NAME
Playwright - Perl client for Playwright
VERSION
version 1.401
SYNOPSIS
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.DESCRIPTION
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.
Getting Started
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.
Node Versions
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:
From there it's recommended you use the latest version of node:
nvm install node
nvm use nodeDocumentation for Playwright Subclasses
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.
Scripts
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.
example of evaluate()
# 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;');Asynchronous operations
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();Getting Object parents
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};Chrome Specific features
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=Y4BBAD4B3AD00This 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.
Firefox Specific concerns
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 } );Leaving browsers alive for manual debugging
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.
Running multiple clients against the same playwright server
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.
Running against remote playwright servers
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.
Taking videos, Making Downloads
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).
Doing arbitrary requests
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.
Differences in behavior from Selenium::Remote::Driver
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).
Perl equivalents for playwright-test
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.
Annotations
https://playwright.dev/docs/test-annotations/
Both Test::More and Test2::V0 provide an equivalent to all the annotations but slow():
- skip or fixme - Test::More::skip or Test2::Tools::Basic::skip handle both needs
- fail - Test::More TODO blocks and Test2::Tools::Basic::todo
- slow - Has no equivalent off the shelf. Playwright::pusht() and Playwright::popt() are here to help.
-
# 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.
Assertions
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.
Authentication
Much of the callback functionality used in these sections is provided by Test::Class and it's fixtures.
Command Line
Both prove and yath have similar functionality, save for retrying flaky tests. That said, you shouldn't do that; good tests don't flake.
Configuration
All the configuration here can simply be passed to launch(), newPage() or other methods directly.
Page Objects
This is basically what Test::Class was written for specifically; so that you could subclass testing of common components across pages.
Parallelizing Tests
Look into Test::Class::Moose's Parallel runmode, prove's -j option, or Test2::Aggregate.
Reporters
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.
Test Retry
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.
Visual Comparisons
Use Image::Compare.
Advanced Configuration
This yet again can be handled when instantiating the various playwright objects.
Fixtures
Test::Class and it's many variants cover the subject well.
INSTALLATION NOTE
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!
CONSTRUCTOR
new(HASH) = (Playwright)
Creates a new browser and returns a handle to interact with it.
INPUT
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: trueMETHODS
launch(HASH) = Playwright::Browser
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'.
server (HASH) = MIXED
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 callThe 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.
await (HASH) = Object
Waits for an asynchronous operation returned by the waitFor* methods to complete and returns the value.
pusht(Playwright::Page, INTEGER timeout, BOOL navigation) = null
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.
popt(Playwright::Page, BOOL navigation) = null
The counterpart to pusht() which returns the timeout value to it's previous value.
try_until(Object, STRING method, LIST args), try_until_die(...)
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().
quit, DESTROY
Terminate the browser session and wait for the Playwright server to terminate.
Automatically called when the Playwright object goes out of scope.
BUGS
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.
AUTHORS
Current Maintainers:
George S. Baugh <teodesian@gmail.com>
CONTRIBUTORS
reneeb <info@perl-services.de>
Yanick Champoux <yanick.champoux@iinteractive.com>
COPYRIGHT AND LICENSE
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.