Firefox-Marionette
view release on metacpan or search on metacpan
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
my $form_login = Firefox::Marionette::Login(host => 'https://github.com', user => 'me2@example.org', password => 'uiop[]', user_field => 'login', password_field => 'password');
$firefox->add_login($form_login);
# or just directly
$firefox->add_login(host => 'https://github.com', user => 'me2@example.org', password => 'uiop[]', user_field => 'login', password_field => 'password');
Note for HTTP Authentication, the realm
<https://datatracker.ietf.org/doc/html/rfc2617#section-2> must
perfectly match the correct realm supplied by the server.
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
add_webauthn_authenticator
accepts a hash of the following keys;
* has_resident_key - boolean value to indicate if the authenticator
will support client side discoverable credentials
<https://www.w3.org/TR/webauthn-2/#client-side-discoverable-credential>
* has_user_verification - boolean value to determine if the
authenticator
<https://www.w3.org/TR/webauthn-2/#virtual-authenticators> supports
user verification
<https://www.w3.org/TR/webauthn-2/#user-verification>.
* is_user_consenting - boolean value to determine the result of all
user consent <https://www.w3.org/TR/webauthn-2/#user-consent>
authorization gestures
<https://www.w3.org/TR/webauthn-2/#authorization-gesture>, and by
extension, any test of user presence
<https://www.w3.org/TR/webauthn-2/#test-of-user-presence> performed
on the Virtual Authenticator
<https://www.w3.org/TR/webauthn-2/#virtual-authenticators>. If set to
true, a user consent will always be granted. If set to false, it will
not be granted.
* is_user_verified - boolean value to determine the result of User
Verification <https://www.w3.org/TR/webauthn-2/#user-verification>
performed on the Virtual Authenticator
<https://www.w3.org/TR/webauthn-2/#virtual-authenticators>. If set to
true, User Verification will always succeed. If set to false, it will
fail.
* protocol - the protocol spoken by the authenticator. This may be
CTAP1_U2F, CTAP2 or CTAP2_1.
* transport - the transport simulated by the authenticator. This may
be BLE, HYBRID, INTERNAL, NFC, SMART_CARD or USB.
It returns the newly created authenticator.
use Firefox::Marionette();
use Crypt::URandom();
my $user_name = MIME::Base64::encode_base64( Crypt::URandom::urandom( 10 ), q[] ) . q[@example.com];
my $firefox = Firefox::Marionette->new( webauthn => 0 );
my $authenticator = $firefox->add_webauthn_authenticator( transport => Firefox::Marionette::WebAuthn::Authenticator::INTERNAL(), protocol => Firefox::Marionette::WebAuthn::Authenticator::CTAP2() );
$firefox->go('https://webauthn.io');
$firefox->find_id('input-email')->type($user_name);
$firefox->find_id('register-button')->click();
$firefox->await(sub { sleep 1; $firefox->find_class('alert-success'); });
$firefox->find_id('login-button')->click();
$firefox->await(sub { sleep 1; $firefox->find_class('hero confetti'); });
add_webauthn_credential
accepts a hash of the following keys;
* authenticator - contains the authenticator that the credential will
be added to. If this parameter is not supplied, the credential will
be added to the default authenticator, if one exists.
* host - contains the domain that this credential is to be used for.
In the language of WebAuthn <https://www.w3.org/TR/webauthn-2>, this
field is referred to as the relying party identifier
<https://www.w3.org/TR/webauthn-2/#relying-party-identifier> or RP ID
<https://www.w3.org/TR/webauthn-2/#rp-id>.
* id - contains the unique id for this credential, also known as the
Credential ID <https://www.w3.org/TR/webauthn-2/#credential-id>. If
this is not supplied, one will be generated.
* is_resident - contains a boolean that if set to true, a client-side
discoverable credential
<https://w3c.github.io/webauthn/#client-side-discoverable-credential>
is created. If set to false, a server-side credential
<https://w3c.github.io/webauthn/#server-side-credential> is created
instead.
* private_key - either a RFC5958
<https://www.rfc-editor.org/rfc/rfc5958> encoded private key encoded
using encode_base64url or a hash containing the following keys;
* name - contains the name of the private key algorithm, such as
"RSA-PSS" (the default), "RSASSA-PKCS1-v1_5", "ECDSA" or "ECDH".
* size - contains the modulus length of the private key. This is
only valid for "RSA-PSS" or "RSASSA-PKCS1-v1_5" private keys.
* hash - contains the name of the hash algorithm, such as "SHA-512"
(the default). This is only valid for "RSA-PSS" or
"RSASSA-PKCS1-v1_5" private keys.
* curve - contains the name of the curve for the private key, such
as "P-384" (the default). This is only valid for "ECDSA" or "ECDH"
private keys.
* sign_count - contains the initial value for a signature counter
<https://w3c.github.io/webauthn/#signature-counter> associated to the
public key credential source
<https://w3c.github.io/webauthn/#public-key-credential-source>. It
will default to 0 (zero).
* user - contains the userHandle
<https://w3c.github.io/webauthn/#public-key-credential-source-userhandle>
associated to the credential encoded using encode_base64url. This
property is optional.
It returns the newly created credential. If of course, the credential
is just created, it probably won't be much good by itself. However, you
can use it to recreate a credential, so long as you know all the
parameters.
use Firefox::Marionette();
use Crypt::URandom();
my $user_name = MIME::Base64::encode_base64( Crypt::URandom::urandom( 10 ), q[] ) . q[@example.com];
my $firefox = Firefox::Marionette->new();
$firefox->go('https://webauthn.io');
$firefox->find_id('input-email')->type($user_name);
$firefox->find_id('register-button')->click();
$firefox->await(sub { sleep 1; $firefox->find_class('alert-success'); });
$firefox->find_id('login-button')->click();
$firefox->await(sub { sleep 1; $firefox->find_class('hero confetti'); });
foreach my $credential ($firefox->webauthn_credentials()) {
$firefox->delete_webauthn_credential($credential);
# ... time passes ...
$firefox->add_webauthn_credential(
id => $credential->id(),
host => $credential->host(),
user => $credential->user(),
private_key => $credential->private_key(),
is_resident => $credential->is_resident(),
sign_count => $credential->sign_count(),
);
}
$firefox->go('about:blank');
$firefox->clear_cache(Firefox::Marionette::Cache::CLEAR_COOKIES());
$firefox->go('https://webauthn.io');
$firefox->find_id('input-email')->type($user_name);
$firefox->find_id('login-button')->click();
$firefox->await(sub { sleep 1; $firefox->find_class('hero confetti'); });
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
<http://kb.mozillazine.org/Command_line_arguments#List_of_command_line_arguments_.28incomplete.29>
cannot be automated.
agent
accepts an optional value for the User-Agent
<https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent>
header and sets this using the profile preferences and inserting
javascript into the current page. It returns the current value, such as
'Mozilla/5.0 (<system-information>) <platform> (<platform-details>)
<extensions>'. This value is retrieved with navigator.userAgent
<https://developer.mozilla.org/en-US/docs/Web/API/Navigator/userAgent>.
This method can be used to set a user agent string like so;
use Firefox::Marionette();
use strict;
# useragents.me should only be queried once a month or less.
# these UA strings should be cached locally.
my %user_agent_strings = map { $_->{ua} => $_->{pct} } @{$firefox->json("https://www.useragents.me/api")->{data}};
my ($user_agent) = reverse sort { $user_agent_strings{$a} <=> $user_agent_strings{$b} } keys %user_agent_strings;
my $firefox = Firefox::Marionette->new();
$firefox->agent($user_agent); # agent is now the most popular agent from useragents.me
If the user agent string that is passed as a parameter looks like a
Chrome <https://www.google.com/chrome/>, Edge
<https://microsoft.com/edge> or Safari <https://www.apple.com/safari/>
user agent string, then this method will also try and change other
profile preferences to match the new agent string. These parameters
are;
* general.appversion.override
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
accepts a login as a parameter.
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
This method empties the password database.
use Firefox::Marionette();
my $firefox = Firefox::Marionette->new();
$firefox->delete_logins();
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
<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.
delete_webauthn_all_credentials
This method accepts an optional authenticator, in which case it will
delete all credentials from this authenticator. If no parameter is
supplied, the default authenticator will have all credentials deleted.
my $firefox = Firefox::Marionette->new();
my $authenticator = $firefox->add_webauthn_authenticator( transport => Firefox::Marionette::WebAuthn::Authenticator::INTERNAL(), protocol => Firefox::Marionette::WebAuthn::Authenticator::CTAP2() );
$firefox->delete_webauthn_all_credentials($authenticator);
$firefox->delete_webauthn_all_credentials();
delete_webauthn_authenticator
This method accepts an optional authenticator, in which case it will
delete this authenticator from the current Firefox instance. If no
parameter is supplied, the default authenticator will be deleted.
my $firefox = Firefox::Marionette->new();
my $authenticator = $firefox->add_webauthn_authenticator( transport => Firefox::Marionette::WebAuthn::Authenticator::INTERNAL(), protocol => Firefox::Marionette::WebAuthn::Authenticator::CTAP2() );
$firefox->delete_webauthn_authenticator($authenticator);
$firefox->delete_webauthn_authenticator();
delete_webauthn_credential
This method accepts either a credential and an authenticator, in which
case it will remove the credential from the supplied authenticator or
use Firefox::Marionette();
my $firefox = Firefox::Marionette->new();
my $authenticator = $firefox->add_webauthn_authenticator( transport => Firefox::Marionette::WebAuthn::Authenticator::INTERNAL(), protocol => Firefox::Marionette::WebAuthn::Authenticator::CTAP2() );
foreach my $credential ($firefox->webauthn_credentials($authenticator)) {
$firefox->delete_webauthn_credential($credential, $authenticator);
}
just a credential, in which case it will remove the credential from the
default authenticator.
use Firefox::Marionette();
my $firefox = Firefox::Marionette->new();
...
foreach my $credential ($firefox->webauthn_credentials()) {
$firefox->delete_webauthn_credential($credential);
}
This method returns itself to aid in chaining methods.
developer
returns true if the current version of firefox is a developer edition
<https://www.mozilla.org/en-US/firefox/developer/> (does the minor
version number end with an 'b\d+'?) version.
dismiss_alert
dismisses a currently displayed modal message box
displays
accepts an optional regex to filter against the usage for the display
and returns a list of all the known displays
<https://en.wikipedia.org/wiki/List_of_common_resolutions> as a
Firefox::Marionette::Display.
use Firefox::Marionette();
use Encode();
use v5.10;
my $firefox = Firefox::Marionette->new( visible => 1, kiosk => 1 )->go('http://metacpan.org');;
my $element = $firefox->find_id('metacpan_search-input');
foreach my $display ($firefox->displays(qr/iphone/smxi)) {
say 'Can Firefox resize for "' . Encode::encode('UTF-8', $display->usage(), 1) . '"?';
if ($firefox->resize($display->width(), $display->height())) {
say 'Now displaying with a Pixel aspect ratio of ' . $display->par();
say 'Now displaying with a Storage aspect ratio of ' . $display->sar();
say 'Now displaying with a Display aspect ratio of ' . $display->dar();
} else {
say 'Apparently NOT!';
}
}
downloaded
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('page-content')->find_id('metacpan_search-input')->type('Test::More');
$firefox->await(sub { $firefox->find_class('autocomplete-suggestion'); })->click();
$firefox->find_partial('Download')->click();
while(!$firefox->downloads()) { sleep 1 }
foreach my $path ($firefox->downloads()) {
parameter. It sends the string to the specified element in the current
page, such as filling out a text box. This method returns itself to aid
in chaining methods.
uname
returns the $^O ($OSNAME) compatible string to describe the platform
where firefox is running.
update
queries the Update Services and applies any available updates. Restarts
the browser if necessary to complete the update. This function is
experimental and currently has not been successfully tested on Win32 or
MacOS.
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
accepts the GUID for the addon to uninstall. The GUID is returned when
from the install method. This method returns itself to aid in chaining
methods.
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
returns the current URI of current top level browsing context for
Desktop. It is equivalent to the javascript document.location.href
webauthn_authenticator
returns the default WebAuthn authenticator created when the new method
was called.
webauthn_credentials
This method accepts an optional authenticator, in which case it will
return all the credentials attached to this authenticator. If no
parameter is supplied, credentials from the default authenticator will
be returned.
use Firefox::Marionette();
use v5.10;
my $firefox = Firefox::Marionette->new();
foreach my $credential ($firefox->webauthn_credentials()) {
say "Credential host is " . $credential->host();
}
# OR
my $authenticator = $firefox->add_webauthn_authenticator( transport => Firefox::Marionette::WebAuthn::Authenticator::INTERNAL(), protocol => Firefox::Marionette::WebAuthn::Authenticator::CTAP2() );
foreach my $credential ($firefox->webauthn_credentials($authenticator)) {
say "Credential host is " . $credential->host();
}
webauthn_set_user_verified
This method accepts a boolean for the is_user_verified field and an
optional authenticator (the default authenticator will be used
otherwise). It sets the is_user_verified field to the supplied boolean
value.
use Firefox::Marionette();
my $firefox = Firefox::Marionette->new();
$firefox->webauthn_set_user_verified(1);
wheel
accepts a element parameter, or a ( x => 0, y => 0 ) type hash manually
describing exactly where to move the mouse from and returns an action
for use in the perform method that corresponding with such a wheel
action, either to the specified co-ordinates or to the middle of the
supplied element parameter. Other parameters that may be passed are
listed below;
* 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.
* deltaX - the change in X co-ordinates during the wheel. If not
defined, deltaX defaults to 0.
* deltaY - the change in Y co-ordinates during the wheel. If not
defined, deltaY defaults to 0.
win32_organisation
accepts a parameter of a Win32 product name and returns the matching
organisation. Only of interest when sub-classing.
win32_product_names
returns a hash of known Windows product names (such as 'Mozilla
Firefox') with priority orders. The lower the priority will determine
the order that this module will check for the existence of this
product. Only of interest when sub-classing.
window_handle
returns the current window's handle. On desktop this typically
corresponds to the currently selected tab. returns an opaque
server-assigned identifier to this window that uniquely identifies it
within this Marionette instance. This can be used to switch to this
window at a later point. This is the same as the window
<https://developer.mozilla.org/en-US/docs/Web/API/Window> object in
Javascript.
use Firefox::Marionette();
( run in 0.459 second using v1.01-cache-2.11-cpan-8f98c5d2c55 )