Allow Disabling Automated Firefox Extension Installation via Cypress Env Variable

[willmsC]

Description:

In our organisation we use a custom Firefox build in a restricted environment. Starting from #30324, where the geckodriver was introduced to install the Cypress Firefox extension, this process fails in our setup with the following error message:

Cypress failed to make a connection to Firefox.

This usually indicates there was a problem opening the Firefox browser.

unknown error: WebDriverError: Expected absolute path: [Exception... "Component returned failure code: 0x80520001 (NS_ERROR_FILE_UNRECOGNIZED_PATH) [nsIFile.initWithPath]"  nsresult: "0x80520001 (NS_ERROR_FILE_UNRECOGNIZED_PATH)"  location: "JS frame :: chrome://remote/content/marionette/addon.sys.mjs :: install :: line 72"  data: no] when running "moz/addon/install" with method "POST" and args "{"path":"/.../run-39277/CypressExtension","temporary":true}"
    at FetchRequest._request (file:///.../app/packages/server/node_modules/webdriver/build/node.js:1700:19)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async <embedded>:2770:14517
    at async Promise.all (index 0)
    at async Object.Y (<embedded>:2770:14409)
    at async Object.open (<embedded>:2770:30476)
    at async v.relaunchBrowser (<embedded>:2879:38794)

Investigation & Root Cause

Our setup deviates from a standard Firefox installation, which seems to be the cause of this failure. Since the extension installation is now an enforced step, Cypress cannot proceed if the process fails.

Proposed Solution

Introduce a custom Cypress environment variable (e.g., CYPRESS_FIREFOX_EXTENSION_INSTALL) that:

1. Allows disabling automated installation of the Firefox extension.
2. Optionally, allows Cypress to continue execution even if the installation fails.

This would enable us to manually install the extension on the browser beforehand while keeping Cypress functional in our environment.

Why This Matters

While this is a niche use case, some users in our organization are not familiar with coding or modifying Cypress locally. Adding this option would significantly improve usability for such environments.

Additional Information

A potential fix has been suggested in a pull request, but I’m open to other approaches that might better align with Cypress’s development roadmap.

Would appreciate any feedback on this!

How has the user experience changed?

The user experience has not been changed.

PR Tasks

• Have tests been added/updated?
• Has a PR for user-facing changes been opened in cypress-documentation?
• Have API changes been updated in the type definitions?

[cypress-app-bot]

• Create a Draft Pull Request if your PR is not ready for review. Mark the PR as Ready for Review when you're ready for a Cypress team member to review the PR.

[MikeMcC399]

• related to Cypress tests fail in air-gapped network on Firefox #31036

[AtofStryker]

Hi @willmsC. Thank you for opening an issue! Unfortunately, Cypress always need to be able to install a web extension to run, so disabling it is not an option. We've have always used one, but the way the extension is installed changed in #30250 where we used to install the extension through marionette directly via websocket, where as now we use the webdriver library to install the extension which I believe operates over http.

Are you able to provide some debug logs that could help provide some context on why things might be failing over? I think setting DEBUG=cypress:server:browsers:firefox,cypress-verbose:server:browsers:firefox,cypress-verbose:server:browsers:webdriver,cypress-verbose:server:browsers:geckodriver npx cypress run ... should be enough to get an idea.

[MikeMcC399]

It would probably be a good idea to open an issue for troubleshooting / analysis as a companion to this PR.

[AtofStryker]

It would probably be a good idea to open an issue for troubleshooting / analysis as a companion to this PR.

I think that's a good idea. I'm going to work on getting something open

[AtofStryker]

Closing due to this solution not being possible, as Cypress needs the web extension to run, especially in firefox