NAME
WebDriver::Tiny - Selenium 2.0 bindings for Perl
SYNOPSIS
use WebDriver::Tiny;
my $drv = WebDriver::Tiny->new;
# Go to Google.
$drv->get('https://www.google.co.uk');
# Type into the search box 'p', 'e', 'r', 'l', <RETURN>.
$drv->('input[name=q]')->send_keys("perl\N{WD_RETURN}");
# Click the first perl result (perl.org).
$drv->('h3.r > a')->click;
# Save a screenshot of the page.
$drv->screenshot('/tmp/perl.org.png');DESCRIPTION
Selenium automates browsers. That's it! What you do with that power is entirely up to you. Primarily, it is for automating web applications for testing purposes, but is certainly not limited to just that. Boring web-based administration tasks can (and should!) also be automated as well.
Selenium has the support of some of the largest browser vendors who have taken (or are taking) steps to make Selenium a native part of their browser. It is also the core technology in countless other browser automation tools, APIs and frameworks.
WARNING: The API of this module is unstable and may change without warning (any change will be appropriately documented in the changelog).
USAGE
The usage of this module varies greatly depending on which backend your're targetting, below are some examples:
ChromeDriver
my $drv = WebDriver::Tiny->new(
capabilities => { chromeOptions => { binary => '/usr/bin/google-chrome' } },
port => 9515,
);geckodriver
On the command line:
geckodriverIn Perl code:
my $drv = WebDriver::Tiny->new(
capabilities => { 'moz:firefoxOptions' => { args => ['-headless'] } },
port => 4444,
);PhantomJS
On the command line:
phantomjs -wIn Perl code:
my $drv = WebDriver::Tiny->new( port => 8910 );Selenium
my $drv = WebDriver::Tiny->new(
capabilities => { browserName => 'firefox' },
path => '/wd/hub',
port => 4444,
);IMPORT
This module imports custom charnames for sending keys that would otherwise be hard to represent in text. Each code point falls inside the Unicode Private Use Area (U+E000–U+F8FF), and are as follows:
WD_NULL
WD_CANCEL
WD_HELP
WD_BACK_SPACE
WD_TAB
WD_CLEAR
WD_RETURN
WD_ENTER
WD_SHIFT
WD_CONTROL
WD_ALT
WD_PAUSE
WD_ESCAPE
WD_SPACE
WD_PAGE_UP
WD_PAGE_DOWN
WD_END
WD_HOME
WD_ARROW_LEFT
WD_ARROW_UP
WD_ARROW_RIGHT
WD_ARROW_DOWN
WD_INSERT
WD_DELETE
WD_SEMICOLON
WD_EQUALS
WD_NUMPAD0
WD_NUMPAD1
WD_NUMPAD2
WD_NUMPAD3
WD_NUMPAD4
WD_NUMPAD5
WD_NUMPAD6
WD_NUMPAD7
WD_NUMPAD8
WD_NUMPAD9
WD_MULTIPLY
WD_ADD
WD_SEPARATOR
WD_SUBTRACT
WD_DECIMAL
WD_DIVIDE
WD_F1
WD_F2
WD_F3
WD_F4
WD_F5
WD_F6
WD_F7
WD_F8
WD_F9
WD_F10
WD_F11
WD_F12
WD_META
WD_COMMAND
WD_ZENKAKU_HANKAKU
METHODS
Driver
new
my $drv = WebDriver::Tiny->new(
base_url => ...,
host => 'localhost',
port => 4444,
);Constructs an instance of this class.
base_url
my $base_url = $drv->base_url;
$drv->base_url($base_url);Accessor to get/set the base_url after instantiation.
Actions
find
my @array_of_elements $drv->find('.class');
my $elements = $drv->find( '#id', %args );Return a collection of matched elements found in the DOM based on passed argument(s). Always returns a collection of WebDriver::Tiny::Elements (sometimes containing no elements), in list context it will return an array of collections, each containing one element.
Due to find being the most common method invoked, the method name can be dropped altogether like so:
$drv->('#foo');
$drv->('.bar');Accepts a mandatory selector parameter and zero or more of the following key/value options:
- dies
-
Whether
finddies if it fails to find any elements. Defaults to true. - method
-
The matching pattern to use with the given selector - css, ecmascript, link_text, partial_link_text, or xpath. Defaults to 'css'.
- sleep
-
How long to sleep before a reattempt of an unsuccessful match. Defaults to 0.1 seconds.
- tries
-
Maximum number of attempts to try and find a match. Defaults to 5.
Alerts
alert_accept
$drv->alert_accept;alert_dismiss
$drv->alert_dismiss;alert_text
my $text = $drv->alert_text;Cookies
cookie
# Get cookie "foo".
my $cookie = $drv->cookie('foo');
# Set cookie "foo".
$drv->cookie( foo => 'value' );
# Or
$drv->cookie(
foo => 'value',
domain => 'example.com',
expires => 123,
httponly => 0,
secure => 1,
);cookie_delete
# Delete all cookies.
$drv->cookie_delete;
# Delete cookie "foo".
$drv->cookie_delete('foo');
# Delete cookie "bar", and "baz".
$drv->cookie_delete(qw/bar baz/);cookies
# Get a hashref of all cookies.
my $cookies = $drv->cookies;JavaScript
js
my $return = $drv->js('return "foo"');js_async
my $return = $drv->js_async(<<'JS');
let callback = arguments[0];
callback("bar");
JSNavigation
back
$drv->back;forward
$drv->forward;get
$drv->get($url);refresh
$drv->refresh;Properties
capabilities
Hash of the capabilities of the current session.
html
Get the source code of the current page.
orientation
my $orientation = $drv->orientation;
$drv->orientation($orientation);status
my $status = $drv->status;title
my $title = $drv->title;url
my $url = $drv->url;Get the URL of the current page.
user_agent
my $user_agent = $drv->user_agent;Window Management
screenshot
my $png_blob = $drv->screenshot;
$drv->screenshot('/tmp/foo.png');window
my $handle = $drv->window;windows
my $handles = $drv->windows;window_close
$drv->window_close;Close the current window.
window_fullscreen
$drv->window_fullscreen;window_maximize
$drv->window_maximize; # Maximize current window.
$drv->window_maximize('current'); # Same as above.
$drv->window_maximize('foo'); # Maximize window "foo".window_rect
The following gets the current window's size and position, returning a hashref with keys for width and height and coordinates x and y.
my $window = $drv->window_rect; # Get size and position of current window.The following sets the current window's size and position, returning $self to allow chaining.
$drv->window_rect( 640, 480, 10, 20 ); # Set size and position of current window.window_switch
$drv->window_switch($handle);SEE ALSO
ACKNOWLEDGEMENTS
Thanks to James Raspass for the original design and implementation.
COPYRIGHT AND LICENSE
Copyright © 2018-2021 CV-Library Ltd.
This is free software; you can redistribute it and/or modify it under the same terms as Perl itself.