Firefox::Marionette - Automate the Firefox browser with the Marionette protocol
Version 0.29
use Firefox::Marionette(); use v5.10; my $firefox = Firefox::Marionette->new()->go('https://metacpan.org/'); $firefox->find_element('//input[@id="search-input"]')->send_keys('Test::More'); my $file_handle = $firefox->selfie(highlights => [ $firefox->find_element('//button[@name="lucky"]') ]) $firefox->find_element('//button[@name="lucky"]')->click(); say $firefox->page_source(); $firefox->install('/full/path/to/gnu_terry_pratchett-0.4-an+fx.xpi');
This is a client module to automate the Mozilla Firefox browser via the Marionette protocol
accepts an optional hash as a parameter. Allowed keys are below;
firefox_binary - use the specified path to the Firefox binary, rather than the default path.
capabilities - use the supplied capabilities object, for example to set whether the browser should accept insecure certs
profile_name - pick a specific existing profile to automate, rather than creating a new profile. Note that firefox 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.
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.
debug - should firefox's debug to be available via STDERR. This defaults to "0".
addons - should any firefox extensions and themes be available in this session. This defaults to "0".
visible - should firefox be visible on the desktop. This defaults to "0".
This method returns a new Firefox::Marionette object, connected to an instance of firefox. In a non MacOS/Win32/Cygwin environment, if necessary (no DISPLAY variable can be found and visible has been set to true) and possible (Xvfb can be executed successfully), this method will also automatically start an Xvfb instance.
Firefox::Marionette
Navigates the current browsing context to the given URI and waits for the document to load or the session's page timeout duration to elapse before returning. This method returns itself to aid in chaining methods
returns the current URI of current top level browsing context for Desktop. It is equivalent to the javascript 'document.location.href'
returns the current title of the window.
returns the first element in the current browsing context that matches the search parameters supplied;
the first parameter is a scalar search value. This can be an xpath expression such as //button[@name="foo"] to find all button elements that have a 'name' of 'foo'.
//button[@name="foo"]
the second optional parameter is a scalar search strategy. This defaults to 'xpath'
This method is subject to the implicit timeout.
returns the elements in the current browsing context that match the search parameters supplied;
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.
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.
accepts an element as the first parameter and a scalar attribute name as the second parameter. It returns the current value of the property with the supplied name. This method will return the current content, the attribute method will return the initial content.
accepts a scalar containing a javascript function that is executed in the browser. Returns the result of the javascript function.
The executing javascript is subject to the scripts timeout.
accepts a scalar containing a javascript function that is executed in the browser. This method returns itself to aid in chaining methods.
returns the page source of the content document.
returns the context type that is Marionette's current target for browsing context scoped commands.
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.
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.
here be cookie monsters! This method returns itself to aid in chaining methods.
returns the contents of the cookie jar in scalar or list context.
accepts an element as the first parameter and a string as the second 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.
accepts an element as the first parameter. This method returns true or false depending on if the element is displayed.
accepts an element as the first parameter. This method returns true or false depending on if the element is enabled.
accepts an element as the first parameter. This method returns true or false depending on if the element is selected.
returns the active element of the current browsing context's document element, if the document element is non-null.
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 timeout duration to elapse before returning. This method returns itself to aid in chaining methods.
causes the browser to traverse one step forward in the joint history of the current browsing context. The browser will wait for the one step forward to complete or the session's page timeout duration to elapse before returning. This method returns itself to aid in chaining methods.
returns the current active frame if there is one in the current browsing context. Otherwise, this method returns undef.
accepts an elemnet as a parameter and switches to it's shadow root
accepts a window handle (either the result of window_handles or a window name as a parameter and switches focus to this window.
accepts a frame as a parameter and switches to it within the current window.
set the current browsing context for future commands to the parent of the current browsing context
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.
closes the current window/tab. It returns a list of still available window/tab handles.
full screens the firefox window. This method returns itself to aid in chaining methods.
minimises the firefox window. This method returns itself to aid in chaining methods.
maximises the firefox window. This method returns itself to aid in chaining methods.
refreshes the current page. The browser will wait for the page to completely refresh or the session's page timeout duration to elapse before returning. This method returns itself to aid in chaining methods.
Returns the message shown in a currently displayed modal message box
dismisses a currently displayed modal message box
accepts a currently displayed modal message box
sends keys to the input field of a currently displayed modal message box
returns the capabilities of the current firefox binary
returns the current browser orientation. This will be one of the valid primary orientation values 'portrait-primary', 'landscape-primary', 'portrait-secondary', or 'landscape-secondary'.
returns a File::Temp object containing a lossless PNG image screenshot. If an element is passed as a parameter, the screenshot will be restricted to the element.
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.
scroll - scroll to the element supplied
highlights - a reference to a list containing elements to draw a highlight around
accepts a Firefox::Marionette::Element object as the first parameter and returns the relevant tag name. For example 'a' or 'input'.
accepts an optional <position and size|Firefox::Marionette::Window::Rect> as a parameter, sets the current browser window to that position and size and returns the previous position, size and state of the browser window. If no parameter is supplied, it returns the current position, size and state of the browser window.
accepts a element as the first parameter and returns the current position and size of the element
accepts a element as the first parameter and returns the text that is contained by that element (if any)
accepts a element as the first parameter and clears any user supplied input
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 timeout duration to elapse before returning.
returns the current timeouts for page loading, searching, and scripts.
creates a new WebDriver session. It is expected that the caller performs the necessary checks on the requested capabilities to be WebDriver conforming. The WebDriver service offered by Marionette does not match or negotiate capabilities beyond type and bounds checks.
deletes the current WebDriver session.
returns the current window's type. This should be 'navigator:browser'.
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.
returns a list of top-level browsing contexts. On desktop this typically corresponds to the set of open tabs for browser windows, or the window itself for non-browser chrome windows. Each window handle is assigned by the server and is guaranteed unique, however the return array does not have a specified ordering.
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.
see 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.
returns identifiers for each open chrome window for tests interested in managing a set of chrome windows and tabs separately.
accepts the fully qualified path to an .xpi addon file as the first parameter and an optional true/false second parameter to indicate if the xpi addon file should be a temporary addition (just for the existance of this browser instance). Unsigned xpi addon files may be loaded temporarily. It returns the GUID for the addon which may be used as a parameter to the uninstall method.
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.
returns the application type for the Marionette protocol. Should be 'gecko'.
returns the version for the Marionette protocol. Current most recent version is '3'.
returns the pid of the xvfb process if it exists.
Marionette will stop accepting new connections before ending the current session, and finally attempting to quit the application. This method returns the $? (CHILD_ERROR) value for the Firefox process
This method returns the $? (CHILD_ERROR) for the Firefox process, or undefined if the process has not yet exited.
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.
This method returns true or false depending on if the Firefox process is still running.
Failed to create a socket: %s
The module was unable to even create a socket. Something is seriously wrong with your environment
Failed to send request to firefox: %s
The module was unable to perform a syswrite on the socket connected to firefox.
Failed to correctly determined the Firefox process id through the initial connection capabilities
The module was found that firefox is reporting through it's Capabilities object a different process id than this module was using. This is probably a bug in this module's logic. Please report as described in the BUGS AND LIMITATIONS section below.
Firefox::Marionette requires no configuration files or environment variables. It will however use the DISPLAY and XAUTHORITY environment variables to try to connect to an X Server.
Firefox::Marionette requires the following non-core Perl modules
JSON
URI
None reported.
No bugs have been reported.
Please report any bugs or feature requests to bug-firefox-marionette@rt.cpan.org, or through the web interface at http://rt.cpan.org.
bug-firefox-marionette@rt.cpan.org
David Dick <ddick@cpan.org>
<ddick@cpan.org>
Thanks to the entire Mozilla organisation for a great browser and to the team behind Marionette for providing a great interface for automation.
Thanks also to the authors of the documentation in the following sources;
Marionette Protocol
Marionette Documentation
Marionette driver.js at github
Copyright (c) 2018, David Dick <ddick@cpan.org>. All rights reserved.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See "perlartistic" in perlartistic.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install Firefox::Marionette, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Firefox::Marionette
CPAN shell
perl -MCPAN -e shell install Firefox::Marionette
For more information on module installation, please visit the detailed CPAN module installation guide.