NAME

Firefox::Marionette - Automate the Firefox browser with the Marionette protocol

VERSION

Version 1.01

SYNOPSIS

use Firefox::Marionette();
use v5.10;

my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');

say $firefox->find_tag('title')->property('innerHTML'); # same as $firefox->title();

say $firefox->html();

$firefox->find_class('container-fluid')->find_id('search-input')->type('Test::More');

say "Height of search box is " . $firefox->find_class('container-fluid')->css('height');

my $file_handle = $firefox->selfie();

$firefox->find('//button[@name="lucky"]')->click();

$firefox->await(sub { $firefox->interactive() && $firefox->find_partial('Download') })->click();

DESCRIPTION

This is a client module to automate the Mozilla Firefox browser via the Marionette protocol

SUBROUTINES/METHODS

accept_alert

accepts a currently displayed modal message box

accept_connections

Enables or disables accepting new socket connections. By calling this method with false the server will not accept any further connections, but existing connections will not be forcible closed. Use true to re-enable accepting connections.

Please note that when closing the connection via the client you can end-up in a non-recoverable state if it hasn't been enabled before.

active_element

returns the active element of the current browsing context's document element, if the document element is non-null.

add_cookie

accepts a single cookie object as the first parameter and adds it to the current cookie jar. This method returns itself to aid in chaining methods.

add_header

accepts a hash of HTTP headers to include in every future HTTP Request.

use Firefox::Marionette();
use UUID();

my $firefox = Firefox::Marionette->new();
my $uuid = UUID::uuid();
$firefox->add_header( 'Track-my-automated-tests' => $uuid );
$firefox->go('https://metacpan.org/');

these headers are added to any existing headers. To clear headers, see the delete_header method

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new()->delete_header( 'Accept' )->add_header( 'Accept' => 'text/perl' )->go('https://metacpan.org/');

will only send out an Accept header that looks like Accept: text/perl.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new()->add_header( 'Accept' => 'text/perl' )->go('https://metacpan.org/');

by itself, will send out an Accept header that may resemble Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8, text/perl. This method returns itself to aid in chaining methods.

add_site_header

accepts a host name and a hash of HTTP headers to include in every future HTTP Request that is being sent to that particular host.

use Firefox::Marionette();
use UUID();

my $firefox = Firefox::Marionette->new();
my $uuid = UUID::uuid();
$firefox->add_site_header( 'metacpan.org', 'Track-my-automated-tests' => $uuid );
$firefox->go('https://metacpan.org/');

these headers are added to any existing headers going to the metacpan.org site, but no other site. To clear site headers, see the delete_site_header method

addons

returns if pre-existing addons (extensions/themes) are allowed to run. This will be true for Firefox versions less than 55, as -safe-mode cannot be automated.

alert_text

Returns the message shown in a currently displayed modal message box

alive

This method returns true or false depending on if the Firefox process is still running.

application_type

returns the application type for the Marionette protocol. Should be 'gecko'.

async_script

accepts a scalar containing a javascript function that is executed in the browser. This method returns itself to aid in chaining methods.

The executing javascript is subject to the script timeout, which, by default is 30 seconds.

attribute

accepts an element as the first parameter and a scalar attribute name as the second parameter. It returns the initial value of the attribute with the supplied name. This method will return the initial content, the property method will return the current content.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');
my $element = $firefox->find_id('search_input');
!defined $element->attribute('value') or die "attribute is not defined!");
$element->type('Test::More');
!defined $element->attribute('value') or die "attribute is still not defined!");

await

accepts a subroutine reference as a parameter and then executes the subroutine. If a not found exception is thrown, this method will sleep for sleep_time_in_ms milliseconds and then execute the subroutine again. When the subroutine executes successfully, it will return what the subroutine returns.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new(sleep_time_in_ms => 5)->go('https://metacpan.org/');

$firefox->find_id('search-input')->type('Test::More');

$firefox->find_name('lucky')->click();

$firefox->await(sub { $firefox->interactive() && $firefox->find_partial('Download') })->click();

back

causes the browser to traverse one step backward in the joint history of the current browsing context. The browser will wait for the one step backward to complete or the session's page_load duration to elapse before returning, which, by default is 5 minutes. This method returns itself to aid in chaining methods.

browser_version

This method returns version of firefox.

bye

accepts a subroutine reference as a parameter and then executes the subroutine. If the subroutine executes successfully, this method will sleep for sleep_time_in_ms milliseconds and then execute the subroutine again. When a not found exception is thrown, this method will return itself to aid in chaining methods.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');

$firefox->find_id('search-input')->type('Test::More');

$firefox->find_name('lucky')->click();

$firefox->bye(sub { $firefox->find_name('lucky') })->await(sub { $firefox->interactive() && $firefox->find_partial('Download') })->click();

capabilities

returns the capabilities of the current firefox binary. You can retrieve timeouts or a proxy with this method.

child_error

This method returns the $? (CHILD_ERROR) for the Firefox process, or undefined if the process has not yet exited.

chrome_window_handle

returns an server-assigned integer identifiers for the current chrome window that uniquely identifies it within this Marionette instance. This can be used to switch to this window at a later point. This corresponds to a window that may itself contain tabs.

chrome_window_handles

returns identifiers for each open chrome window for tests interested in managing a set of chrome windows and tabs separately.

clear

accepts a element as the first parameter and clears any user supplied input

click

accepts a element as the first parameter and sends a 'click' to it. The browser will wait for any page load to complete or the session's page_load duration to elapse before returning, which, by default is 5 minutes. The click method is also used to choose an option in a select dropdown.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new(visible => 1)->go('https://ebay.com');
my $select = $firefox->find_tag('select');
foreach my $option ($select->find_tag('option')) {
    if ($option->property('value') == 58058) { # Computers/Tablets & Networking
        $option->click();
    }
}

close_current_chrome_window_handle

closes the current chrome window (that is the entire window, not just the tabs). It returns a list of still available chrome window handles. You will need to switch_to_window to use another window.

close_current_window_handle

closes the current window/tab. It returns a list of still available window/tab handles.

context

accepts a string as the first parameter, which may be either 'content' or 'chrome'. It returns the context type that is Marionette's current target for browsing context scoped commands.

use Firefox::Marionette();
use v5.10;

my $firefox = Firefox::Marionette->new();
my $old_context = $firefox->context('chrome');
$firefox->script(...); # running script in chrome context
$firefox->context($old_context);

cookies

returns the contents of the cookie jar in scalar or list context.

use Firefox::Marionette();
use v5.10;

my $firefox = Firefox::Marionette->new()->go('https://github.com');
foreach my $cookie ($firefox->cookies()) {
    if (defined $cookie->same_site()) {
        say "Cookie " . $cookie->name() . " has a SameSite of " . $cookie->same_site();
    } else {
        warn "Cookie " . $cookie->name() . " does not have the SameSite attribute defined";
    }
}

css

accepts an element as the first parameter and a scalar CSS property name as the second parameter. It returns the value of the computed style for that property.

use Firefox::Marionette();
use v5.10;

my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');
say $firefox->find_id('search-input')->css('height');

current_chrome_window_handle

see chrome_window_handle.

delete_cookie

deletes a single cookie by name. Accepts a scalar containing the cookie name as a parameter. This method returns itself to aid in chaining methods.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new()->go('https://github.com');
foreach my $cookie ($firefox->cookies()) {
    warn "Cookie " . $cookie->name() . " is being deleted";
    $firefox->delete_cookie($cookie->name());
}
foreach my $cookie ($firefox->cookies()) {
    die "Should be no cookies here now";
}

delete_cookies

here be cookie monsters! This method returns itself to aid in chaining methods.

delete_header

accepts a list of HTTP header names to delete from future HTTP Requests.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new();
$firefox->delete_header( 'User-Agent', 'Accept', 'Accept-Encoding' );

will remove the User-Agent, Accept and Accept-Encoding headers from all future requests

This method returns itself to aid in chaining methods.

delete_session

deletes the current WebDriver session.

delete_site_header

accepts a host name and a list of HTTP headers names to delete from future HTTP Requests.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new();
$firefox->delete_header( 'metacpan.org', 'User-Agent', 'Accept', 'Accept-Encoding' );

will remove the User-Agent, Accept and Accept-Encoding headers from all future requests to metacpan.org.

This method returns itself to aid in chaining methods.

developer

returns true if the current version of firefox is a developer edition (does the minor version number end with an 'b\d+'?) version.

dismiss_alert

dismisses a currently displayed modal message box

download

accepts a filesystem path and returns a matching filehandle. This is trivial for locally running firefox, but sufficiently complex to justify the method for a remote firefox running over ssh.

use Firefox::Marionette();
use v5.10;

my $firefox = Firefox::Marionette->new( host => '10.1.2.3' )->go('https://metacpan.org/');

$firefox->find_class('container-fluid')->find_id('search-input')->type('Test::More');

$firefox->find('//button[@name="lucky"]')->click();

$firefox->await(sub { $firefox->interactive() && $firefox->find_partial('Download') })->click();

while(!$firefox->downloads()) { sleep 1 }

foreach my $path ($firefox->downloads()) {

    my $handle = $firefox->download($path);

    # do something with downloaded file handle

}

downloading

returns true if any files in downloads end in .part

use Firefox::Marionette();
use v5.10;

my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');

$firefox->find_class('container-fluid')->find_id('search-input')->type('Test::More');

$firefox->find('//button[@name="lucky"]')->click();

$firefox->await(sub { $firefox->interactive() && $firefox->find_partial('Download') })->click();

while(!$firefox->downloads()) { sleep 1 }

while($firefox->downloading()) { sleep 1 }

foreach my $path ($firefox->downloads()) {
    say $path;
}

downloads

returns a list of file paths (including partial downloads) of downloads during this Firefox session.

use Firefox::Marionette();
use v5.10;

my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');

$firefox->find_class('container-fluid')->find_id('search-input')->type('Test::More');

$firefox->find('//button[@name="lucky"]')->click();

$firefox->await(sub { $firefox->interactive() && $firefox->find_partial('Download') })->click();

while(!$firefox->downloads()) { sleep 1 }

foreach my $path ($firefox->downloads()) {
    say $path;
}

error_message

This method returns a human readable error message describing how the Firefox process exited (assuming it started okay). On Win32 platforms this information is restricted to exit code.

execute

This utility method executes a command with arguments and returns STDOUT as a chomped string. It is a simple method only intended for the Firefox::Marionette::* modules.

find

accepts an xpath expression as the first parameter and returns the first element that matches this expression.

This method is subject to the implicit timeout, which, by default is 0 seconds.

use Firefox::Marionette();

my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');

$firefox->find('//input[@id="search-input"]')->type('Test::More');

# OR in list context 

foreach my $element ($firefox->find('//input[@id="search-input"]')) {
    $element->type('Test::More');
}