Firefox browser extension support for Playwright

Learn how to run Playwright tests on BrowserStack Automate with a single Firefox browser extension attached to each session.

Browser extensions are a common way to deliver product features, content blockers, and productivity tooling directly in the browser UI. This page explains the behavior, constraints, and high-level configuration model for testing Firefox browser extensions on BrowserStack Automate using Playwright.

Supported scenario

You can use this capability in the following scenario:

• Run Playwright tests on BrowserStack Automate against desktop Firefox sessions.
• Attach one Firefox browser extension to each Automate session.
• Provide the extension as a packaged .xpi file or a .zip that contains a valid Firefox extension.
• The extension filename should not contain any blank spaces or dots (‘.’).
• Make the extension package accessible to BrowserStack by uploading it to BrowserStack.

This capability focuses on Firefox desktop for Playwright. Extension testing for other browsers or frameworks is handled by their respective workflows and documentation.

Key behavior and constraints

Firefox extension support in Playwright sessions follows these rules:

• Extension load timing: The extension is installed and loaded before the Firefox browser instance starts your test. It remains active for the entire session.
• Single extension per session: Each Automate session accepts at most one extension. If you configure multiple extensions for the same session, BrowserStack returns a clear, user-facing error and does not start the session.
• Package validation: BrowserStack validates that the provided .xpi or .zip contains a valid Firefox extension. If validation fails or BrowserStack cannot fetch the package, the session ends early with a clear error message.
• Configuration-driven setup: The extension is attached through a dedicated configuration capability in your Playwright configuration or capabilities object. The exact capability name and shape may vary by release. Use the examples from your BrowserStack account or release notes for the final key name.
• Session visibility: You should be able to confirm that the extension is active, for example by checking Firefox’s extension listing from your test code or by using logs and metadata in the Automate dashboard.

High-level configuration flow

To enable Firefox extension testing with Playwright on BrowserStack Automate, follow this high-level flow:

1. Package your Firefox extension:
   • Build your browser extension as an .xpi package or as a .zip that contains a valid Firefox extension.
   • Verify it can be installed and run locally in Firefox before automating it on BrowserStack.
2. Make the extension accessible to BrowserStack:
   • Either upload the package to BrowserStack using the existing media upload API to obtain a reusable identifier, or
   • Host the package at a secure, publicly reachable URL that BrowserStack can fetch at session start.
3. Reference the extension from your Playwright capabilities:
   • In your Playwright configuration or capabilities object, add the Firefox extension reference using the capability key provided in your BrowserStack documentation or account configuration. - Ensure the sample code reflects the upload media flow code.
   • The value should be either the uploaded identifier (for example, a media://... token) or a public URL that points to the .xpi or .zip file.

    // Example structure – replace <capability-key> and <extension-reference>
    // with the exact values documented for your account.
    const caps = {
      browser: 'firefox',
      os: 'Windows',
      osVersion: '11',
      'browserstack.username': process.env.BROWSERSTACK_USERNAME,
      'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY,
      '<capability-key>': '<extension-reference>', // for example, uploaded ID or URL
    };
   

4. Run your Playwright tests on Firefox:
   • Start your Playwright tests against BrowserStack Automate as usual, targeting Firefox.
   • Your tests can now interact with the extension UI, validate extension-driven behavior, and assert side effects created by the extension.

Out-of-scope behavior

Firefox extension support for Playwright on BrowserStack Automate does not cover the following in this iteration:

• Loading more than one extension in the same Automate session.
• Dynamically adding, removing, or swapping extensions mid-session.
• Testing browser extensions on non-Firefox browsers (such as Chrome, Edge, Safari, or Brave).
• Testing on mobile Firefox or other mobile browsers.
• Advanced, extension-specific debugging tools beyond standard browser logs and console output.
• Playwright version compatibility: This feature is stable only when the client and server Playwright versions match or share the same major version. For example, versions 1.54.0 and 1.54.1 are compatible because they have the same major version (1.54). Ensure that browserstack.playwrightVersion and client playwrightVersion are aligned before running tests.

As BrowserStack expands extension testing support to additional browsers or workflows, it will document those in the respective product sections.