Cypress 14.0.0 was released on January 16, 2025. Upgrading is more than changing the package version: check your Node.js and operating-system requirements, update tests that cross origins to use cy.origin(), and review browser, component-testing, configuration, and CI compatibility. This guide covers the Cypress 14 migration; Cypress’s migration index now includes later majors, so teams upgrading to a newer release should follow the intervening guides as well.
What changed in Cypress 14?
Cypress 14 introduced component-testing performance and compatibility changes, raised several runtime and platform minimums, and changed how Cypress handles cross-origin tests. The most consequential test-code change is that Cypress no longer injects document.domain by default. Tests that interact with a second origin must use cy.origin() for commands at that origin.
The official Cypress changelog describes the 14.0.0 release. For migration details, use Cypress’s version migration guide.
Check runtime, operating-system, and browser compatibility
Before updating dependencies, compare the environments used to install and run Cypress with the Cypress 14 migration requirements. In particular, check CI images and pinned browser versions, not just a developer’s local machine.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Area | Cypress 14 requirement or change | What to check |
|---|---|---|
| Node.js used for installation | Node.js 18 or newer; Node.js 16 and 21 are no longer supported. | Check the Node version in developer setup, package-manager scripts, and CI. Cypress bundles a separate Node runtime, but installing the Cypress package uses the system Node.js version. |
| Linux | glibc 2.28 or newer is required for the prebuilt binaries. | Check the distribution and glibc version in Linux containers and runners. |
| macOS | macOS 11 (Big Sur) or newer. | Check the operating-system version on local machines and hosted or self-managed runners. |
| Chrome, Firefox, and Edge | Cypress officially supports the latest three major versions of each browser. | Check the actual browser binaries used in CI, especially when they are pinned in an image or installed separately. |
| Firefox | The current Cypress install compatibility note says Firefox 141 or newer requires Cypress 14.1.0 or newer. | If using Firefox 141 or newer, check the current install compatibility note; Cypress 14.0.0 alone does not meet that stated minimum. |
Update tests that cross origins
An origin is defined by its scheme, hostname, and port. A change to any of those creates a different origin. In Cypress 14, a test that visits another origin must use cy.origin() to run commands there—even when both hostnames share a superdomain.
For example, after navigating from https://www.cypress.io to https://docs.cypress.io, wrap the commands that interact with the docs site in a cy.origin() block:
cy.visit('https://www.cypress.io')
cy.origin('https://docs.cypress.io', () => {
cy.visit('/')
cy.get('body').should('be.visible')
})Use the exact origin of the second site, including its scheme and non-default port if applicable. See Cypress’s cy.origin() documentation for the command’s usage and constraints.
Decide what to do with injectDocumentDomain
Cypress added injectDocumentDomain as a transition aid. Setting it to true can reduce the number of cy.origin() calls needed for subdomains, but the setting is deprecated, Cypress warns when it is enabled, and it may break sites. The intended forward path is to add the required cy.origin() calls and remove the transition option. The configuration reference describes its temporary role and compatibility caveats.
Audit removed and deprecated APIs, commands, and configuration
Search test code, support files, Cypress configuration, browser-launch hooks, and package scripts for these changes:
| Find | Migration action |
|---|---|
resourceType in cy.intercept() |
It is deprecated. Review why each use exists and avoid introducing new behavior that depends on it. |
experimentalFetchPolyfill |
Remove it; use cy.intercept() for fetch handling. |
experimentalSkipDomainInjection |
Remove it; the behavior it controlled is now the default. |
cypress open-ct or cypress run-ct |
Replace with cypress open --component or cypress run --component, respectively. |
Cypress.backend('firefox:force:gc') or Cypress.backend('log:memory:pressure') |
Remove these undocumented calls. The migration guide does not give a replacement. |
fetch or XMLHttpRequest from Electron’s about:blank before navigation |
Do not make the request from about:blank; use cy.request() or visit a page first. |
Update browser launch hooks
In the before:browser:launch event, the second argument is launchOptions, not an array. Read browser arguments from launchOptions.args. For example, change code that treats the argument itself as the array to use its args property instead. Cypress documents the hook in its browser launch API.
Rank #4
Verify component-testing dependencies and configuration
If your project uses Cypress component testing, check the framework, bundler, dev-server package, and Cypress configuration format together. Cypress 14 changes minimum supported versions and defaults that can affect how components compile and mount.
| Stack or setting | Cypress 14 change | Migration check |
|---|---|---|
| Webpack dev server | Webpack 4 is no longer supported; the minimum is Webpack 5. | Check the version used by the component-testing dev server and update the project stack if needed. |
| Vite dev server | Vite 4 is no longer supported through @cypress/vite-dev-server; the minimum is Vite 5. |
Check both Vite and @cypress/vite-dev-server. The dev-server package is ESM-only, so a CommonJS Cypress config must move to an ESM context or a TypeScript config when using it. |
| Angular component testing | The minimum Angular version is 18. | Check the Angular version and change the mount import from cypress/angular to @cypress/angular. |
| Vue 2 component testing | Cypress no longer bundles the Vue 2 component-testing harness. | A separately installable @cypress/vue2 package is described as a temporary, deprecated workaround for projects not yet migrated to Vue 3. |
| JIT compilation | The justInTimeCompile component configuration option became the default. JIT does not apply with Vite. |
Review the bundler and component configuration. For another supported setup, set justInTimeCompile: false if you need to disable JIT. |
Upgrade Cypress 14 in a project
- Inventory the project. Identify the Cypress version, package manager, Node.js version used for installation, test types, browser versions, operating systems, component-testing framework and bundler, Cypress config format, and CI commands.
- Check compatibility before changing the dependency. Compare Node.js, glibc or macOS, browsers, and component-testing dependencies with the requirements above. Update CI images or pinned browser versions where necessary.
- Update the Cypress package using your project’s package manager. Follow the repository’s existing dependency and lockfile practices. The exact command depends on whether the project uses npm, Yarn, pnpm, or Bun; do not update the package in a way that leaves the lockfile inconsistent.
- Make code and configuration changes. Add
cy.origin()where tests interact with another origin, remove obsolete options and undocumented backend calls, update browser-launch hooks and component-testing scripts, and adjust framework or bundler configuration as applicable. - Run focused verification, then the full suite. Start with tests that cross origins and component tests, since those are directly affected by major changes. Then run the project’s normal Cypress verification and test commands in the same environments used by CI.
- Upgrade later major versions sequentially if needed. Cypress’s migration index includes versions after 14. If your destination is newer than Cypress 14, consult each intervening migration guide rather than assuming a direct version bump covers every breaking change.
Troubleshoot common Cypress 14 upgrade failures
| Symptom | Likely cause | What to do |
|---|---|---|
| Cypress installation fails or the binary will not run on a Linux runner. | The installer is using an unsupported Node.js version, or the Linux distribution uses glibc older than 2.28. | Check the Node.js version used for package installation and the runner’s Linux/glibc compatibility; move to a supported environment before debugging test code. |
| A test fails after navigating to a different host, scheme, or port. | The test interacts with a second origin without cy.origin(). |
Wrap the commands for the second origin in a block whose origin matches the destination, including scheme and port where relevant. |
| A project still relies on domain injection behavior. | injectDocumentDomain is enabled as a transition setting, or the test suite has not been updated for the default behavior. |
Prefer explicit cy.origin() usage. Treat the deprecated setting as temporary and review Cypress’s configuration caveats before retaining it. |
| Component tests fail to start after the upgrade. | The project may use Webpack 4, Vite 4 with the Cypress Vite dev server, an unsupported Angular version, or a CommonJS config with the ESM-only Vite dev-server package. | Check each installed version and the config module format against the component-testing requirements; update only the stack elements the project uses. |
| Component tests cannot find the Vue 2 harness or Angular mount import. | The bundled Vue 2 harness was removed, or the Angular import path is outdated. | For Vue 2, assess the temporary deprecated @cypress/vue2 workaround or plan a Vue 3 migration. For Angular, use @cypress/angular. |
| CI fails while local browser tests pass. | The CI browser may be pinned outside Cypress 14’s officially supported latest-three-major range, or the CI operating system may fall below the minimum. | Inspect the browser and OS versions in the runner image rather than relying on the locally installed browser’s compatibility. |
| A browser launch hook throws while processing arguments. | The hook treats its second parameter as an array. | Use the launchOptions object and read or modify its args property. |
Or skip the browser setup
If your goal is to capture a page screenshot while working on tests or documentation, ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. A single GET request can return a PNG, JPEG, WebP, or PDF. It is separate from Cypress and does not replace Cypress browser tests.
Best Value
For example, request a WebP screenshot with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; those steps can be disabled. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and responses identify page verdict and billing status in headers. 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 screenshots.
Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Frequently Asked Questions
Does Cypress 14 support Node.js 21?
No. Cypress’s migration guide says Node.js 21 is no longer supported; use Node.js 18 or newer.
Can I keep using Cypress 14 with Vue 2 component tests?
The bundled Vue 2 harness was removed. Cypress documents a separately installable, temporary and deprecated @cypress/vue2 workaround for projects that have not migrated to Vue 3.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
