Engine Coverage Gaps

Cypress launches and controls its own browser instance rather than attaching to one you already have open, so the list of browsers a suite can cover is fixed by what Cypress knows how to automate. As of **Cypress 16.0.0** that list is short and worth knowing exactly. ## The engine families Cypress 16 drives - **Chromium family** (`Cypress.browser.family === 'chromium'`) - Chrome, Chrome Beta, Chrome Canary, **Chrome for Testing**, Chromium, and Microsoft Edge in stable, beta, dev and canary channels. - **Firefox family** (`family === 'firefox'`) - Firefox, Firefox Developer Edition and Firefox Nightly. - **WebKit** (`family === 'webkit'`) - Safari's rendering engine, available only as an opt-in experiment via the `experimentalWebKitSupport` configuration option. - **Electron** - the Chromium build bundled inside Cypress itself. It reports `family: 'chromium'`, and Cypress 16 **deprecates it as a test browser**; it will be removed in a future major version. Cypress auto-detects what is installed on the machine, so a suite driving a bank statement app normally needs no browser paths configured at all: it walks the well-known binary names for each browser above, reads a version out of each one it finds, and offers the result. `cypress info` prints what was found on that machine, which is the fastest way to answer "why is Edge not in the list" on a CI agent you cannot see. ## Choosing one for a run | `--browser` value | Family | Status in Cypress 16 | | --- | --- | --- | | `chrome`, `chrome:beta`, `chrome:canary` | `chromium` | Supported | | `chrome-for-testing` | `chromium` | Supported, pinned build | | `chromium` | `chromium` | Supported | | `edge`, `edge:beta`, `edge:dev`, `edge:canary` | `chromium` | Supported | | `firefox`, `firefox:dev`, `firefox:nightly` | `firefox` | Supported, version 140+ only | | `webkit` | `webkit` | Experimental, opt-in | | `electron` | `chromium` | Deprecated, removal planned | Cypress resolves which browser to launch in a fixed order: 1. A `--browser` value on the command line wins - a name (`chrome`), a name plus release channel (`edge:dev`), or a filesystem path such as `/usr/bin/chromium`. 2. Otherwise the `defaultBrowser` configuration option, if the project sets one. 3. Otherwise the bundled Electron browser - which is exactly the fallback Cypress 16 wants you to stop relying on. In `cypress open` you pick from a dropdown near the top right instead, and the browser is always headed there so you can watch the run. During `cypress run` every browser starts **headless** by default - Electron through its own headless mode, Chrome, Chromium and Edge with `--headless=new`, Firefox with `-headless`, and WebKit headless through Playwright. `--headed` shows the browser, and `--headless` forces it back. That default is why `cypress run` works on a CI machine with no display attached. ## Which versions count as supported Cypress officially supports the **latest three major versions** of Chrome, Firefox and Edge. These browsers are evergreen and their automation interfaces move quickly, so the window is deliberately narrow. One hard stop sits inside it: Cypress cannot launch **Firefox older than 140** at all, and refuses with an error naming the version to install. The consequence for a CI image is that "we installed a browser once" is not a finished job. An evergreen browser moves under a suite, an old pinned one falls out of the window, and both show up as a Cypress problem long before anyone suspects the browser. Chrome for Testing exists as the deliberate answer to the first half of that, and `--browser chrome-for-testing` selects it. ## Reacting to the browser from inside a spec Sometimes a statement page genuinely renders differently per engine and one assertion has to bend: - `Cypress.browser` exposes `name`, `family`, `channel`, `version`, `majorVersion`, `displayName`, `path`, `isHeaded` and `isHeadless`. - `Cypress.isBrowser('firefox')` matches by name, `Cypress.isBrowser('!chrome')` inverts it, an array matches several, and an object filters on properties such as `{ family: 'chromium' }`. - Cypress's test configuration takes a `browser` option, so `describe('embedded PDF viewer', { browser: 'firefox' }, ...)` runs a suite only under Firefox. Reach for these sparingly. Branching a spec per browser is how a suite quietly stops asserting the same behaviour everywhere. ## What is not on the list - **Safari itself cannot be launched.** Experimental WebKit runs Safari's *engine*, obtained from Playwright's `playwright-webkit` package; it is not the Safari application, and it does not carry Safari's own UI behaviour. - **Internet Explorer and real mobile browsers are not options.** Cypress launches desktop browser binaries on the machine running the test. - **A browser Cypress cannot detect is not automatically excluded.** You can pass its path to `--browser`, or add an entry to the `browsers` array returned from `setupNodeEvents` so it appears in the open-mode dropdown; filtering that array is also how you *remove* browsers a team should not use. The practical takeaway for a suite covering a bank statement app: Chromium browsers and Firefox are first-class, WebKit is a partial preview of Safari, and Electron is a fallback you should be actively leaving.