Run Cypress Cross-Browser Tests in Chrome, Firefox, Edge & WebKit

This guide walks you through running Cypress tests across Chrome, Firefox, Edge, and WebKit. You’ll learn how to configure Cypress, run tests in each browser, and handle common issues. By the end, you’ll be able to verify your app works consistently across all major browser engines.

What You’ll Need

A project with Cypress installed (version 10 or later recommended).
Node.js and npm (or yarn) installed.
Chrome, Firefox, and Edge installed on your machine (WebKit is bundled via Playwright).
Basic familiarity with Cypress test files and the Cypress CLI.

Step-by-Step

Install Cypress and the WebKit browser support. If you haven’t already, install Cypress in your project: npm install cypress --save-dev. For WebKit support, install the Playwright browser: npm install --save-dev @playwright/test and then run npx playwright install webkit to download the WebKit browser.
Verify browser availability. Run npx cypress open to launch the Test Runner. In the browser dropdown, you should see Chrome, Edge, Firefox, and WebKit (if installed). If any are missing, check your installation or Cypress configuration.
Configure Cypress for cross-browser testing (optional). In your cypress.config.js file, you can set the default browser or define a list of browsers to use. For example, to set the default browser to Firefox, add: module.exports = defineConfig({ e2e: { browser: 'firefox' } }). This is optional; you can also specify the browser per run.
Run tests in a specific browser via CLI. Use the --browser flag to run tests in a specific browser. For example: npx cypress run --browser chrome for Chrome, --browser firefox for Firefox, --browser edge for Edge, and --browser webkit for WebKit.
Run tests in all browsers sequentially. To run the same test suite across all browsers, you can chain commands: npx cypress run --browser chrome && npx cypress run --browser firefox && npx cypress run --browser edge && npx cypress run --browser webkit. This runs tests one after another, generating separate reports for each.
Use a script to run all browsers (optional). For convenience, add a script in your package.json: "test:all": "cypress run --browser chrome && cypress run --browser firefox && cypress run --browser edge && cypress run --browser webkit". Then run npm run test:all.
Handle browser-specific test logic (if needed). Use the Cypress.browser object to conditionally run code based on the browser. For example: if (Cypress.browser.family === 'firefox') { ... }. This is useful for known browser quirks.
Review results. After running, Cypress generates test reports in the cypress/results folder (if configured) and outputs a summary in the terminal. Check for failures and address any browser-specific issues.

Common Mistakes

Forgetting to install WebKit. WebKit is not bundled with Cypress by default; you must install Playwright and run npx playwright install webkit.
Using browser names incorrectly. Use the exact browser names: chrome, firefox, edge, webkit (not “Google Chrome” or “Safari”).
Assuming identical behavior across browsers. CSS, animations, and APIs can differ. Always run tests in each browser to catch discrepancies.
Not handling browser-specific timeouts. Some browsers may be slower; consider adjusting default command timeouts via defaultCommandTimeout in your config.

Tips

Use a CI pipeline. Integrate cross-browser tests into your CI (e.g., GitHub Actions, CircleCI) to run them automatically on every push.
Parallelize with Cypress Cloud. If you have many tests, consider using Cypress Cloud to run tests in parallel across browsers, saving time.
Keep your browsers updated. Outdated browsers can cause false failures due to missing features or bugs.
Use environment variables for browser selection. For flexibility, set the browser via an environment variable: CYPRESS_BROWSER=firefox npx cypress run and read it in your script.

Troubleshooting

Browser not launching. If a browser fails to launch, ensure it’s installed and accessible. For WebKit, re-run npx playwright install webkit. For Chrome/Edge, check that the executable is in your PATH.

Tests fail only in one browser. Inspect the error message; it may indicate a CSS or JavaScript incompatibility. Use Cypress.browser to skip or adjust tests conditionally, but first try to fix the underlying issue.

WebKit tests are slow. WebKit is generally slower than Chrome; increase timeouts or run fewer tests in parallel. Also, ensure your system meets Playwright’s requirements.

Edge not showing up. On Windows, Edge is usually installed. On macOS/Linux, you may need to install Microsoft Edge manually. Cypress detects it automatically if installed.

Frequently Asked Questions

Can I run tests in Safari?

No, Cypress does not support Safari directly. Use WebKit (via Playwright) to simulate Safari’s engine.

How do I run tests in multiple browsers at the same time?

Cypress does not support parallel execution across browsers in a single run. Use Cypress Cloud or run separate processes concurrently.

Can I use a custom browser path?

Yes, in cypress.config.js you can specify a custom path for a browser using the browsers array. See Cypress docs for details.

Do I need Playwright installed to run WebKit?

Yes, Cypress uses Playwright’s WebKit build. Install it with npm install --save-dev @playwright/test and run npx playwright install webkit.

Why do my tests pass in Chrome but fail in Firefox?

This is common due to differences in CSS rendering, JS APIs, or event handling. Check the failure details and use browser-specific workarounds if necessary.

Can I run cross-browser tests in headless mode?

Yes, use the --headless flag with cypress run. For example: npx cypress run --browser firefox --headless.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →