How to Run Cypress Cross-Browser Tests in All Major Browsers

Run Cypress once per installed browser with npx cypress run --browser <browser>. Cypress supports Chrome-family browsers (including Chrome, Chromium, and Microsoft Edge), Firefox, and experimental WebKit. The browser must be installed in the environment where Cypress runs. WebKit is Safari’s browser engine, not the Safari application, so a WebKit run does not prove full Safari compatibility. Cypress cross-browser testing guide

1. Know what “all major browsers” means in Cypress

Cypress’s documented browser families are Chrome-family browsers, Firefox, and WebKit. Its browser reference states official support for the latest three major versions of Chrome, Firefox, and Edge. It currently says Firefox versions earlier than 140 cannot be launched because they do not fully implement WebDriver BiDi; recheck this version floor against the live docs when upgrading Cypress. Browser support and launch details change over time. Cypress browser launch reference

Target	What to run	Important boundary
Chrome	`--browser chrome`	Use Chrome for Testing when you need a versioned binary that does not auto-update.
Chromium	`--browser chromium` if detected, or supply its binary path	Ensure the binary exists in the local or CI environment.
Microsoft Edge	`--browser edge`	Edge is a Chromium-based, Chrome-family browser.
Firefox	`--browser firefox`	Check the current Cypress minimum version; the current reference lists Firefox 140.
WebKit	Enable experimental support and install `playwright-webkit`	Experimental engine coverage, not a run of Safari itself; documented limitations include no `cy.origin()` support and no Test Replay.

Cypress also lists browser channels such as stable, beta, canary, and developer for several browser families. For repeatable automation, Chrome for Testing is useful because Cypress describes its binary as versioned and non-auto-updating. Electron is deprecated as a Cypress test browser and is planned for removal in a future Cypress version, so explicitly select a supported installed browser instead of relying on a default. Browser launch reference · Cypress migration guide

2. Install Cypress and the browsers you plan to cover

Add Cypress to the project using its package manager, then install each target browser on the same machine or CI image that runs the tests. Browser installation is environment-specific; Cypress detects available browsers and lists them in the browser selector. In CI, choose a maintained Cypress browser image or provision the browsers yourself. Cypress’s CI documentation demonstrates installing Chrome, Chrome for Testing, Edge, and Firefox in a job environment. Cross-browser guide

npm install --save-dev cypress
npx cypress install
npx cypress verify

For local interactive testing, start Cypress and select a browser from the browser menu:

npx cypress open

For a custom or portable browser that Cypress does not discover automatically, pass its executable path. The documented example uses cypress open; the same browser-selection concept applies when running a test run, provided Cypress can launch that binary:

npx cypress open --browser /usr/bin/chromium

3. Run the same suite in each browser

Use the CLI --browser flag. These commands run the suite separately in each browser; Cypress does not make one browser run stand in for another.

npx cypress run --browser chrome
npx cypress run --browser edge
npx cypress run --browser firefox

Use chromium or a browser channel identifier when that installation is detected. A path can be used when you need to select a specific custom binary. See the CLI reference for current syntax.

CLI runs are headless by default. Add --headed to watch the browser while diagnosing a failure:

npx cypress run --browser firefox --headed

To repeat browser commands easily, add npm scripts:

{
  "scripts": {
    "cy:run:chrome": "cypress run --browser chrome",
    "cy:run:edge": "cypress run --browser edge",
    "cy:run:firefox": "cypress run --browser firefox"
  }
}

Then run, for example, npm run cy:run:firefox. Equivalent commands work with other package managers.

4. Add experimental WebKit coverage

Cypress’s WebKit integration is experimental and requires explicit setup. Install the WebKit package and enable the experimental flag in the Cypress configuration. Linux environments may also need operating-system dependencies for Playwright WebKit. Follow the current Cypress WebKit instructions for the Cypress and package versions in your project. Cypress browser launch reference

npm install --save-dev playwright-webkit

In cypress.config.js:

const { defineConfig } = require('cypress');

module.exports = defineConfig({
  experimentalWebKitSupport: true,
  e2e: {
    setupNodeEvents(on, config) {
      return config;
    }
  }
});

Then select WebKit as documented by your installed Cypress version and run the suite. Because support is experimental and behavior differs from Safari, treat this as additional engine coverage. Validate Safari-specific behavior on actual Safari using a suitable Safari testing environment if Safari itself is part of your support promise. Do not assume WebKit coverage exercises Safari’s app-specific integrations or every Safari release.

5. Choose a CI coverage strategy

Every browser in the matrix needs to be installed in the job environment. Decide how broadly to run tests using product risk, feedback time, and CI capacity. Cypress’s guide gives two practical patterns: run the whole suite in one browser and a critical subset in another, or run additional browser suites periodically. These are strategy examples, not a universal required matrix. Cypress CI strategy examples

Start with the primary browser. Run the full suite on each commit in the browser that gives the team its main feedback loop.
Cover critical user journeys elsewhere. Select signup, authentication, checkout, or other business-critical specs for another browser.
Expand by risk. Run broader suites across more browsers before releases or on a schedule when the product’s compatibility commitments justify the time.
Keep versions deliberate. Pin or otherwise control browser versions when reproducibility matters; Chrome for Testing is one option identified by Cypress.
Record and group runs if using Cypress Cloud. Browser-specific groups make results distinguishable in the recorded run.

Example commands for a full Chrome suite and a Firefox critical-path subset:

npx cypress run --browser chrome --record --group chrome
npx cypress run --browser firefox \
  --spec "cypress/e2e/signup.cy.js,cypress/e2e/login.cy.js" \
  --record --group firefox-critical-path

--record requires the project’s Cypress Cloud recording setup. Omit the recording flags if you do not use Cypress Cloud. Run each command in a job or workflow step that has the corresponding browser installed and starts the application under test.

For a minimal provider-neutral CI job, the essential sequence is install dependencies, install or select the browser-containing environment, start the app, and run Cypress. The exact YAML differs by provider, but the commands are the same:

npm ci
npx cypress verify
npm run start:test &
npx cypress run --browser chrome

Ensure the app is ready before Cypress starts; use your CI provider’s service readiness or wait mechanism rather than relying on a fixed short delay. Cypress’s CircleCI example uses browser installation and separates browser jobs; the same coverage principles apply to other CI providers. Cross-browser CI guide

6. Keep tests shared and isolate real browser differences

Most application behavior should be tested with the same specs in each selected browser. When a test truly depends on a browser-specific capability, Cypress supports browser-specific test or suite configuration. Cypress.isBrowser() is also available for runtime checks. Keep these exceptions narrow so that one browser does not quietly receive less meaningful coverage. Browser-specific test examples · Cypress browser API

it('checks the Firefox-specific extension flow', { browser: 'firefox' }, () => {
  cy.get('[data-cy=extension-download]').should('be.visible');
});

describe('Chrome-only capability', { browser: 'chrome' }, () => {
  it('runs only where the capability is supported', () => {
    // Browser-specific assertions belong here.
  });
});

You can exclude a browser with a matcher such as { browser: '!chrome' }, but do this only when the test cannot meaningfully run there. If the app needs a particular launch argument, preference, environment value, or extension, Cypress exposes before:browser:launch through setupNodeEvents. Avoid adding browser flags without a concrete need. Launch hook documentation

7. Troubleshoot common failures

Symptom	Likely cause	Fix
“Browser is not installed” or browser absent from selector	The target browser is missing or not discoverable in this environment.	Install it in the local machine or CI image, verify its executable, or pass the binary path with `--browser`.
Browser launch fails in CI	Missing system dependencies, incompatible browser binary, or an environment image without the browser.	Use a Cypress browser image or install the browser and its required system packages; compare local and CI browser versions.
Firefox refuses to launch	The version may be below Cypress’s current supported floor; the current reference says versions before 140 are unsupported.	Upgrade Firefox to a supported version and recheck Cypress’s live browser reference.
WebKit setup errors	Experimental support is not enabled, `playwright-webkit` is absent, or Linux dependencies are missing.	Enable `experimentalWebKitSupport`, install the matching WebKit package, and follow the current platform dependency instructions.
WebKit test fails around `cy.origin()` or Test Replay	These are documented WebKit limitations.	Do not treat the failure as proof that Safari itself behaves the same. Adapt the test if possible, or use another supported validation method for the Safari-specific behavior.
Tests pass locally but fail in CI	Different browser versions, missing app readiness, environment configuration, or timing-sensitive assertions.	Align versions and configuration, wait for the application to be ready, and replace arbitrary sleeps with assertions on observable state.
Run opens Electron unexpectedly	No browser was explicitly selected or the project relies on a default.	Specify an installed supported browser with `--browser`; Electron is deprecated as a test browser.
One test fails only in one browser	Could be a real compatibility defect, a browser-specific limitation, or an assumption in the test.	Reproduce with that browser locally using `--headed`, inspect the browser console and assertion, and only add browser-specific test configuration when justified.

When reporting a launch issue, include the operating system, Cypress version, browser name and version, and relevant launch output. Cypress’s troubleshooting reference describes collecting debug logs for hard-to-diagnose failures. Cypress troubleshooting

8. Runtime, reliability, and cost considerations

Runtime scales with the matrix. Running the same suite in three browsers generally means three browser executions. CI parallelization can reduce elapsed time when supported by your setup, but it consumes more workers.
Choose coverage by risk. A full matrix on every commit offers broad feedback at a higher runtime and infrastructure cost. A full primary-browser suite plus targeted or scheduled secondary-browser runs is a documented alternative.
Control browser versions. Auto-updating binaries can change behavior between runs. Chrome for Testing provides a versioned binary according to Cypress; record the versions used in CI for diagnosis.
WebKit adds uncertainty. Its Cypress support is experimental and has known differences and limitations. Do not make it the sole Safari sign-off.
Keep test conditions comparable. Use the same app build, fixtures, environment variables, and test data across browser jobs unless the difference is intentional.
Budget infrastructure explicitly. More browser jobs and parallel workers use more CI capacity. Cypress’s guide frames the strategy as a balance among confidence, duration, and infrastructure cost; there is no universal optimal matrix.

9. Do it yourself, or capture a rendered page with ScreenshotNeo

Cypress is for automated browser tests and assertions. If your immediate task is to produce a website screenshot or PDF without provisioning a browser in your own script, ScreenshotNeo is a separate website screenshot API and MCP server for developers. A single GET request captures a URL as PNG, JPEG, WebP, or PDF. It does not run Cypress specs or replace cross-browser test coverage. Visit ScreenshotNeo; see the API documentation.

Or skip the browser setup

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://stripe.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.

10. Frequently asked questions

Can Cypress test Safari?

Cypress’s documented option is experimental WebKit, Safari’s browser engine. It is not the Safari application and has known limitations, so do not describe it as full Safari testing.

Do I need separate test files for each browser?

Usually no. Run shared specs in each browser and use browser-specific configuration only for genuine browser-dependent cases.

Does `cypress run` open a visible browser?

No. CLI runs are headless by default. Add --headed when you need to observe a run while debugging.

Can I test browser-specific versions or channels?

Cypress documents browser channel variants for several families and allows selecting a custom binary path. Check the launch reference for currently supported names and requirements.

Should every browser run every test on every commit?

That depends on the product’s risk tolerance, feedback-time needs, and available CI capacity. Cypress documents full-suite and subset or scheduled strategies.