Playwright - Perl client for Playwright
version 1.401
use Playwright; my $handle = Playwright->new(); my $browser = $handle->launch( headless => 0, type => 'chrome' ); my $page = $browser->newPage(); my $res = $page->goto('http://somewebsite.test', { waitUntil => 'networkidle' }); my $frameset = $page->mainFrame(); my $kidframes = $frameset->childFrames(); # Grab us some elements my $body = $page->select('body'); # You can also get the innerText my $text = $body->textContent(); $body->click(); $body->screenshot(); my $kids = $body->selectMulti('*'); #Alternatively, use the new locator API instead of select/selectMulti: my $loc = $page->locator('body'); my $innerTubes = $loc->allInnerTexts(); print Dumper($innerTubes); # See a more full exploration of the API in example.pl on github.
Perl interface to a lightweight node.js webserver that proxies commands runnable by Playwright. Checks and automatically installs a copy of the node dependencies in the local folder if needed.
Currently understands commands you can send to all the playwright classes defined in api.json (installed wherever your OS puts shared files for CPAN distributions).
See https://playwright.dev/versions and drill down into your relevant version (run `npm list playwright` ) for what the classes do, and their usage.
All the classes mentioned there will correspond to a subclass of the Playwright namespace. For example:
# ISA Playwright my $playwright = Playwright->new(); # ISA Playwright::BrowserContext my $ctx = $playwright->newContext(...); # ISA Playwright::Page my $page = $ctx->newPage(...); # ISA Playwright::ElementHandle my $element = $ctx->select('body');
See example.pl for a more thoroughly fleshed-out display on how to use this module.
When using the playwright module for the first time, you may be told to install node.js libraries. It should provide you with instructions which will get you working right away.
However, depending on your node installation this may not work due to dependencies for node.js not being in the expected location. To fix this, you will need to update your NODE_PATH environment variable to point to the correct location.
playwright itself tends to need the latest version of node to work properly. It is recommended that you use nvm to get a hold of this:
https://github.com/nvm-sh/nvm
From there it's recommended you use the latest version of node:
nvm install node nvm use node
The documentation and names for the subclasses of Playwright follow the spec strictly:
Playwright::BrowserContext => https://playwright.dev/docs/api/class-browsercontext Playwright::Page => https://playwright.dev/docs/api/class-page Playwright::ElementHandle => https://playwright.dev/docs/api/class-elementhandle
...And so on. These classes are automatically generated during module build based on the spec hash built by playwright. See generate_api_json.sh and generate_perl_modules.pl if you are interested in how this sausage is made.
You can check what methods are installed for each subclass by doing the following:
use Data::Dumper; print Dumper($instance->{spec});
There are two major exceptions in how things work versus the upstream Playwright documentation, detailed below in the Selectors section.
Selectors
The selector functions have to be renamed from starting with $ for obvious reasons. The renamed functions are as follows:
These functions are present as part of the Page, Frame and ElementHandle classes.
The evaluate() and evaluateHandle() functions can only be run in string mode. To maximize the usefulness of these, I have wrapped the string passed with the following function:
const fun = new Function (toEval); args = [ fun, ...args ];
As such you can effectively treat the script string as a function body. The same restriction on only being able to pass one arg remains from the upstream: https://playwright.dev/docs/api/class-page#pageevalselector-pagefunction-arg
You will have to refer to the arguments array as described here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/arguments
You can also pass Playwright::ElementHandle objects as returned by the select() and selectMulti() routines. They will be correctly translated into DOMNodes as you would get from the querySelector() javascript functions.
Calling evaluate() and evaluateHandle() on Playwright::Element objects will automatically pass the DOMNode as the first argument to your script. See below for an example of doing this.
# Read the console $page->on('console',"return [...arguments]"); my $promise = $page->waitForEvent('console'); #TODO This request can race, the server framework I use to host the playwright spec is *not* FIFO (YET) sleep 1; $page->evaluate("console.log('hug')"); my $console_log = $handle->await( $promise ); print "Logged to console: '".$console_log->text()."'\n"; # Convenient usage of evaluate on ElementHandles # We pass the element itself as the first argument to the JS arguments array for you $element->evaluate('arguments[0].style.backgroundColor = "#FF0000"; return 1;');
The waitFor* methods defined on various classes fork and exec, waiting on the promise to complete. You will need to wait on the result of the backgrounded action with the await() method documented below.
# Assuming $handle is a Playwright object my $async = $page->waitForEvent('console'); $page->evaluate('console.log("whee")'); my $result = $handle->await( $async ); my $logged = $result->text();
Some things, like elements naturally are children of the pages in which they are found. Sometimes this can get confusing when you are using multiple pages, especially if you let the ref to the page go out of scope. Don't worry though, you can access the parent attribute on most Playwright::* objects:
# Assuming $element is a Playwright::ElementHandle my $page = $element->{parent};
You can pass the parameter 'cdp_uri' to the constructor to connect to a running browser with a ChromeDevTools server running. Example:
ws://wegotussomebrowsers.test:666?user=fred&token=Y4BBAD4B3AD00
This appears to be what the large scale playwright-as-a-service shops are using to expose browsers to their customers.
For the curious as to how this actually works:
Similar to the playwright_server binary this module ships, they use some kind of web service to wrap browser.newBrowserCDPSession(). Alternatively, they wrap running `chromium-browser --remote-debugging-port=7779311` instead of touching pw, because complexity demon BAD. See the CDP: block in example.pl with this distribution (read: in the TLD of its repo) for how to do precisely that.
It's nothing all that complicated, other than the hulking swarm of services which integrate that into a userland that can charge your credit card! Oh, and monitoring/balancing/scaling it all so that it doesn't fall over because you crammed 10 billion clients onto one box. Gotta stay right on the edge of utilization madness, that's the sweet spot as far as margin is concerned.
By default, firefox will open PDFs in a pdf.js window. To suppress this behavior (such as in the event you are await()ing a download event), you will have to pass this option to launch():
# Assuming $handle is a Playwright object my $browser = $handle->launch( type => 'firefox', firefoxUserPrefs => { 'pdfjs.disabled' => JSON::true } );
Passing the cleanup => 0 parameter to new() will prevent DESTROY() from cleaning up the playwright server when a playwright object goes out of scope.
Be aware that this will prevent debug => 1 from printing extra messages from playwright_server itself, as we redirect the output streams in this case so as not to fill your current session with prints later.
A convenience script has been provided to clean up these orphaned instances, `reap_playwright_servers` which will kill all extant `playwright_server` processes.
To save on memory, this is a good idea. Pass the 'port' argument to the constructor, and we'll re-use anything listening on that port locally, and be sure to use it when starting up.
This will also set the cleanup flag to false, so be sure you run `reap_playwright_servers` when you are sure that all testing on this server is done.
Pass the 'host' along with the 'port' argument to the constructor in order to use an instance of playwright_server running on another host. This will naturally set the cleanup flag to false; it is the server operator's responsibility to reap the server when complete.
A systemd service file, and Makefile are provided in the service/ folder of this module's git repository which will install playwright_server as a user-mode service on the PORT variable.
We spawn browsers via BrowserType.launchServer() and then connect to them over websocket. This means you can't just set paths up front and have videos recorded, the Video.path() method will throw. Instead you will need to call the Video.saveAs() method after closing a page to record video:
# Do stuff ... # Save video my $video = $page->video; $page->close(); $video->saveAs('video/example.webm');
It's a similar story with Download classes:
# Do stuff ... # Wait on Download my $promise = $page->waitForEvent('download') # Do some thing triggering a download ... my $download = $handle->await( $promise ); $download->saveAs('somefile.extension');
Remember when doing an await() with playwright-perl you are waiting on a remote process on a server to complete, which can time out. You may wish to spawn a subprocess using a different tool to download very large files. If this is not an option, consider increasing the timeout on the LWP object used by the Playwright object (it's the 'ua' member of the class).
When you either want to test APIs (or not look like a scraper/crawler) you'll want to issue arbitrary requests, such as POST/HEAD/DELETE et cetera. Here's how you go about that:
print "HEAD http://google.com : \n"; my $fr = $page->request(); my $resp = $fr->fetch("http://google.com", { method => "HEAD" }); print Dumper($resp->headers()); print "200 OK\n" if $resp->status() == 200;
The request() method will give you a Playwright::APIRequestContext object, which you can then call whichever methods you like upon. When you call fetch (or get, post, etc) you will then be returned a Playwright::APIResponse object.
By default selenium has its selector methods obeying a timeout and waits for an element to appear. It then explodes when and element can't be found.
To replicate this mode of operation, we have provided the try_until helper:
# Args are $object, $method, @args my $element = Playwright::try_until($page, 'select', $selector) or die ...;
This will use the timeouts described by pusht/popt (see below).
This section is intended to be read alongside the playwright-test documentation to aid understanding of common browser testing techniques. The relevant documentation section will be linked for each section.
https://playwright.dev/docs/test-annotations/
Both Test::More and Test2::V0 provide an equivalent to all the annotations but slow():
# Examples assume you have a $page object. # Timeouts are in milliseconds Playwright::pusht($page,5000); # Do various things... ... Playwright::popt($page);
See https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout for more on setting default timeouts in playwright. By default we assume the timeout to be 30s.
As with before, most of the functionality here is satisfied with perl's default testing libraries. In particular, like() and cmp_bag() will do most of what you want here.
Much of the callback functionality used in these sections is provided by Test::Class and it's fixtures.
Both prove and yath have similar functionality, save for retrying flaky tests. That said, you shouldn't do that; good tests don't flake.
prove
yath
All the configuration here can simply be passed to launch(), newPage() or other methods directly.
This is basically what Test::Class was written for specifically; so that you could subclass testing of common components across pages.
Look into Test::Class::Moose's Parallel runmode, prove's -j option, or Test2::Aggregate.
When using prove, consider Test::Reporter coupled with App::Prove::Plugins using custom TAP::Formatters. Test2 as of this writing (October 2012) supports formatters and plugins, but no formatter plugins have been uploaded to CPAN. See Test2::Manual::Tooling::Formatter on writing a formatter yourself, and then a Test2::Plugin using it.
prove supports tests in sequence via the --rules option. It's also got the handy --state options to further micromanage test execution over multiple iterations. You can use this to retry flaking tests, but it's not a great idea in practice.
Use Image::Compare.
This yet again can be handled when instantiating the various playwright objects.
Test::Class and it's many variants cover the subject well.
If you install this module from CPAN, you will likely encounter a croak() telling you to install node module dependencies. Follow the instructions and things should be just fine.
If you aren't, please file a bug!
Creates a new browser and returns a handle to interact with it.
debug (BOOL) : Print extra messages from the Playwright server process. Default: false timeout (INTEGER) : Seconds to wait for the playwright server to spin up and down. Default: 30s cleanup (BOOL) : Whether or not to clean up the playwright server when this object goes out of scope. Default: true
The Argument hash here is essentially those you'd see from browserType.launch(). See: https://playwright.dev/docs/api/class-browsertype#browsertypelaunchoptions
There is an additional "special" argument, that of 'type', which is used to specify what type of browser to use, e.g. 'firefox'.
Call Playwright::BrowserServer methods on the server which launched your browser object.
Parameters:
browser : The Browser object you wish to call a server method upon. command : The BrowserServer method you wish to call
The most common use for this is to get the PID of the underlying browser process:
my $browser = $playwright->launch( browser => chrome ); my $process = $playwright->server( browser => $browser, command => 'process' ); print "Browser process PID: $process->{pid}\n";
BrowserServer methods (at the time of writing) take no arguments, so they are not processed.
Waits for an asynchronous operation returned by the waitFor* methods to complete and returns the value.
Like pushd/popd, but for default timeouts used by a Playwright::Page object and it's children.
If the 'navigation' option is high, we set the NavigationTimeout rather than the DefaultTimeout. By default 'navigation' is false.
If we popt to the bottom of the stack, we will set the timeout back to 1 second.
The counterpart to pusht() which returns the timeout value to it's previous value.
Try to execute the provided method upon the provided Playwright::* object until it returns something truthy. Quits after the timeout (or 1s, if pusht is not used before this) defined on the object is reached.
Use this for methods which *don't* support a timeout option, such as select().
Terminate the browser session and wait for the Playwright server to terminate.
Automatically called when the Playwright object goes out of scope.
Please report any bugs or feature requests on the bugtracker website https://github.com/teodesian/playwright-perl/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Current Maintainers:
George S. Baugh <teodesian@gmail.com>
reneeb <info@perl-services.de>
Yanick Champoux <yanick.champoux@iinteractive.com>
Copyright (c) 2020 Troglodyne LLC
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
To install Playwright, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Playwright
CPAN shell
perl -MCPAN -e shell install Playwright
For more information on module installation, please visit the detailed CPAN module installation guide.