Firefox Automation

GeckoDriver / WebDriver Classic

Purpose

Cypress uses GeckoDriver to drive classic WebDriver methods, as well as interface with Firefox's Marionette Protocol. This is necessary to automate the Firefox browser in the following cases:

• Navigating to the current/next spec URL via WebDriver Classic.
• Installing the Cypress web extension via the Marionette Protocol, which is critical to automating Firefox.

The WebDriver methods used come from the webdriver package to drive WebDriver (and in the future, WebDriver BiDi), which also starts the geckodriver for us using the wdio:geckodriverOptions capability.

As of Firefox 141 and Cypress 15, WebDriver BiDi is used to fully automate the firefox browser. GeckoDriver will be the entry point in which Cypress implements WebDriver BiDi for Firefox.

Historical Context

Previously, Cypress was using an older package called the marionette-client, which is near identical to the mozilla b2g marionette client. The b2g client hasn't had active development since 2014 and there have been changes to Marionette's server implementation since then. This means the marionette-client could break at any time, hence why we have migrated away from it. See Cypress' migration to WebDriver BiDi within Firefox bugzilla ticket for more details.

Implementation

To consume GeckoDriver, Cypress installs the geckodriver package, a lightweight wrapper around the geckodriver binary, to connect to the Firefox browser. Once connected, GeckoDriver is able to send WebDriver commands, as well as Marionette commands, to the Firefox browser. It is also capable of creating a WebDriver BiDi session to send WebDriver BiDi commands and receive WebDriver BiDi events.

It is worth noting that Cypress patches the geckodriver and webdriver packages for a few reasons:

• To coincide with our debug logs in order to not print extraneous messages to the console that could disrupt end user experience as well as impact our system tests. These can be turned on by setting the DEBUG variable to cypress-verbose:server:browsers:geckodriver or cypress-verbose:server:browsers:webdriver depending on what needs to be debugged
• Patch top-level awaits to correctly build the app.

Currently, the use of WebDriver Classic is small. To prepare for the implementation of WebDriver BiDi and reduce the need for maintenance code, the methods are implemented via the webdriver package. It's important to note that, unlike Chrome, Firefox is launched via the WebDriver newSession command (via webdriver package).

Since we patch the geckodriver and the related webdriver packages, we nohoist the dependencies. We keep all dependencies related to webdriver in the packherd binary-cleanup file. One of these preserved dependencies, [email protected] has the same top-level await that geckodriver uses, so we need to patch it. We do not consume this package directly. This is just to make sure the binary can build.

Debugging

To help debug geckodriver and firefox, the DEBUG=cypress-verbose:server:browsers:geckodriver,cypress-verbose:server:browsers:webdriver can be used when launching cypress. This will

• Enable full stdout and stderr for geckodriver (including startup time) and the firefox process. The logs will NOT be truncated so they may get quite long.
• Enables the debugger terminal, which will additionally print browser information to the debugger terminal process.
• enables webdriver debug logs for all commands and events.

If you are having trouble running firefox, turning on this debug option can be quite useful.