accept_alert

accept_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

add_certificate

• path - a file system path to a single PEM encoded X.509 certificate <https://datatracker.ietf.org/doc/html/rfc7468#section-5>.
• string - a string containg a single PEM encoded X.509 certificate <https://datatracker.ietf.org/doc/html/rfc7468#section-5>
• trust - This is the trustargs <https://www.mankier.com/1/certutil#-t> value for NSS <https://wiki.mozilla.org/NSS>. If defaults to 'C,,';

This method returns itself to aid in chaining methods.

    use Firefox::Marionette();

    my $pem_encoded_string = <<'_PEM_';
    -----BEGIN CERTIFICATE-----
    MII..
    -----END CERTIFICATE-----
    _PEM_
    my $firefox = Firefox::Marionette->new()->add_certificate(string => $pem_encoded_string);

add_cookie

This method throws an exception if you try to add a cookie for a different domain than the current document <https://developer.mozilla.org/en-US/docs/Web/WebDriver/Errors/InvalidCookieDomain>.

add_header

    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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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 <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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_login

• host - The scheme + hostname of the page where the login applies, for example 'https://www.example.org'.
• user - The username for the login.
• password - The password for the login.
• origin - The scheme + hostname that the form-based login was submitted to <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-action>. Forms with no action attribute <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form#attr-action> default to submitting to the URL of the page containing the login form, so that is stored here. This field should be omitted (it will be set to undef) for http auth type authentications and "" means to match against any form action.
• realm - The HTTP Realm for which the login was requested. When an HTTP server sends a 401 result, the WWW-Authenticate header includes a realm. See RFC 2617 <https://datatracker.ietf.org/doc/html/rfc2617>. If the realm is not specified, or it was blank, the hostname is used instead. For HTML form logins, this field should not be specified.
• user_field - The name attribute for the username input in a form. Non-form logins should not specify this field.
• password_field - The name attribute for the password input in a form. Non-form logins should not specify this field.

or a Firefox::Marionette::Login object as the first parameter and adds the login to the Firefox login database.

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

    my $firefox = Firefox::Marionette->new();

    # for http auth logins

    my $http_auth_login = Firefox::Marionette::Login->new(host => 'https://pause.perl.org', user => 'AUSER', password => 'qwerty', realm => 'PAUSE');
    $firefox->add_login($http_auth_login);
    $firefox->go('https://pause.perl.org/pause/authenquery')->accept_alert(); # this goes to the page and submits the http auth popup

    # for form based login

    $firefox->add_login(host => 'https://github.com', origin => 'https://github.com', user => 'me@example.org', password => 'qwerty', user_field => 'login', password_field => 'password');
    my $form_login = Firefox::Marionette::Login(host => 'https://github.com', user => 'me2@example.org', password => 'uiop[]', user_field => 'login', password_field => 'password');

    # or just directly

    $firefox->add_login(host => 'https://github.com', user => 'me2@example.org', password => 'uiop[]', user_field => 'login', password_field => 'password');

This method returns itself to aid in chaining methods.

add_site_header

    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

alert_text

alive

application_type

async_script

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

attribute

    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

    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

debug

default_binary_name

browser_version

bye

    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

certificate_as_pem

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();

    # Generating a ca-bundle.crt to STDOUT from the current firefox instance

    foreach my $certificate (sort { $a->display_name() cmp $b->display_name } $firefox->certificates()) {
        if ($certificate->is_ca_cert()) {
            print '# ' . $certificate->display_name() . "\n" . $firefox->certificate_as_pem($certificate) . "\n";
        }
    }

The ca-bundle-for-firefox command that is provided as part of this distribution does this.

certificates

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

    # Sometimes firefox can neglect old certificates.  See https://bugzilla.mozilla.org/show_bug.cgi?id=1710716

    my $firefox = Firefox::Marionette->new();
    foreach my $certificate (grep { $_->is_ca_cert() && $_->not_valid_after() < time } $firefox->certificates()) {
        say "The " . $certificate->display_name() " . certificate has expired and should be removed";
    }

This method returns itself to aid in chaining methods.

child_error

chrome

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

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

See the context method for an alternative methods for changing the context.

chrome_window_handle

chrome_window_handles

clear

click

    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

close_current_window_handle

content

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

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

See the context method for an alternative methods for changing the context.

context

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

    my $firefox = Firefox::Marionette->new();
    if ($firefox->context() eq 'content') {
       say "I knew that was going to happen";
    }
    my $old_context = $firefox->context('chrome');
    $firefox->script(...); # running script in chrome context
    $firefox->context($old_context);

See the content and chrome methods for alternative methods for changing the context.

cookies

    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

    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

delete_certificate

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

    my $firefox = Firefox::Marionette->new();
    foreach my $certificate ($firefox->certificates()) {
        if ($certificate->is_ca_cert()) {
            $firefox->delete_certificate($certificate);
        } else {
            say "This " . $certificate->display_name() " certificate is NOT a certificate authority, therefore it is not being deleted";
        }
    }
    say "Good luck visiting a HTTPS website!";

This method returns itself to aid in chaining methods.

delete_cookie

    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

delete_header

    use Firefox::Marionette();

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

will remove the User-Agent <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent>, Accept <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept> and Accept-Encoding <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding> headers from all future requests

This method returns itself to aid in chaining methods.

delete_login

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();
    foreach my $login ($firefox->logins()) {
        if ($login->user() eq 'me@example.org') {
            $firefox->delete_login($login);
        }
    }

will remove the logins with the username matching 'me@example.org'.

This method returns itself to aid in chaining methods.

delete_logins

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();
    $firefox->delete_logins();

This method returns itself to aid in chaining methods.

delete_session

delete_site_header

    use Firefox::Marionette();

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

will remove the User-Agent <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent>, Accept <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept> and Accept-Encoding <https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Encoding> headers from all future requests to metacpan.org.

This method returns itself to aid in chaining methods.

developer

dismiss_alert

download

    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

    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

    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

execute

fill_login

    use Firefox::Marionette();
    use IO::Prompt();

    my $firefox = Firefox::Marionette->new();

    my $firefox = Firefox::Marionette->new();

    my $url = 'https://github.com';

    my $user = 'me@example.org';

    my $password = IO::Prompt::prompt(-echo => q[*], "Please enter the password for the $user account when logging into $url:");

    $firefox->add_login(host => $url, user => $user, password => 'qwerty', user_field => 'login', password_field => 'password');

    $firefox->go("$url/login");

    $firefox->fill_login();

find

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');
    }

If no elements are found, a not found exception will be thrown. For the same functionality that returns undef if no elements are found, see the has method.

find_id

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_id('search-input')->type('Test::More');

    # OR in list context 

    foreach my $element ($firefox->find_id('search-input')) {
        $element->type('Test::More');
    }

If no elements are found, a not found exception will be thrown. For the same functionality that returns undef if no elements are found, see the has_id method.

find_name

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_name('q')->type('Test::More');

    # OR in list context 

    foreach my $element ($firefox->find_name('q')) {
        $element->type('Test::More');
    }

If no elements are found, a not found exception will be thrown. For the same functionality that returns undef if no elements are found, see the has_name method.

find_class

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_class('form-control home-search-input')->type('Test::More');

    # OR in list context 

    foreach my $element ($firefox->find_class('form-control home-search-input')) {
        $element->type('Test::More');
    }

If no elements are found, a not found exception will be thrown. For the same functionality that returns undef if no elements are found, see the has_class method.

find_selector

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_selector('input.home-search-input')->type('Test::More');

    # OR in list context 

    foreach my $element ($firefox->find_selector('input.home-search-input')) {
        $element->type('Test::More');
    }

If no elements are found, a not found exception will be thrown. For the same functionality that returns undef if no elements are found, see the has_selector method.

find_tag

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/');
    my $element = $firefox->find_tag('input');

    # OR in list context 

    foreach my $element ($firefox->find_tag('input')) {
        # do something
    }

If no elements are found, a not found exception will be thrown. For the same functionality that returns undef if no elements are found, see the has_tag method.

find_link

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_link('API')->click();

    # OR in list context 

    foreach my $element ($firefox->find_link('API')) {
        $element->click();
    }

If no elements are found, a not found exception will be thrown. For the same functionality that returns undef if no elements are found, see the has_link method.

find_partial

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_partial('AP')->click();

    # OR in list context 

    foreach my $element ($firefox->find_partial('AP')) {
        $element->click();
    }

If no elements are found, a not found exception will be thrown. For the same functionality that returns undef if no elements are found, see the has_partial method.

forward

full_screen

go

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();
    $firefox->go('https://metacpan.org/'); # will only return when metacpan.org is FULLY loaded (including all images / js / css)

To make the go method return quicker, you need to set the page load strategy capability to an appropriate value, such as below;

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new( capabilities => Firefox::Marionette::Capabilities->new( page_load_strategy => 'eager' ));
    $firefox->go('https://metacpan.org/'); # will return once the main document has been loaded and parsed, but BEFORE sub-resources (images/stylesheets/frames) have been loaded.

When going directly to a URL that needs to be downloaded, please see BUGS AND LIMITATIONS for a necessary workaround.

This method returns itself to aid in chaining methods.

har

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

    my $firefox = Firefox::Marionette->new(visible => 1, debug => 1, har => 1);

    $firefox->go("http://metacpan.org/");

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

    my $har = Archive::Har->new();
    $har->hashref($firefox->har());

    foreach my $entry ($har->entries()) {
        say $entry->request()->url() . " spent " . $entry->timings()->connect() . " ms establishing a TCP connection";
    }

has

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/');

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

If no elements are found, this method will return undef. For the same functionality that throws a not found exception, see the find method.

has_id

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/');

    if (my $element = $firefox->has_id('search-input')) {
        $element->type('Test::More');
    }

If no elements are found, this method will return undef. For the same functionality that throws a not found exception, see the find_id method.

has_name

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/');
    if (my $element = $firefox->has_name('q')) {
        $element->type('Test::More');
    }

If no elements are found, this method will return undef. For the same functionality that throws a not found exception, see the find_name method.

has_class

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/');
    if (my $element = $firefox->has_class('form-control home-search-input')) {
        $element->type('Test::More');
    }

If no elements are found, this method will return undef. For the same functionality that throws a not found exception, see the find_class method.

has_selector

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/');
    if (my $element = $firefox->has_selector('input.home-search-input')) {
        $element->type('Test::More');
    }

If no elements are found, this method will return undef. For the same functionality that throws a not found exception, see the find_selector method.

has_tag

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/');
    if (my $element = $firefox->has_tag('input')) {
        # do something
    }

If no elements are found, this method will return undef. For the same functionality that throws a not found exception, see the find_tag method.

has_link

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/');
    if (my $element = $firefox->has_link('API')) {
        $element->click();
    }

If no elements are found, this method will return undef. For the same functionality that throws a not found exception, see the find_link method.

has_partial

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/');
    if (my $element = $firefox->find_partial('AP')) {
        $element->click();
    }

If no elements are found, this method will return undef. For the same functionality that throws a not found exception, see the find_partial method.

html

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

    say Firefox::Marionette->new()->go('https://metacpan.org/')->html();

images

• img <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img>
• image inputs <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/image>

as Firefox::Marionette::Image objects.

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/');
    if (my $link = $firefox->images()) {
        say "Found a image with width " . $image->width() . "px and height " . $image->height() . "px from " . $image->URL();
    }

If no elements are found, this method will return undef.

install

• path to an xpi file <https://developer.mozilla.org/en-US/docs/Mozilla/XPI>.
• path to a directory containing firefox extension source code <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension>. This directory will be packaged up as an unsigned xpi file.
• path to a top level file (such as manifest.json <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Anatomy_of_a_WebExtension#manifest.json>) in a directory containing firefox extension source code <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Your_first_WebExtension>. This directory will be packaged up as an unsigned xpi file.

and an optional true/false second parameter to indicate if the xpi file should be a temporary extension <https://extensionworkshop.com/documentation/develop/temporary-installation-in-firefox/> (just for the existance of this browser instance). Unsigned xpi files may only be loaded temporarily <https://wiki.mozilla.org/Add-ons/Extension_Signing> (except for nightly firefox installations <https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly>). It returns the GUID for the addon which may be used as a parameter to the uninstall method.

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();

    my $extension_id = $firefox->install('/full/path/to/gnu_terry_pratchett-0.4-an+fx.xpi');

    # OR downloading and installing source code

    system { 'git' } 'git', 'clone', 'https://github.com/kkapsner/CanvasBlocker.git';

    if ($firefox->nightly()) {

        $extension_id = $firefox->install('./CanvasBlocker'); # permanent install for unsigned packages in nightly firefox

    } else {

        $extension_id = $firefox->install('./CanvasBlocker', 1); # temp install for normal firefox

    }

interactive

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');
    $firefox->find_id('search_input')->type('Type::More');
    $firefox->find('//button[@name="lucky"]')->click();
    while(!$firefox->interactive()) {
        # redirecting to Test::More page
    }

is_displayed

is_enabled

is_selected

json

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

    say Firefox::Marionette->new()->go('https://fastapi.metacpan.org/v1/download_url/Firefox::Marionette")->json()->{version};

key_down

    use Firefox::Marionette();
    use Firefox::Marionette::Keys qw(:all);

    my $firefox = Firefox::Marionette->new();

    $firefox->chrome()->perform(
                                 $firefox->key_down(CONTROL()),
                                 $firefox->key_down('l'),
                               )->release()->content();

key_up

    use Firefox::Marionette();
    use Firefox::Marionette::Keys qw(:all);

    my $firefox = Firefox::Marionette->new();

    $firefox->chrome()->perform(
                                 $firefox->key_down(CONTROL()),
                                 $firefox->key_down('l'),
                                 $firefox->pause(20),
                                 $firefox->key_up('l'),
                                 $firefox->key_up(CONTROL())
                               )->content();

loaded

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');
    $firefox->find_id('search_input')->type('Type::More');
    $firefox->find('//button[@name="lucky"]')->click();
    while(!$firefox->loaded()) {
        # redirecting to Test::More page
    }

links

• anchor <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a>
• area <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/area>
• frame <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/frame>
• iframe <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe>
• meta <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta>

as Firefox::Marionette::Link objects.

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/');
    if (my $link = $firefox->links()) {
        if ($link->tag() eq 'a') {
            warn "Found a hyperlink to " . $link->URL();
        }
    }

If no elements are found, this method will return undef.

macos_binary_paths

marionette_protocol

maximise

mime_types

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

    my $firefox = Firefox::Marionette->new(mime_types => [ 'application/pkcs10' ])

    foreach my $mime_type ($firefox->mime_types()) {
        say $mime_type;
    }

minimise

mouse_down

mouse_move

• origin - the origin of the C(<x => 0, y => 0)> co-ordinates. Should be either "viewport", "pointer" or an element.
• duration - Number of milliseconds over which to distribute the move. If not defined, the duration defaults to 0.

This method returns itself to aid in chaining methods.

mouse_up

new

• addons - should any firefox extensions and themes be available in this session. This defaults to "0".
• binary - use the specified path to the Firefox <https://firefox.org/> binary, rather than the default path.
• capabilities - use the supplied capabilities object, for example to set whether the browser should accept insecure certs or whether the browser should use a proxy.
• chatty - Firefox is extremely chatty on the network, including checking for the lastest malware/phishing sites, updates to firefox/etc. This option is therefore off ("0") by default, however, it can be switched on ("1") if required. Even with chatty switched off, connections to firefox.settings.services.mozilla.com will still be made <https://bugzilla.mozilla.org/show_bug.cgi?id=1598562#c13>. The only way to prevent this seems to be to set firefox.settings.services.mozilla.com to 127.0.0.1 via /etc/hosts <https://en.wikipedia.org/wiki//etc/hosts>. NOTE: that this option only works when profile_name/profile is not specified.
• console - show the browser console <https://developer.mozilla.org/en-US/docs/Tools/Browser_Console/> when the browser is launched. This defaults to "0" (off).
• debug - should firefox's debug to be available via STDERR. This defaults to "0". Any ssh connections will also be printed to STDERR. This defaults to "0" (off). This setting may be updated by the debug method.
• developer - only allow a developer edition <https://www.mozilla.org/en-US/firefox/developer/> to be launched. This defaults to "0" (off).
• devtools - begin the session with the devtools <https://developer.mozilla.org/en-US/docs/Tools> window opened in a separate window.
• height - set the height <http://kb.mozillazine.org/Command_line_arguments#List_of_command_line_arguments_.28incomplete.29> of the initial firefox window
• har - begin the session with the devtools <https://developer.mozilla.org/en-US/docs/Tools> window opened in a separate window. The HAR Export Trigger <https://addons.mozilla.org/en-US/firefox/addon/har-export-trigger/> addon will be loaded into the new session automatically, which means that -safe-mode will not be activated for this session AND this functionality will only be available for Firefox 61+.
• host - use ssh <https://man.openbsd.org/ssh.1> to create and automate firefox on the specified host. See REMOTE AUTOMATION OF FIREFOX VIA SSH.
• implicit - a shortcut to allow directly providing the implicit timeout, instead of needing to use timeouts from the capabilities parameter. Overrides all longer ways.
• kiosk - start the browser in kiosk <https://support.mozilla.org/en-US/kb/firefox-enterprise-kiosk-mode> mode.
• mime_types - any MIME types that Firefox will encounter during this session. MIME types that are not specified will result in a hung browser (the File Download popup will appear).
• nightly - only allow a nightly release <https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly> to be launched. This defaults to "0" (off).
• port - if the "host" parameter is also set, use ssh <https://man.openbsd.org/ssh.1> to create and automate firefox via the specified port. See REMOTE AUTOMATION OF FIREFOX VIA SSH.
• page_load - a shortcut to allow directly providing the page_load timeout, instead of needing to use timeouts from the capabilities parameter. Overrides all longer ways.
• profile - create a new profile based on the supplied profile. NOTE: firefox ignores any changes made to the profile on the disk while it is running.
• profile_name - pick a specific existing profile to automate, rather than creating a new profile. Firefox <https://firefox.com> refuses to allow more than one instance of a profile to run at the same time. Profile names can be obtained by using the Firefox::Marionette::Profile::names() method. NOTE: firefox ignores any changes made to the profile on the disk while it is running.
• reconnect - an experimental parameter to allow a reconnection to firefox that a connection has been discontinued. See the survive parameter.
• script - a shortcut to allow directly providing the script timeout, instead of needing to use timeouts from the capabilities parameter. Overrides all longer ways.
• seer - this option is switched off "0" by default. When it is switched on "1", it will activate the various speculative and pre-fetch options for firefox. NOTE: that this option only works when profile_name/profile is not specified.
• sleep_time_in_ms - the amount of time (in milliseconds) that this module should sleep when unsuccessfully calling the subroutine provided to the await or bye methods. This defaults to "1" millisecond.
• survive - if this is set to a true value, firefox will not automatically exit when the object goes out of scope. See the reconnect parameter for an experimental technique for reconnecting.
• trust - give a path to a root certificate <https://en.wikipedia.org/wiki/Root_certificate> encoded as a PEM encoded X.509 certificate <https://datatracker.ietf.org/doc/html/rfc7468#section-5> that will be trusted for this session.
• timeouts - a shortcut to allow directly providing a timeout object, instead of needing to use timeouts from the capabilities parameter. Overrides the timeouts provided (if any) in the capabilities parameter.
• user - if the "host" parameter is also set, use ssh <https://man.openbsd.org/ssh.1> to create and automate firefox with the specified user. See REMOTE AUTOMATION OF FIREFOX VIA SSH. The user will default to the current user name.
• visible - should firefox be visible on the desktop. This defaults to "0".
• waterfox - only allow a binary that looks like a waterfox version <https://www.waterfox.net/> to be launched.
• width - set the width <http://kb.mozillazine.org/Command_line_arguments#List_of_command_line_arguments_.28incomplete.29> of the initial firefox window

This method returns a new "Firefox::Marionette" object, connected to an instance of firefox <https://firefox.com>. In a non MacOS/Win32/Cygwin environment, if necessary (no DISPLAY variable can be found and the visible parameter to the new method has been set to true) and possible (Xvfb can be executed successfully), this method will also automatically start an Xvfb <https://en.wikipedia.org/wiki/Xvfb> instance.

    use Firefox::Marionette();

    my $remote_darwin_firefox = Firefox::Marionette->new(
                     debug => 1,
                     host => '10.1.2.3',
                     trust => '/path/to/root_ca.pem',
                     binary => '/Applications/Firefox.app/Contents/MacOS/firefox'
                                                        ); # start a temporary profile for a remote firefox and load a new CA into the temp profile
    ...

    foreach my $profile_name (Firefox::Marionette::Profile->names()) {
        my $firefox_with_existing_profile = Firefox::Marionette->new( profile_name => $profile_name, visible => 1 );
        ...
    }

new_window

• focus - a boolean field representing if the new window be opened in the foreground (focused) or background (not focused). Defaults to false.
• private - a boolean field representing if the new window should be a private window. Defaults to false.
• type - the type of the new window. Can be one of 'tab' or 'window'. Defaults to 'tab'.

Returns the window handle for the new window.

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();

    my $window_handle = $firefox->new_window(type => 'tab');

    $firefox->switch_to_window($window_handle);

new_session

nightly

paper_sizes

pause

pdf

• landscape - Paper orientation. Boolean value. Defaults to false
• margin - A hash describing the margins. The hash may have the following optional keys, 'top', 'left', 'right' and 'bottom'. All these keys are in cm and default to 1 (~0.4 inches)
• page - A hash describing the page. The hash may have the following keys; 'height' and 'width'. Both keys are in cm and default to US letter size. See the 'size' key.
• print_background - Print background graphics. Boolean value. Defaults to false.
• raw - rather than a file handle containing the PDF, the binary PDF will be returned.
• scale - Scale of the webpage rendering. Defaults to 1.
• size - The desired size (width and height) of the pdf, specified by name. See the page key for an alternative and the paper_sizes method for a list of accepted page size names.
• shrink_to_fit - Whether or not to override page size as defined by CSS. Boolean value. Defaults to true.

returns a File::Temp object containing a PDF encoded version of the current page for printing.

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');
    my $handle = $firefox->pdf();
    foreach my $paper_size ($firefox->paper_sizes()) {
            $handle = $firefox->pdf(size => $paper_size, landscape => 1, margin => { top => 0.5, left => 1.5 });
            ...
            print $firefox->pdf(page => { width => 21, height => 27 }, raw => 1);
            ...
    }

perform

    use Firefox::Marionette();
    use Firefox::Marionette::Keys qw(:all);
    use Firefox::Marionette::Buttons qw(:all);

    my $firefox = Firefox::Marionette->new();

    $firefox->chrome()->perform(
                                 $firefox->key_down(CONTROL()),
                                 $firefox->key_down('l'),
                                 $firefox->key_up('l'),
                                 $firefox->key_up(CONTROL())
                               )->content();

    $firefox->go('https://metacpan.org');
    my $help_button = $firefox->find_class('btn search-btn help-btn');
    $firefox->perform(
                                  $firefox->mouse_move($help_button),
                                  $firefox->mouse_down(RIGHT_BUTTON()),
                                  $firefox->pause(4),
                                  $firefox->mouse_up(RIGHT_BUTTON()),
                );

See the release method for an alternative for manually specifying all the mouse_up and key_up methods

profile_directory

property

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/');
    my $element = $firefox->find_id('search_input');
    $element->property('value') eq '' or die "Initial property is the empty string";
    $element->type('Test::More');
    $element->property('value') eq 'Test::More' or die "This property should have changed!";

    # OR getting the innerHTML property

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

pwd_mgr_lock

    use Firefox::Marionette();
    use IO::Prompt();

    my $firefox = Firefox::Marionette->new();
    my $password = IO::Prompt::prompt(-echo => q[*], "Please enter the password for the Firefox Password Manager:");
    $firefox->pwd_mgr_lock($password);
    $firefox->pwd_mgr_logout();
    # now no-one can access the Password Manager Database without the value in $password

This method returns itself to aid in chaining methods.

pwd_mgr_login

    use Firefox::Marionette();
    use IO::Prompt();

    my $firefox = Firefox::Marionette->new( profile_name => 'default' );
    my $password = IO::Prompt::prompt(-echo => q[*], "Please enter the password for the Firefox Password Manager:");
    $firefox->pwd_mgr_login($password);
    ...
    # access the Password Database.
    ...
    $firefox->pwd_mgr_logout();
    ...
    # no longer able to access the Password Database.

This method returns itself to aid in chaining methods.

pwd_mgr_logout

    use Firefox::Marionette();
    use IO::Prompt();

    my $firefox = Firefox::Marionette->new( profile_name => 'default' );
    my $password = IO::Prompt::prompt(-echo => q[*], "Please enter the password for the Firefox Password Manager:");
    $firefox->pwd_mgr_login($password);
    ...
    # access the Password Database.
    ...
    $firefox->pwd_mgr_logout();
    ...
    # no longer able to access the Password Database.

This method returns itself to aid in chaining methods.

pwd_mgr_needs_login

    use Firefox::Marionette();
    use IO::Prompt();

    my $firefox = Firefox::Marionette->new( profile_name => 'default' );
    if ($firefox->pwd_mgr_needs_login()) {
      my $password = IO::Prompt::prompt(-echo => q[*], "Please enter the password for the Firefox Password Manager:");
      $firefox->pwd_mgr_login($password);
    }

quit

rect

refresh

release

    use Firefox::Marionette();
    use Firefox::Marionette::Keys qw(:all);
    use Firefox::Marionette::Buttons qw(:all);

    my $firefox = Firefox::Marionette->new();

    $firefox->chrome()->perform(
                                 $firefox->key_down(CONTROL()),
                                 $firefox->key_down('l'),
                               )->release()->content();

    $firefox->go('https://metacpan.org');
    my $help_button = $firefox->find_class('btn search-btn help-btn');
    $firefox->perform(
                                  $firefox->mouse_move($help_button),
                                  $firefox->mouse_down(RIGHT_BUTTON()),
                                  $firefox->pause(4),
                )->release();

restart

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();

    $firefox->restart(); # but why?

This method returns itself to aid in chaining methods.

root_directory

screen_orientation

script

• args - The reference to a list is the arguments passed to the function body.
• filename - Filename of the client's program where this script is evaluated.
• line - Line in the client's program where this script is evaluated.
• new - Forces the script to be evaluated in a fresh sandbox. Note that if it is undefined, the script will normally be evaluted in a fresh sandbox.
• sandbox - Name of the sandbox to evaluate the script in. The sandbox is cached for later re-use on the same window <https://developer.mozilla.org/en-US/docs/Web/API/Window> object if "new" is false. If he parameter is undefined, the script is evaluated in a mutable sandbox. If the parameter is "system", it will be evaluted in a sandbox with elevated system privileges, equivalent to chrome space.
• timeout - A timeout to override the default script timeout, which, by default is 30 seconds.

Returns the result of the javascript function.

    use Firefox::Marionette();

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

    if ($firefox->script('return window.find("lucky");')) {
        # luckily!
    }

    my $search_input = $firefox->find_by_id('search-input');

    $firefox->script('arguments[0].style.backgroundColor = "red"', args => [ $search_input ]); # turn the search input box red

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

selfie

If an element is not passed as a parameter and the current context is 'chrome', a screenshot of the current viewport will be returned.

If an element is not passed as a parameter and the current context is 'content', a screenshot of the current frame will be returned.

The parameters after the element parameter are taken to be a optional hash with the following allowed keys;

• hash - return a SHA256 hex encoded digest of the PNG image rather than the image itself
• full - take a screenshot of the whole document unless the first element parameter has been supplied.
• raw - rather than a file handle containing the screenshot, the binary PNG image will be returned.
• scroll - scroll to the element supplied
• highlights - a reference to a list containing elements to draw a highlight around. Not available in Firefox 70 <https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/70#WebDriver_conformance_Marionette> onwards.

send_alert_text

sleep_time_in_ms

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new(sleep_time_in_ms => 5); # setting default time to 5 milliseconds

    my $old_time_in_ms = $firefox->sleep_time_in_ms(8); # setting default time to 8 milliseconds, returning 5 (milliseconds)

ssh_local_directory

strip

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

    say JSON::decode_json(Firefox::Marionette->new()->go("https://fastapi.metacpan.org/v1/download_url/Firefox::Marionette")->strip())->{version};

Note that this method will assume the bytes it receives from the html method are UTF-8 encoded and will translate accordingly, throwing an exception in the process if the bytes are not UTF-8 encoded.

switch_to_frame

switch_to_parent_frame

switch_to_window

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();
    $firefox->version
    my $original_window_uuid = $firefox->window_handle();
    $firefox->new_window( type => 'tab' );
    $firefox->new_window( type => 'window' );
    $firefox->switch_to_window($original_window_uuid);
    $firefox->go('https://metacpan.org');

tag_name

text

timeouts

title

type

update

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

    my $firefox = Firefox::Marionette->new();

    my $update = $firefox->update();

    while($update->successful()) {
        $update = $firefox->update();
    }

    say "Updated to " . $update->display_version() . " - Build ID " . $update->build_id();

    $firefox->quit();

returns a status object that contains useful information about any updates that occurred.

uninstall

    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new();

    my $extension_id = $firefox->install('/full/path/to/gnu_terry_pratchett-0.4-an+fx.xpi');

    # do something

    $firefox->uninstall($extension_id); # not recommended to uninstall this extension IRL.

uri

win32_organisation

win32_product_names

window_handle

    use Firefox::Marionette();
    use 5.010;

    my $firefox = Firefox::Marionette->new();
    my $original_window_uuid = $firefox->window_handle();

window_handles

    use Firefox::Marionette();
    use 5.010;

    my $firefox = Firefox::Marionette->new();
    my $original_window_uuid = $firefox->window_handle();
    $firefox->new_window( type => 'tab' );
    $firefox->new_window( type => 'window' );
    say "There are " . $firefox->window_handles() . " tabs open in total";
    say "Across " . $firefox->chrome()->window_handles()->content() . " chrome windows";

window_rect

window_type

xvfb_pid

xvfb_display

xvfb_xauthority

DOWNLOADING USING GO METHOD

    #! /usr/bin/perl

    use strict;
    use warnings;
    use Firefox::Marionette();

    my $firefox = Firefox::Marionette->new( capabilities => Firefox::Marionette::Capabilities->new( page_load_strategy => 'none' ) );
    $firefox->go("https://github.com/david-dick/firefox-marionette/archive/refs/heads/master.zip");
    while(!$firefox->downloads()) { sleep 1 }
    while($firefox->downloading()) { sleep 1 }
    foreach my $path ($firefox->downloads()) {
        warn "$path has been downloaded";
    }
    $firefox->quit();

MISSING METHODS

•

WebDriver:SetScreenOrientation

To report a bug, or view the current list of bugs, please visit <https://github.com/david-dick/firefox-marionette/issues>