Cypress Electron Browser Deprecation: What You Need to Know

Cypress deprecated its bundled Electron browser as a test browser in Cypress 16.0.0. Electron runs still work during the deprecation period, but Cypress displays a warning. Cypress says Electron will be removed in a future major version; it has not announced which version or a date. Migrate by installing a browser your team intends to test, selecting it as the default or with --browser, updating CI, and confirming the warning is gone.

This guide covers the migration and the behavior to expect. It uses Cypress’s published migration, browser, and CLI guidance; check those sources again when updating Cypress or pinning browser versions.

1. What the deprecation means

Starting with Cypress 16.0.0, the bundled Electron browser is deprecated as a test target. Deprecation does not mean it has already been removed: during the deprecation period, Electron-targeted runs continue to work and emit a warning in cypress run output and the Cypress app.

Cypress plans to remove Electron in a future major release, but its documentation does not name that release or give a removal date. Avoid planning around an assumed deadline. When removal happens, explicit selections such as --browser electron and defaultBrowser: 'electron', as well as runs that fall back to Electron implicitly, will fail.

Electron remains listed as an accepted CLI browser during the deprecation period. The warning is a migration signal, not proof that your current run has failed.

2. Why Cypress is moving away from Electron

Electron bundles a Chromium version tied to the Electron release bundled with Cypress. That Chromium can lag stable Chrome by weeks or months, so it may not include newer web platform features and fixes. Also, embedded Chromium does not necessarily behave exactly like the Chrome browser people use in production.

Testing in an installed browser lets a team exercise the browser engine and update cadence that better match its users. This does not guarantee identical results across engines or mean Chrome is always the right target. Choose based on the browsers your application supports and the behavior your suite needs to cover. See Cypress’s migration guidance.

3. Choose a replacement browser

Browser choice	When it fits	Considerations
Google Chrome	You want coverage in Chrome, a commonly targeted production browser.	Make sure it is installed both locally and in CI. Evergreen updates can alter behavior.
Chromium or Chrome for Testing	You want a Chromium-based target; a specific downloaded version can help with deterministic runs.	Pin and update deliberately when repeatability matters.
Microsoft Edge	Your users or coverage requirements include Edge.	Install it in the environment where Cypress runs.
Firefox	You need coverage in Firefox’s browser engine.	Cypress’s current browser guidance says it cannot launch Firefox earlier than version 140 because older versions have incomplete WebDriver BiDi support.
WebKit	You need to explore WebKit behavior.	Cypress documents WebKit as experimental; treat it differently from its supported browser version policy.

Cypress officially supports the latest three major versions of Chrome, Firefox, and Edge. Browser compatibility changes, so consult the browser launching guide before pinning a version or CI image. Cypress can detect installed browsers automatically, and the CLI accepts installed browser names such as chrome, chromium, edge, and firefox.

4. Migrate a project from Electron

Find every Electron selection. Search your Cypress configuration, package scripts, shell scripts, and CI workflow for --browser electron and defaultBrowser: 'electron'. Also identify jobs that rely on an implicit browser choice.
Install your chosen browser. Install it in each developer environment and in every CI image or runner that executes Cypress. Cypress points to CI guidance for Docker images, its GitHub Action, and its CircleCI Orb.
Select the browser explicitly. Either set a project default or pass the browser on the command line. Explicit selection makes the target clear in local and CI runs.
Update CI. Ensure the browser is present in the runner and change the job command or configuration to select it.
Run the affected suite locally and in CI. Confirm that Cypress launches the intended browser, review any behavior changes, and confirm the Electron deprecation warning no longer appears.

Set the default browser

In your Cypress configuration file, set defaultBrowser to the installed browser you intend to use:

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    defaultBrowser: 'chrome',
  },
})

Use the configuration format and file already used by your project. The example selects Chrome; use another detected, installed browser name where appropriate.

Select a browser in a command or package script

npx cypress run --browser chrome

For a package script, replace any Electron selection with the intended browser, for example:

{
  "scripts": {
    "test:e2e": "cypress run --browser chrome"
  }
}

Then run it with npm run test:e2e. The same CLI option can be used in a CI command. See the Cypress CLI reference for command syntax.

5. Update and verify CI

A local browser installation does not install that browser in CI. Make the browser available in the runner image or workflow, then select it in the Cypress invocation. Cypress’s migration guidance links to its CI setup materials, including Docker images, the GitHub Action, and the CircleCI Orb. Use the current instructions for your CI provider rather than assuming a particular runner includes Chrome.

Check that the browser binary exists in the job environment.
Use the same intended browser name in the CI command or Cypress configuration.
Review the job logs for browser detection and launch errors.
Confirm the Electron deprecation warning is absent from the updated run.
If the suite is sensitive to browser updates, use Cypress’s documented Chrome for Testing or Chromium version download approach and manage the pin as part of your CI image or setup.

Changing browser can change test behavior. A move from Electron to Chrome can make the target more representative for Chrome users, but Cypress does not promise that every suite behaves identically across engines. Investigate failures as browser compatibility or timing issues rather than assuming the migration itself is incorrect.

6. Troubleshooting

Symptom	Likely cause	What to do
Electron deprecation warning still appears	A script, config, CI job, or implicit fallback still selects Electron.	Search the repository and CI definitions for Electron references. Set `defaultBrowser` or pass `--browser` explicitly, then rerun.
Cypress cannot find or launch Chrome	The browser is not installed in that environment, or the selected name does not match a detected browser.	Install Chrome in the local or CI environment. Check Cypress’s browser detection output and use a supported installed browser name.
Local runs pass but CI fails to launch	The CI image or runner does not contain the selected browser.	Use a CI image or setup that installs the browser and confirm the binary is available in the job before Cypress runs.
Tests fail after switching browsers	The browser engine, browser version, rendering, or timing differs from Electron’s embedded Chromium.	Inspect the failing assertion and browser logs. Check whether the test relies on engine-specific behavior or timing; update the test only after confirming the intended behavior.
Firefox fails to launch	The installed version may be below Cypress’s current minimum.	Use Firefox 140 or later under the browser guidance reviewed for this article, and recheck Cypress’s current compatibility page when upgrading.
Results vary after a browser update	An automatically updated browser changed while the suite or CI image stayed the same.	For repeatable runs, pin a supported Chrome for Testing or Chromium version using Cypress’s documented approach, then update the pin intentionally.
A command rejects the browser option	The command may be misspelled, use an unsupported browser name, or run under a different Cypress CLI setup.	Check the exact `--browser` spelling and consult the CLI reference. Try a detected installed browser such as `chrome`, `chromium`, `edge`, or `firefox`.

7. Performance, reliability, and cost considerations

The deprecation guidance does not provide benchmark results for Electron versus installed browsers, so do not assume a performance gain or loss from the migration. Browser startup and test runtime depend on the selected browser, its version, the runner, and the test suite. Measure within your own CI workflow if runtime is a decision factor.

For reliability, keep the browser installation and Cypress selection aligned across developer machines and CI. If automatic browser updates create unpredictable changes, use a supported pinned browser version and schedule updates deliberately. If your goal is broad browser coverage, run the suite against each relevant engine instead of treating one replacement as coverage for all browsers.

The cited Cypress guidance does not state a separate charge for choosing Chrome, Firefox, or another browser. Account for the practical CI costs of installing and maintaining the browser and any runner or image you use; exact cost depends on your infrastructure.

8. Capture browser output without setting up a capture script

If your task is to capture a page image or PDF rather than run Cypress interaction tests, ScreenshotNeo is the alternative to try first: it returns screenshots or PDFs from one API request, and its clean-shot billing excludes bot checks, blank pages, failed loads, and cache hits.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

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}`);
const bytes = Buffer.from(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

See the ScreenshotNeo API documentation for request options. Cookie and consent banners are accepted before capture, and more than 60 known consent platforms, newsletter popups, and chat widgets can be removed; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with response headers identifying the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 screenshots.

9. Frequently asked questions

Does Cypress 16 remove Electron?

No. Cypress 16.0.0 deprecated Electron as a test browser. Runs continue during the deprecation period with a warning.

When will Cypress remove Electron?

Cypress says removal will happen in a future major version, but has not published the version or date in the reviewed documentation.

Can I keep using Electron for now?

Yes, during the deprecation period it continues to run with a warning. Plan a migration before the future removal.

Will switching to Chrome make every test pass the same way?

No such guarantee is documented. Browser engines can differ, so review failures against the behavior your application intends to support.

Is WebKit the recommended replacement?

Not by default. Cypress describes WebKit as experimental. Choose a target that matches your coverage goal and Cypress’s current support guidance.