Cross-Browser Testing with Cypress: A Practical Guide
Run Cypress tests in Chrome and Firefox, plan a useful CI browser matrix, and understand the limits of experimental WebKit support.
Cypress can run tests in Chrome-family browsers, including Edge, and Firefox. WebKit support is experimental. Install the browser in the environment where Cypress runs, then select it in the Cypress app or pass its name to cypress run --browser. A practical CI strategy is to run the full suite in a primary browser and a smaller set of critical-path tests in another browser when duplicating every test would cost too much time or CI capacity. Cypress cross-browser testing guide · Browser launch reference.
1. Browser support and what “cross-browser” means
Cypress supports Chrome-family browsers (including Edge) and Firefox. It can also launch WebKit experimentally. The browser is software installed in the local or CI environment; Cypress launches its own browser instance with an isolated test profile rather than reusing a person’s everyday browser session.
| Browser target | What to know |
|---|---|
| Chrome-family | Includes Chrome for Testing, Chrome channels, Chromium, and Edge and its release channels. Chrome is evergreen and can update automatically. |
| Firefox | Stable releases and channels are available when installed. Current Cypress launch requirements are version-sensitive; consult the reference for the Cypress release in use. |
| WebKit | Experimental browser-engine coverage. It needs opt-in configuration and additional installation steps; feature limitations apply. It is not ordinary supported Safari automation. |
| Electron | Cypress marks Electron deprecated. Do not make it the implicit definition of browser coverage; check current migration guidance for the Cypress version you use. |
Cypress officially supports the latest three major versions of Chrome, Firefox, and Edge, according to its current launch reference. That policy can change. The same reference says current Cypress cannot launch Firefox versions older than 140 because their WebDriver BiDi implementation is incomplete; Cypress 15.0.0 through 15.18.1 had a Firefox floor of 135. Verify the applicable support page when upgrading Cypress or choosing a pinned browser.
2. Run a Cypress suite in another browser
Prerequisites
- Install the project dependencies and Cypress using your project’s package manager.
- Install the browser you intend to run in the same environment as Cypress.
- Confirm the browser version meets the launch requirements for your Cypress version.
Run commands
# Run the project suite in Chrome
npx cypress run --browser chrome
# Run it in Firefox
npx cypress run --browser firefox
# Run a specific spec in Firefox
npx cypress run --browser firefox --spec "cypress/e2e/checkout.cy.js"For other detected browser names, use the name Cypress reports or documents for that browser, such as edge. Check the current launch reference for available names and channel-specific behavior. In the interactive Cypress app, open the browser selector and choose an installed browser before starting the run.
Make browser selection explicit in package scripts
{
"scripts": {
"cy:chrome": "cypress run --browser chrome",
"cy:firefox": "cypress run --browser firefox",
"cy:firefox:critical": "cypress run --browser firefox --spec 'cypress/e2e/critical/**/*.cy.js'"
}
}Then run npm run cy:chrome or npm run cy:firefox. Adjust the spec paths to your project. Explicit commands make the intended coverage visible in local workflows and CI.
3. Choose a useful browser matrix
Running every test in every browser increases confidence in browser-specific behavior, but also increases run duration and infrastructure use. Cypress documents an approach that runs all tests in Chrome and a selected critical-path subset in Firefox. Treat that as a pattern to adapt to your users and product risks, not a universal required matrix.
| Coverage choice | Good fit | Trade-off |
|---|---|---|
| Full suite in one browser | Fast feedback in the browser your team primarily targets. | Provides limited evidence about other engines. |
| Full suite in primary browser plus critical specs in another | Teams needing additional engine coverage while keeping CI work bounded. | Only the selected specs receive the additional-browser check; this is not full parity coverage. |
| Full suite in each target browser | Products where broad behavior across engines justifies the extra runtime and capacity. | Duplicates work and can make feedback slower or more resource-intensive. |
Choose targets based on the browsers and engines important to your audience, the breadth of specs you can afford to run, reproducibility needs, and support maturity. There is no universal ideal number of browsers or evidence-backed percentage of defects caught by cross-browser testing.
4. Configure browser jobs in CI
Install each browser explicitly in the CI environment, or use a Cypress browser image that includes the browser and dependencies. Keep separate browser jobs or commands with names that show their coverage. Cypress’s CI documentation covers browser images and setup options: Cypress continuous integration overview.
# Example job commands; configure these in your CI provider's job steps.
npm ci
npx cypress run --browser chrome
# A separate job can run the critical-path subset in Firefox.
npm ci
npx cypress run --browser firefox --spec "cypress/e2e/critical/**/*.cy.js"The commands are intended to be steps in separate jobs when parallel browser feedback is useful. Configure the CI provider to install or supply each requested browser before the Cypress command. The exact YAML and browser installation command depend on the CI provider and image you choose; avoid assuming that a browser exists in a generic runner.
Reproducibility and upgrades
Chrome can auto-update, which may change test behavior between runs. Cypress recommends Chrome for Testing where deterministic Chrome runs matter: its versioned binary does not auto-update. Pinning browser versions locally and in CI can reduce environment drift. Schedule deliberate Cypress and browser updates so pinned versions do not become stale, and record the versions used when investigating a failure.
5. Experimental WebKit setup
WebKit can provide a check against Safari’s browser engine, but Cypress labels this support experimental. The documented setup requires enabling experimentalWebKitSupport: true, installing playwright-webkit, and installing additional Linux dependencies where applicable. Follow the current launching browsers reference for the commands and requirements corresponding to your Cypress version.
// cypress.config.js (illustrative configuration)
const { defineConfig } = require('cypress')
module.exports = defineConfig({
experimentalWebKitSupport: true,
})After installing the documented WebKit package and operating-system dependencies, check whether Cypress detects WebKit and use the browser name specified in the launch reference. WebKit has documented limitations, including unsupported cy.origin() and Test Replay. An experimental WebKit run is an engine check; it does not erase differences between that environment and a user’s full Safari installation.
6. Screenshot checks alongside browser tests
Browser tests can assert behavior and state. When a failure is easier to understand visually, capture a screenshot using Cypress’s screenshot facilities and retain it with the CI artifacts according to your runner’s artifact settings. Keep screenshots tied to a named browser job and the failing spec so investigators know which environment produced them.
For a separate screenshot of a live page or for image/PDF capture outside a Cypress test, ScreenshotNeo is a website screenshot API and MCP server. It is not a Cypress browser runner, but can complement a test workflow when you need a captured page rather than another test execution.
7. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Cypress cannot find or launch the browser | The requested browser is not installed, is not detected, or the name is wrong. | Install it in the same local/CI environment as Cypress and use a documented browser name. In the Cypress app, check the browser selector. |
| Firefox launches locally but fails in CI | CI has a different or older Firefox binary, or lacks required environment dependencies. | Check the Cypress and Firefox versions against the current launch reference; install the intended browser in CI or use an appropriate Cypress browser image. |
| Current Cypress rejects an older Firefox | That version may be below the current launch floor. The documented floor has changed across Cypress releases. | Check the support details for your exact Cypress release and upgrade the browser or use a compatible Cypress/browser pairing. |
| Tests behave differently after a browser update | An evergreen browser version changed between runs. | Use a versioned Chrome for Testing binary where reproducibility matters, record versions, and upgrade deliberately. |
| WebKit configuration is ignored or browser launch fails | The experiment is not enabled, the package or OS dependencies are missing, or the selected feature is unsupported. | Follow the current WebKit setup instructions, install dependencies, and check the documented limitations before treating the failure as an application bug. |
| A second browser job passes while another fails | The environment or browser-specific behavior differs, or the two jobs do not run the same specs. | Compare job browser versions and spec lists first. If coverage is partial by design, confirm whether the failing spec belongs to that job’s declared scope. |
8. Performance, reliability, and CI cost
- Run only useful extra coverage. A critical-path subset in a second engine can control runtime while checking high-risk flows.
- Make jobs independent and explicit. Separate browser jobs clarify failures and allow CI parallelism where your provider and capacity support it.
- Stabilize the environment. Pin browser versions when drift is costly, but update those pins deliberately. Record Cypress and browser versions in CI logs or job metadata.
- Interpret failures in context. Browser launch problems, missing dependencies, experimental feature gaps, and application defects need different fixes.
- Budget for duplication. More browser runs consume more execution time and CI resources. Select the matrix based on user risk and available capacity; do not assume a fixed number of browsers is optimal.
9. Or skip the browser setup
For a screenshot of a page without installing and launching a browser yourself, ScreenshotNeo accepts one GET request with the target URL and returns an image or PDF. See the ScreenshotNeo API documentation.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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 removes cookie banners, newsletter popups, and chat widgets before the shot; each cleanup step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, with response headers reporting the page verdict and billing status. Its MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. The API also supports PDF and configurable capture options; consult the docs for parameters.
Sign up free for 1,000 screenshots a month with no card.
10. FAQ
Does Cypress test Safari?
Cypress’s WebKit support is experimental. It can check the WebKit engine with documented setup and limitations, but should not be described as ordinary full Safari automation.
Do I need a separate Cypress project for each browser?
No. Select the browser with the app’s browser selector or the --browser run option. Separate CI jobs are useful for clarity and parallel scheduling, but they can use the same project.
Should every test run in every browser?
That depends on product risk and CI capacity. Cypress documents a full suite in one browser with selected critical-path coverage in another as one practical trade-off.
Can I rely on the same Firefox minimum forever?
No. Browser compatibility requirements depend on the Cypress release. Check the current launching browsers page when upgrading or pinning versions.
