FoxPuppet¶
FoxPuppet is a library for automating user interactions in Firefox using Selenium.
User Guide¶
FoxPuppet is a library for automating user interactions in Firefox using Selenium. This section gives some example use-cases of FoxPuppet.
Example¶
This is an example for setting up FoxPuppet and opening a private window:
from foxpuppet import FoxPuppet
from selenium.webdriver import Firefox
selenium = Firefox()
foxpuppet = FoxPuppet(selenium)
window = foxpuppet.browser.open_window(private=True)
selenium.quit()
This example opens first a non-private browser window, then proceeds to open a private browser window.
Finally it quits via selenium.quit()
.
Note: | The initial browser window is automatically assigned to the browser attribute and is always available. |
---|
Development¶
Automated Testing¶
All pull requests and merges are tested in Travis CI
based on the .travis.yml
file.
Usually, a link to your specific travis build appears in pull requests, but if not, you can find it on the pull requests page
The only way to trigger Travis CI to run again for a pull request, is to submit another change to the pull branch.
Test coverage is done by Coveralls.
Running Tests¶
You will need Tox installed to run the tests against the supported Python versions.
You also need to have Geckodriver installed so the tests can run Firefox.
$ pip install tox
$ tox
Keeping up with Firefox¶
As Firefox evolves, it will be necessary for FoxPuppet to keep up. This will likely present itself as a test failure introduces in Firefox nightly. FoxPuppet’s tests are configures to run on Travis CI every day, which alerts us of regressions or more likely changes in Firefox that we need to adapt to.
When such failures occur, the following guide may help to determine the change that introduced the failure, and the fix that may be needed.
Replicate the failure¶
To run the tests against a specific Firefox version (you’ll typically want Nightly)
make sure the PATH
environment variable is front-loaded with the path to the target
binary. Note that you want the path that contains the binary, and not the path of the
binary itself. Although this part should run fine in Python 3, it’s worth targeting
2.7 using -e py27
as the following steps currently require it. It’s also a good idea to narrow the tests being run using -k
as shown in this example:
$ export MOZ_HEADLESS=1
$ export PATH=/Applications/FirefoxNightly.app/Contents/MacOS:$PATH
$ tox -e py27 -- -k test_tracking_protection_shield
Determine the regression range¶
Run mozregression
to determine the change that introduced the failure. Create a
temporary virtual environment using Python 2.7 and install both tox
and
mozregression
. You can then use mozregression
providing the last time the test
was known to pass, and the first time it was known to fail. This can be determined by
the dates in the Travis CI results. Modify the following to suit your needs:
$ mozregression -b 2018-08-12 -g 2018-08-11 -c "tox -e py27 -- -k test_tracking_protection_shield"
This will identify the builds within the range, and systematically download and execute
the tests against the builds to identify the change that caused the failure. You don’t
need to worry about PATH
as the FoxPuppet tests use the MOZREGRESSION_BINARY
environment variable if it’s set.
Assuming everything goes as expected, mozregression will report the last good revision, first bad revision, and provide a pushlog URL showing the change(s) that caused the regression. From this, it should be possible to determine if the failure is expected due to changes in Firefox, or if a bug has been introduced.
Supporting latest Firefox versions¶
If behaviour changes in Firefox and FoxPuppet needs to be updated, it is sometimes necessary to change the behaviour in FoxPuppet based on the Firefox version.
Release Notes¶
Developer Interface¶
This part of the documentation describes the interfaces for using FoxPuppet.
FoxPuppet¶
Windows¶
This module contains all of the window types as well as the window manager.
Window Manager¶
Browser Window¶
-
class
foxpuppet.windows.browser.window.
BrowserWindow
(selenium, handle)[source]¶ Representation of a browser window.
-
close
()¶ Close the window.
-
document_element
¶ Return the inner DOM window element.
Returns: WebDriver element object for the DOM window element. Return type: WebElement
-
firefox_version
¶ Major version of Firefox in use.
Returns: Major component of the Firefox version. Return type: int
-
is_private
¶ Property that checks if the specified window is private or not.
Returns: True if this is a Private Browsing window. Return type: bool
Provide access to the Navigation Bar.
Returns: FoxPuppet NavBar object. Return type: NavBar
-
notification
¶ Provide access to the currently displayed notification.
Returns: FoxPuppet BaseNotification object. Return type: BaseNotification
-
open_window
(private=False)[source]¶ Open a new browser window.
Parameters: private (bool) – Optional parameter to open a private browsing window. Defaults to False. Returns: Opened window. Return type: BrowserWindow
-
switch_to
()¶ Switch focus for Selenium commands to this window.
-
wait_for_notification
(notification_class=<class 'foxpuppet.windows.browser.notifications.base.BaseNotification'>)[source]¶ Wait for the specified notification to be displayed.
Parameters: notification_class ( BaseNotification
, optional) – The notification class to wait for. If None is specified it will wait for any notification to be closed. Defaults to BaseNotification.Returns: Firefox notification. Return type: BaseNotification
-