How to test Cypress on different browsers and devices?

Last updated

Cypress runs tests in Chromium-based browsers (Chrome, Edge and Electron), Firefox, and WebKit, the engine behind Safari. That covers most of what a cross-browser suite needs, with two limits worth knowing before you plan around it: WebKit support is experimental rather than a real Safari, and Cypress does not drive physical mobile devices at all.

Which browsers can Cypress test?

  • Chrome, including Chrome Beta, Canary and Chrome for Testing builds.
  • Edge, which is Chromium underneath.
  • Electron, the default, bundled with Cypress so it always works with no install.
  • Firefox.
  • WebKit, experimental. It uses Playwright's WebKit build, not Safari itself, so it approximates Safari's engine without being the browser your users run.

Internet Explorer and real Safari are not supported, and neither are iOS or Android browsers.

Running your tests on a different browser

Cypress detects the browsers installed on the machine. Pick one at run time:

cypress run --browser chrome
cypress run --browser firefox
cypress run --browser edge
cypress run --browser electron

You can pin a specific channel or an absolute path when you need a particular build:

cypress run --browser chrome:beta
cypress run --browser /usr/bin/chromium-browser

Each run gets a fresh browser profile with clean history and cookies, so state from a previous run cannot change the result of the next one.

To see which browsers Cypress has found on the current machine:

cypress info

Running the same spec on every browser

There is no built-in "all browsers" flag. In CI you fan the run out into one job per browser, which also keeps the wall-clock time flat as you add browsers rather than multiplying it. In GitHub Actions that is a matrix:

strategy:
  matrix:
    browser: [chrome, firefox, edge]
steps:
  - run: npx cypress run --browser ${{ matrix.browser }}

Inside a spec you can also branch on the browser, which is useful when one engine genuinely behaves differently and you do not want a blanket skip:

it('uses the clipboard', { browser: '!firefox' }, () => {
  // only runs where the clipboard API behaves as the test expects
})

What about Safari and mobile browsers?

This is where a Cypress-only strategy runs out. The WebKit build ships with Cypress and is marked experimental, and it is not Safari: it does not carry Safari's own quirks, its version does not track what Apple shipped, and nothing about it exercises iOS. If a Safari or mobile bug is the kind of bug you need to catch, Cypress alone will not catch it.

Two honest options. Test the WebKit engine with Cypress and accept the gap, or run the browsers you actually care about with a tool that drives them. Cypress can also be run against browsers hosted elsewhere, which is how most teams get Chrome, Edge and Firefox coverage in parallel without installing anything locally.

Viewport size is not device testing

Setting a small viewport is a common substitute for mobile testing and it is not the same thing:

cy.viewport('iphone-x')
cy.viewport(375, 812)

That resizes a desktop browser. It does not give you mobile Safari or Chrome on Android, touch behaviour, the real user agent, device pixel ratio, or the memory limits of a phone. It is a good way to test your responsive breakpoints and a poor way to test whether your site works on an iPhone.

Common cross-browser failures in Cypress

  • Missing browser in CI. The Cypress Docker images that include browsers are pinned to specific versions, and a run that assumes Chrome is present will fail on an image that only carries Electron.
  • Firefox memory. Long Firefox runs consume noticeably more memory than Chromium ones, and a container without enough headroom fails in ways that look like flaky tests.
  • WebKit gaps. Experimental support means some commands and network stubbing behave differently, so a WebKit-only failure is as likely to be Cypress as your application.
  • Assuming parity. Chrome and Edge share an engine, so passing both proves less than it appears. Firefox and WebKit are where genuine engine differences surface.

TestingBot runs Cypress tests on a hosted grid of browsers, in parallel, with video and logs captured for every run. You keep your spec files as they are and get Chrome, Edge and Firefox coverage without maintaining the machines. See running Cypress tests in the cloud, and Selenium Grid if you also need real Safari and mobile devices that Cypress cannot reach.

Other Questions