How to Run Cypress Tests Across Browsers
Run Cypress in Chrome, Firefox, and experimental WebKit locally and in CI, with browser-specific tests, version guidance, and practical debugging steps.
Run Cypress against a chosen browser with --browser: npx cypress run --browser chrome or npx cypress run --browser firefox. Cypress must be able to find that browser in the environment where the command runs. Chrome-family browsers and Firefox are supported; WebKit, the engine used by Safari, is experimental. Cypress’s cross-browser guide and browser-launch guide document the current behavior and setup.
1. Install Cypress and choose a browser
Install Cypress in your project and install the browsers you plan to run. The browser must be available on the same machine, container, or CI runner as Cypress. Cypress detects installed browsers; for an undetected browser, provide its executable path as described in the launching browsers reference.
npm install --save-dev cypress
npx cypress install
npx cypress info
npx cypress run --browser chrome
npx cypress run --browser firefoxcypress info is useful when checking which browsers Cypress sees. Browser names depend on what is installed and detected. Common choices include chrome, chromium, edge, and firefox. Use npx cypress run --help and the launch reference for the exact names, channel syntax, and path option supported by your installed Cypress version.
Run from Cypress open mode
Open the interactive runner with npx cypress open, then select an available browser in the runner before launching the specs. For automated or repeatable runs, specify the browser on the CLI instead.
Use a non-default channel or binary
The browser-launch reference documents selecting non-stable channels with a colon suffix and launching a browser by binary path when Cypress does not detect it automatically. Since local installation paths and supported channel names vary by operating system and browser release, inspect the launch reference for your environment rather than copying a path from another machine.
2. Run the same suite in multiple browsers
Run one Cypress invocation per browser. Each invocation executes the configured suite in that browser.
npx cypress run --browser chrome
npx cypress run --browser firefox
npx cypress run --browser edgeFor a small project, add shortcuts to package.json:
{
"scripts": {
"cy:run": "cypress run",
"cy:run:chrome": "cypress run --browser chrome",
"cy:run:firefox": "cypress run --browser firefox",
"cy:run:edge": "cypress run --browser edge"
}
}Then run npm run cy:run:chrome or another script. These are shortcuts; they do not install or pin the browser. Provision browser versions separately if reproducibility matters.
3. Add browser coverage in CI
Make browsers explicit in CI so each run’s target is clear. Cypress documents provisioning browsers with its Docker images. You can use separate jobs for parallel execution and clearer results, or run commands sequentially in one job when simplicity matters.
# Example job steps after the runner has Node.js, dependencies, and Chrome installed
npm ci
npx cypress install
npx cypress run --browser chrome# A separate job after provisioning Firefox
npm ci
npx cypress install
npx cypress run --browser firefoxConfigure the CI image or setup step to provide each requested browser. A command that works on a developer laptop can fail in CI if the runner image lacks that browser or contains a different version. Cypress’s cross-browser guide includes CI strategies, named jobs, and optional Cypress Cloud recording and grouping. Cloud is an option, not a requirement for running browsers.
Choose how much to run per browser
Full-suite coverage in every browser gives broad confidence but increases execution time and infrastructure use. A common strategy is to run the full suite in the primary browser and a critical-path subset in another browser on each change, then run broader coverage on a schedule or at a release point. Choose based on your users, the browser engines and features your app depends on, the confidence required, and the time and cost available. There is no universal browser matrix or execution-time figure that fits every project.
Keep the browser matrix and selected versions visible in the CI configuration. When a job fails, that makes it easier to distinguish a browser-specific regression from a missing or changed runner dependency.
4. Include or exclude browser-specific tests
Most tests should remain shared across browsers. Cypress also supports browser-based test configuration for cases that genuinely depend on browser behavior. The documented browser configuration accepts matchers following Cypress.isBrowser(), including exclusions such as !chrome. See Writing and organizing tests and the cross-browser guide for syntax compatible with your installed Cypress version.
describe('browser-dependent behavior', { browser: 'chrome' }, () => {
it('checks a Chrome-specific capability', () => {
// Place a test here only when the behavior is genuinely browser-specific.
})
})
describe('shared behavior except for Chrome', { browser: '!chrome' }, () => {
it('runs in the other matching browsers', () => {
// Keep ordinary application behavior covered across browsers where possible.
})
})Use browser filtering narrowly. Excluding a test means that test provides no coverage in that browser; document why the behavior is browser-specific and keep equivalent shared assertions where they apply.
5. Understand browser support and version limits
| Browser family | What to know |
|---|---|
| Chrome, Chromium, Edge | Cypress supports Chrome-family browsers. The launching guide says it officially supports the latest three major versions of Chrome and Edge. Exact detected names and availability depend on the installed environment. |
| Firefox | Supported. The current launch guide documents Firefox 140 as the launch floor; it notes Cypress 15.0.0 through 15.18.1 had a floor of Firefox 135. These are release-dependent details, so check the guide for your Cypress version. |
| WebKit | Experimental. Setup requires enabling experimentalWebKitSupport, installing playwright-webkit, and, on applicable Linux systems, installing extra dependencies. Cypress documents known issues, including no support for cy.origin(). Treat this as testing with the Safari engine, not a guarantee of identical behavior to native Safari. |
| Electron | Deprecated as a test browser and documented for removal in a future Cypress version. Specify a browser explicitly to avoid relying on a bundled default. |
The version floors and browser support can change. Pin or provision browser versions in your development and CI environments when repeatable results matter, and check the official launch documentation before upgrading Cypress or changing runner images.
WebKit setup
Follow the experimental setup in Cypress’s browser-launch guide: enable experimentalWebKitSupport in Cypress configuration, install playwright-webkit, and install the listed system dependencies when running on Linux. Then launch using the WebKit browser name documented for your Cypress release. Because support is experimental and has known limitations, use this as additional engine coverage rather than treating it as a substitute for every Safari-specific check.
6. Debug browser differences
cypress run is headless by default. To inspect a failure in a visible browser, add --headed:
npx cypress run --browser chrome --headedCypress recommends reproducing headless-only failures in headed mode. Compare the same spec, browser version, runner environment, and application build before drawing conclusions. Browser engines can differ in rendering, APIs, timing, and network behavior, so reduce the issue to a focused test and inspect the browser-specific error and Cypress command log.
As of Cypress 16, Chrome, Chromium, and Edge use native browser network interception, while Firefox and WebKit retain the legacy network path, according to the configuration reference. This can matter when diagnosing interception behavior; confirm the Cypress version and applicable configuration reference before attributing a difference to the application.
7. Common problems and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
| “Browser not found” or Cypress cannot launch the requested browser | The browser is not installed, its name is not recognized, or its binary is outside Cypress’s detection paths. | Install it in the current environment, check detected browsers with npx cypress info, verify the browser name for your Cypress release, or use the documented binary path option. |
| Works locally, fails in CI | The CI image does not contain the selected browser, or local and CI browser versions differ. | Provision the browser in the runner or use an appropriate Cypress Docker image. Make browser versions explicit where possible. |
| Firefox fails to launch | The installed Firefox is below the launch floor for the Cypress version. | Check the current launch reference. Its Firefox minimum is release-dependent; upgrade Firefox or use a compatible Cypress/browser combination. |
| WebKit setup or specs fail | Experimental support may not be enabled, the WebKit package or Linux dependencies may be missing, or the test may use an unsupported feature such as cy.origin(). |
Follow the exact experimental setup for your Cypress version and review its documented known issues. Keep WebKit results separate from stable browser coverage. |
| Headless failure is hard to reproduce | The failure depends on visible rendering, timing, or environment details. | Repeat with --headed, then compare the browser version, runner, and spec. Cypress specifically recommends headed reproduction for headless-only failures. |
| Network interception differs by browser | Browser-specific interception implementation or Cypress-version behavior. | Check the configuration reference for your version; Cypress 16 uses native interception in Chrome, Chromium, and Edge, while Firefox and WebKit retain the legacy path. |
| A test is skipped in one browser | A browser matcher includes or excludes it. | Inspect the test or suite’s browser configuration and confirm that the exclusion is intentional. |
8. Performance, reliability, and cost
Each browser invocation adds work, and separate CI jobs may require additional runner capacity. Reduce the matrix by matching coverage to risk: use the full suite where it gives the most confidence, select critical paths for additional per-change coverage, and schedule broader runs when appropriate. Cypress’s guide frames this as a balance among confidence, test time, and infrastructure cost; it does not provide a universal numeric cost or speed estimate.
For repeatable results, provision browsers deliberately and keep versions consistent across the environments you compare. Treat experimental WebKit failures with its support status and known limitations in mind. When a test fails, retain enough CI output to identify the browser and version, and reproduce with the same target before changing application code.
9. Or skip the browser setup
If your goal is to capture a page image or PDF rather than exercise interactive application behavior, ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. It does not run Cypress tests or replace browser automation.
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}`);
See the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
Sign up for ScreenshotNeo and get 1,000 free screenshots a month, with no card required.
10. FAQ
Can I run Cypress in Safari?
Cypress offers experimental WebKit support, which tests the Safari engine. It is not a guarantee of identical behavior in native Safari, and it has documented limitations.
Do I need Cypress Cloud for cross-browser runs?
No. You can run Cypress locally or in CI with browser-specific commands. Cloud recording and grouping are optional workflows described in Cypress’s cross-browser guide.
Should every browser run every spec?
That depends on the confidence you need and the time and infrastructure available. A full suite in one browser with critical-path coverage elsewhere is one strategy; broaden coverage when your risk or release process calls for it.
Why specify a browser if Cypress has a default?
An explicit browser makes the target clear and avoids depending on a bundled default, especially as Cypress documents Electron as deprecated.
