How to Run Cypress Cross-Browser Tests in the Cloud
Run Cypress tests in Chrome, Firefox, and Edge in CI, choose a practical browser matrix, and scale recorded runs with cloud parallelization.
To run Cypress cross-browser tests in the cloud, make the target browsers available on your CI runners, then run Cypress separately for each browser with --browser. For example, use npx cypress run --browser chrome and npx cypress run --browser firefox. Cypress selects an installed browser; it does not install one for you. You can use CI jobs for each browser, or a hosted browser service when you need provider-managed operating systems and browser combinations. [Cypress browser launch guide]
1. Choose where the browsers run
Start with your existing CI runner if it has the browsers and operating system you need. Current GitHub-hosted Ubuntu and Windows runners include Chrome, Firefox, and Edge; macOS runners additionally include Safari. Runner images change, so check the current image documentation and the actual browser versions available to your workflow before relying on a specific combination. [GitHub-hosted runners]
A Cypress Docker browser image is an option when you want a more controlled Linux environment with browsers and Node included. Select a published image tag that matches your Cypress, Node, browser, and architecture needs. The documented browser set differs by architecture: Edge is unavailable in the documented Linux/arm64 browser images. Cypress’s container examples require a Linux runner; do not copy them unchanged to Windows or macOS. [Cypress Docker images] [Cypress GitHub Actions guide]
| Approach | Use it when | Trade-off |
|---|---|---|
| Installed CI runner browsers | Your current runner provides the needed browsers and operating systems. | Runner image contents and browser versions can change. |
| Cypress Docker browser image | You want a more controlled Linux browser and Node environment. | Image tags and architecture constrain available combinations; use a Linux runner. |
| Hosted browser service | You need provider-managed browser and OS combinations. | Check current combinations, concurrency limits, and pricing with the provider. |
2. Run each browser explicitly
Install project dependencies and ensure the selected browser is present on the runner. Then invoke Cypress once for each browser. Browser names accepted by Cypress include Chrome-family browsers, Firefox, and Edge where installed. WebKit support is experimental. Electron is deprecated as a test browser, so select the browser you intend to cover explicitly. [Cypress browser launch guide] [Cypress cross-browser testing]
# Run the full suite in each browser available on this machine
npx cypress run --browser chrome
npx cypress run --browser firefox
npx cypress run --browser edge
# Run only a critical-path subset in a secondary browser
npx cypress run --browser firefox --spec 'cypress/e2e/critical/**/*.cy.js'These commands are examples of Cypress’s documented CLI approach. Adapt the spec path to your repository. Each invocation is a separate run; in CI, separate jobs make the browser and its failures visible in the job name.
GitHub Actions example
This workflow uses the browsers on a GitHub-hosted Ubuntu runner and runs one job per browser. Validate the runner image and available versions for your project, since hosted images are updated. Cypress’s GitHub Actions guidance documents the runner options and workflow setup. [Cypress GitHub Actions guide]
name: Cypress browsers
on:
push:
pull_request:
jobs:
e2e:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
browser: [chrome, firefox, edge]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx cypress install
- run: npx cypress run --browser ${{ matrix.browser }}The workflow assumes the project has a valid package-lock.json, Cypress dependency, and E2E configuration. If you use a different CI provider, keep the same shape: provision the browser, install dependencies, and run Cypress once per browser.
3. Decide how much cross-browser coverage to run
There is no universal browser matrix. Cypress recommends balancing confidence against test duration and infrastructure cost. Choose based on your supported browser policy, application risk, and release process. [Cypress cross-browser testing]
- Every change: Run the main browser on every push or pull request. Add all supported browsers on every change if feedback time and runner capacity allow.
- Nightly: Run additional browsers on a schedule when broader coverage is useful but would slow the normal feedback loop.
- Pre-release: Run the full browser matrix at a release branch or deployment checkpoint.
- Critical path: Run a smaller, high-value subset in secondary browsers on each change, then run the full suite less often.
Keep the matrix aligned with the browsers your application supports. Do not infer browser usage shares or choose a matrix from an unsourced market-share number.
4. Parallelize long runs with Cypress Cloud
Cypress Cloud can distribute spec files across multiple CI machines when the run is recorded and includes --parallel. Each machine needs the same project and a common build identifier so Cloud can associate workers with the same run. Cypress supports common CI providers automatically in many cases. Cloud assigns whole spec files to workers and does not guarantee their execution order. [Cypress Cloud parallelization]
- Set up the project for recording and obtain its record key.
- Store the record key in your CI secret store. Do not commit it to the repository.
- Start multiple CI workers for the same browser run and give them a shared build identifier if your CI integration does not provide one automatically.
- Run the recorded suite with
--parallel. Use a group label to distinguish browser runs in Cloud.
# Example worker command; set CYPRESS_RECORD_KEY as a CI secret
npx cypress run \
--browser chrome \
--record \
--parallel \
--group chromeFor a Firefox matrix job, use --browser firefox --group firefox. The record key can be supplied through the CYPRESS_RECORD_KEY environment variable. Recording and Cloud orchestration are required for Cypress Cloud spec distribution; basic local or CI browser selection with --browser does not itself require Cypress Cloud.
Cloud parallelization works at the spec-file level, so similarly sized specs tend to distribute more evenly. Avoid tests that depend on another spec running first. Adding workers does not guarantee a proportional reduction in elapsed time: suite size, spec duration, available workers, and CI setup overhead all affect the result. [Cypress Cloud parallelization]
5. Consider a managed browser provider when needed
BrowserStack documents Cypress-specific browser and operating system matrix configuration, which can help when you need combinations your own runner images do not provide. Its Cypress documentation also describes parallel execution. Confirm supported combinations, plan limits, and current pricing directly with the provider; the cited setup material does not establish those commercial details. Cypress WebKit support remains experimental, including when used through a provider. [BrowserStack Cypress documentation] [Cypress browser launch guide]
6. Keep browser versions predictable
Chrome is evergreen and can update automatically, which may introduce a browser change between runs. For deterministic results, pin a fixed Chrome for Testing or Chromium version in the environment where your tests run. Docker image tags can also make the browser environment more controlled, but you still need to update deliberately when upgrading your browser or Cypress. [Cypress browser launch guide]
Check Cypress’s current browser requirements for the Cypress version in your project. The browser guide currently notes that Firefox versions below 140 implement WebDriver BiDi incompletely; Cypress versions 15.0.0 through 15.18.1 had a lower floor of 135. This is version-sensitive, so verify the requirement against your installed Cypress release before pinning Firefox. [Cypress browser launch guide]
7. Troubleshoot common failures
| Symptom | Likely cause | Fix |
|---|---|---|
| Cypress says the browser cannot be found or launched. | The browser is not installed, its executable is not discoverable, or the browser name does not match an installed browser. | Install or provision the browser in the runner or use an image that contains it. Check Cypress’s browser launch documentation for supported names and requirements. |
| Edge works on amd64 but is missing in an arm64 container. | The documented Cypress Linux/arm64 browser images do not include Edge. | Use a supported amd64 image or a suitable runner/provider combination, and verify current image availability. |
| Firefox fails to start or behaves unexpectedly. | The version may not meet the current Cypress requirement or may implement WebDriver BiDi incompletely. | Check the Cypress version’s Firefox requirements and provision a compatible Firefox release. |
| Chrome tests pass one day and fail after a runner update. | The hosted runner or evergreen Chrome version changed. | Inspect the browser version in the failing job and pin a fixed Chrome for Testing or Chromium version when stable reproduction matters. |
| Parallel workers do not combine into one Cloud run. | The run is not recorded, --parallel is missing, the key is absent, or workers do not share a build identifier. |
Check the record key secret, enable recording and parallel mode, and make sure workers use the same build identifier. |
| A parallel run is slower than expected or uneven. | Cloud assigns whole spec files; long or uneven specs and worker setup overhead can limit balancing. | Review spec durations, split oversized specs where appropriate, and compare actual CI time before adding capacity. |
| Tests fail only when the spec order changes. | A spec may rely on state created by another spec. | Make specs independently runnable and remove inter-spec ordering assumptions; Cloud does not guarantee spec order. |
| A Docker workflow fails on a macOS or Windows runner. | The copied container setup expects a Linux runner. | Run the container workflow on Linux or use an appropriate non-container runner configuration. |
8. Performance, reliability, and cost
- Performance: Measure end-to-end workflow time, including dependency installation, Cypress startup, and browser launch. Cypress Cloud distributes files across available workers, but no fixed speedup applies to every suite.
- Reliability: Keep browser versions and runner images visible in CI logs. Pin versions when browser drift makes failures hard to reproduce, then schedule intentional upgrades.
- Test design: Make specs independent and roughly similar in runtime to help parallel distribution. Maintain a fast main-browser check and choose secondary-browser frequency based on risk.
- Cost: More browser jobs and CI workers consume more CI capacity; hosted browser products may also have plan limits and charges. Compare measured runtime and required coverage with your CI and provider costs. Check current provider pricing and limits before committing to a plan.
Or skip the browser setup
If your goal is to capture website screenshots rather than test your own application interactions across browsers, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. A single GET request returns a PNG, JPEG, WebP, or PDF. It does not replace Cypress for running application tests.
ScreenshotNeo accepts cookie and consent banners like a visitor, then removes more than 60 known consent platforms, newsletter popups, and chat widgets before the capture; each step can be turned off. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. See the ScreenshotNeo API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport 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)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
FAQ
Can I run Chrome and Firefox in the same Cypress command?
No. Select one browser per Cypress run with --browser; use separate CI jobs or invocations for a browser matrix.
Does selecting a browser install it?
No. The browser must already be installed or provided by the runner or container image.
Does cross-browser testing require Cypress Cloud?
No. Cloud is needed for Cypress Cloud’s recorded parallel spec distribution. Cypress can run in an installed browser without Cloud.
Can Cypress test Safari through WebKit?
Cypress lists WebKit support as experimental. Treat it as experimental coverage and verify the current Cypress guidance before adopting it as a required release gate.
