Selenium::Client - Module for communicating with WC3 standard selenium servers
version 2.00
Either connects to a driver at the specified host and port, or spawns one locally.
Spawns a server on a random port in the event the host is "localhost" (or 127.0.0.1) and nothing is reachable on the provided port.
Returns a Selenium::Client object with all WC3 methods exposed.
To view all available methods and their documentation, the catalog() method is provided.
Remote Server options:
version
Default: stable
host
Default: localhost
prefix
Default: ''
port
Default: 4444 Note: when spawning, this will be ignored and a random port chosen instead.
scheme
Default: http
nofetch
Default: 1
client_dir
Default: ~/.selenium
debug
Default: false
auto_close
Only turn this off when you are debugging.
Default: true
normalize
If another normal form is preferred, you should turn this off and directly use Unicode::Normalize.
post_callbacks
Callbacks are passed $self, an HTTP::Tiny response hashref and the request hashref. Use this to implement custom error handlers, testing harness modifications etc.
Return a truthy value to immediately exit the request subroutine after all cbs are executed. Truthy values (if any are returned) are returned in order encountered.
fatal
Useful to turn off when using post_callbacks as error handlers.
When using remote servers, you should take extra care that they automatically clean up after themselves. We cannot guarantee the state of said servers after interacting with them.
Spawn Options:
driver
Included are 'Auto', 'SeleniumHQ::Jar', 'Gecko', 'Chrome', 'Edge' Default: Auto
The 'Auto' Driver will pick whichever direct driver looks like it will work for your chosen browser. If we can't find one, we'll fall back to SeleniumHQ::Jar.
browser
Default: Blank
headless
Default: True
driver_version
Blank and Partial versions will return the latest sub-version available. Only relevant to Drivers which auto-download (currently only SeleniumHQ::Jar).
Driver modules should be in the Selenium::Driver namespace. They may implement additional parameters which can be passed into the options hash.
This means that the Selenium::Client class can directly call all selenium methods. We provide a variety of subclasses as sugar around this:
Selenium::Session Selenium::Capabilities Selenium::Element
Which will simplify correctly passing arguments in the case of sessions and elements. However, this does not change the fact that you still must take great care. We do no validation whatsoever of the inputs, and the selenium server likes to hang when you give it an invalid input. So take great care and understand this is what "script hung and died" means -- you passed the function an unrecognized argument.
This is because Selenium::Specification cannot (yet!) parse the inputs and outputs for each endpoint at this time. As such we can't just filter against the relevant prototype.
In any case, all subs will look like this, for example:
$client->Method( key => value, key1 => value1, ...) = (@return_per_key)
The options passed in are basically JSON serialized and passed directly as a POST body (or included into the relevant URL). We return a list of items which are a hashref per item in the result (some of them blessed). For example, NewSession will return a Selenium::Capabilities and Selenium::Session object. The order in which they are returned will be ordered alphabetically.
By default, we will pass a set of capabilities that satisfy the options passed to new().
If you want *other* capabilities, pass them directly to NewSession as documented in the WC3 spec.
However, this will ignore what you passed to new(). Caveat emptor.
For the general list of options supported by each browser, see here:
Firefox
Chrome
Edge
Safari
Returns the entire method catalog. Prints out every method and a link to the relevant documentation if verbose is true.
Returned as first element from NewSession(). Query this object for various things about the server capabilities.
Returned as second element of NewSession(). Has a destructor which will automatically clean itself up when we go out of scope. Alternatively, when the driver object goes out of scope, all sessions it spawned will be destroyed.
You can call Selenium methods on this object which require a sessionid without passing it explicitly.
Returned from find element calls.
You can call Selenium methods on this object which require a sessionid and elementid without passing them explicitly.
There are a variety of quirks with Selenium drivers that you just have to put up with, don't log bugs on these behaviors. Most of this will probably change in the future, as these are firmly in the "undefined/undocumented behavior" stack of the browser vendors.
If you have an alert() open on the page, all calls to the selenium server will 500 until you dismiss or accept it.
Also be aware that chrome will re-fire alerts when you do a forward() or back() event, unlike firefox.
Safari returns ALLCAPS names for tags. amazing
Many valid properties/attributes will never be accessible via GetProperty() or GetAttribute().
For example, getting the "for" value of a <label> element is flat-out impossible using either GetProperty or GetAttribute. There are many other such cases, the most common being "non-standard" properties such as aria-* or things used by JS templating engines. You are better off using JS shims to do any element inspection.
Similarly the IsElementSelected() method is quite unreliable. We can work around this however by just using the CSS :checked pseudoselector when looking for elements, as that actually works.
It is this for these reasons that you should consider abandoning Selenium for something that can actually do this correctly such as Playwright.
When closing windows, be aware you will be NOT be shot back to the last window you had focused before switching to the current one. You have to manually switch back to an existing one.
Opening _blank targeted links *does not* automatically switch to the new window. The procedure for handling links of such a sort to do this is as follows:
# Get current handle my $handle = $session->GetWindowHandle(); # Assuming the element is an href with target=_blank ... $element->ClickElement(); # Get all handles and filter for the ones that we aren't currently using my @handles = $session->GetWindowHandles(); my @new_handles = grep { $handle != $_ } @handles; # Use pop() as it will always be returned in the order windows are opened $session->SwitchToWindow( handle => pop(@new_handles) );
Different browser drivers also handle window handles differently. Chrome in particular demands you stringify handles returned from the driver. It also seems to be a lot less cooperative than firefox when setting the WindowRect.
In the SwitchToFrame documentation, the claim is made that passing the element ID of a <frame> or <iframe> will switch the browsing context of the session to that frame. This is quite obviously false in every driver known. Example:
# This does not ever work $session->SwitchToFrame( id => $session->FindElement( using => 'css selector', value => '#frame' )->{elementid} );
The only thing that actually works is switching by array index as you would get from window.frames in javascript:
# Supposing #frame is the first frame encountered in the DOM, this works $session->SwitchToFrame( id => 0 );
As you might imagine this is a significant barrier to reliable automation as not every JS interperter will necessarily index in the same order. Nor is there, say, a GetFrames() method from which you could sensibly pick which one you want and move from there. The only workaround here would be to always execute a script to interrogate window.frames and guess which one you want based on the output of that.
If you make a request of the server with arguments it does not understand it will hang for 30s, so set a SIGALRM handler if you insist on doing so.
The default version of the Java JRE from java.com is quite simply ancient on windows, and SeleniumHQ develops against JDK 11 and better. So make sure your JDK bin dir is in your PATH before the JRE path (or don't install an ancient JRE lol)
If you don't, you'll probably get insta-explosions due to their usage of new language features. Kind of like how you'll die if you use a perl without signatures with this module :)
Also, due to perl pseudo-forks hanging forever if anything is ever waiting on read() in windows, we don't fork to spawn binaries. Instead we use start to open a new cmd.exe window, which will show up in your task tray. Don't close this or your test will fail for obvious reasons.
start
This also means that if you have to send ^C (SIGTERM) to your script or exit() prematurely, said window may be left dangling, as these behave a lot more like POSIX::_exit() does on unix systems.
The JSON responses from the selenium server are decoded as UTF-8, as per the Selenium standard. As a convenience, we automatically apply NFC to output via Unicode::Normalize, which can be disabled by passing normalize=0 to the constructor. If you are comparing output from selenium calls against UTF-8 glyphs, `use utf8`, `use feature qw{unicode_strings}` and normalization is strongly suggested.
George S. Baugh <george@troglodyne.net>
This software is Copyright (c) 2023 by George S. Baugh.
This is free software, licensed under:
The MIT (X11) License
To install Selenium::Subclass, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Selenium::Subclass
CPAN shell
perl -MCPAN -e shell install Selenium::Subclass
For more information on module installation, please visit the detailed CPAN module installation guide.