How to Upgrade Cypress 13 or 14 to Cypress 15

Direct answer: Upgrade Cypress one major version at a time. If you are on Cypress 13, first complete the 13-to-14 migration, then apply the 14-to-15 changes. If you are already on 14, check Cypress 15’s runtime and component-testing requirements, update the dependency, fix applicable breaking changes, and run Cypress verification and your project’s tests.

Cypress 15 requires Node.js 20, 22, 24, or later to install its binary; Node.js 18 and 23 are no longer supported. On Linux, prebuilt binaries require glibc 2.31 or newer. Firefox requirements depend on the exact Cypress 15 minor: 15.0.0–15.18.1 requires Firefox 135 or later, while 15.19.0 and later requires Firefox 140 or later. Check the official Cypress migration guide for the applicable version details.

1. Confirm your starting point and prerequisites

Before changing dependencies, establish which Cypress version is actually installed and which runtime and browser versions your local and CI environments use. A package manifest may specify a range, while the lockfile and installed package determine what a given run uses.

npx cypress version
node --version
npm ls cypress

Use the equivalent package listing command for your package manager if you use Yarn or pnpm. Also inspect your CI workflow, container image, and browser setup; upgrading locally does not update those environments automatically.

Check	Cypress 15 requirement or action
Starting major	For version 13, complete the 13-to-14 migration before upgrading to 15. For version 14, proceed to the 14-to-15 migration.
Node.js	Use Node.js 20, 22, 24, or later for Cypress binary installation. Node.js 18 and 23 are unsupported.
Linux system libraries	Prebuilt binaries require glibc 2.31 or newer.
Firefox	Use Firefox 135+ for Cypress 15.0.0–15.18.1; Firefox 140+ for Cypress 15.19.0+.
Component-testing bundler/framework	Use Webpack 5+, Vite 5+, and Angular 18+ where applicable; Cypress 15 drops support for Webpack 4, Vite 4, and Angular 17 component testing.

If a CI provider installs Firefox or supplies a fixed image, verify the actual version in that environment. A locally compatible browser does not prove that the CI browser meets the minimum for your chosen Cypress 15 minor.

2. Upgrade from Cypress 13 to 14 first

Do not skip the intermediate major. Follow the official migration guidance for your exact 13-to-14 transition, address its applicable changes, and run the project’s relevant tests before proceeding. This isolates regressions and makes it easier to identify which upgrade introduced them.

Commit or otherwise preserve a clean working state before each major upgrade. Review package scripts and Cypress configuration so you know how to run the same checks after each change.

3. Update Cypress to version 15

Once the project is on Cypress 14 and its migration checks pass, update the dependency using the package manager already used by the project. Choose a Cypress 15 release that fits your project’s browser and environment constraints, and let the package manager update the lockfile.

npm

npm install --save-dev cypress@15

Yarn

yarn add --dev cypress@15

pnpm

pnpm add --save-dev cypress@15

These commands request the Cypress 15 major through the package manager. Review the resulting manifest and lockfile diff, especially if your repository pins exact versions or uses a shared dependency policy. In a monorepo, run the command in the package that owns Cypress and check whether root-level tooling also needs updating.

4. Apply Cypress 15 code and configuration changes

Search application tests and Cypress configuration for the affected APIs and component-testing integrations. Make only the changes relevant to code your project uses.

Use `exitCode` with `cy.exec()`

Change assertions that read the command result’s code property to read exitCode.

// Before
cy.exec('npm run check').its('code').should('eq', 0)

// After
cy.exec('npm run check').its('exitCode').should('eq', 0)

Pass stub implementations with `callsFake()`

When supplying a fake implementation, create the stub and then call callsFake().

// Before
cy.stub(object, 'method', fakeImplementation)

// After
cy.stub(object, 'method').callsFake(fakeImplementation)

Update component-testing dependencies and configuration

Replace Webpack 4 with Webpack 5 or newer if your component-testing setup uses Webpack.
Replace Vite 4 with Vite 5 or newer if your component-testing setup uses Vite.
Use Angular 18 or newer for Angular component testing.
The @cypress/vite-dev-server package is ESM-only. If your Cypress config is CommonJS and imports that package, move the config into an ESM context, such as a cypress.config.mjs file, and use ESM imports.

// cypress.config.mjs
import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    // Keep your project's supported component-testing setup here.
  },
})

Adapt the example to your existing configuration and framework adapter. Do not remove project-specific setup simply to make the file resemble this minimal example.

5. Verify Cypress and run your project checks

After resolving the migration items, verify the Cypress installation and run the project’s test commands. Run the checks in the environments that matter, including CI where configuration or browser versions differ.

npx cypress verify
npx cypress run

If your project uses separate scripts or component and end-to-end suites, run those scripts as well. A successful Cypress binary verification confirms the binary can be verified in that environment; it does not establish that application tests pass or that every browser and CI matrix entry is compatible.

Review the dependency and lockfile diff.
Run Cypress verification and the relevant local test suites.
Run the CI workflow or equivalent checks using the project’s supported Node.js, Linux, and browser versions.
Investigate failures before moving the upgrade into a shared or release branch.

Common errors and fixes

Symptom	Likely cause	Fix
Cypress cannot install or verify its binary	The environment uses an unsupported Node.js version or lacks a required system library.	Use Node.js 20, 22, 24, or later. On Linux, confirm glibc is at least 2.31, then reinstall or verify in the same environment that runs tests.
Firefox tests fail after the upgrade	The installed Firefox is below the minimum for the Cypress 15 minor in use.	Check the exact Cypress version. Use Firefox 135+ for 15.0.0–15.18.1, or 140+ for 15.19.0 and later; update pinned CI images or provider settings as needed.
An assertion against `cy.exec()` fails because a property is missing	The test still reads `code`.	Change `.its('code')` to `.its('exitCode')`.
A stub call rejects its implementation argument	The test uses the removed three-argument form.	Use `cy.stub(object, 'method').callsFake(fakeImplementation)`.
Component tests fail to start with an unsupported bundler or framework	The setup still uses Webpack 4, Vite 4, or Angular 17 component testing.	Upgrade to Webpack 5+, Vite 5+, or Angular 18+, as applicable, and align the Cypress component adapter configuration.
CommonJS config cannot load `@cypress/vite-dev-server`	The package is ESM-only, but the configuration is loaded as CommonJS.	Use an ESM Cypress config context, for example a `.mjs` file with ESM imports, and check the rest of the config for CommonJS-only syntax.
Local run passes but CI fails	CI may use a different Node.js version, Linux base image, Firefox version, lockfile install, or environment variables.	Compare the actual versions and install process in both environments; update the CI image or configuration and reproduce the CI command locally where possible.

Performance, reliability, and upgrade cost

The Cypress version change itself does not tell you how long your suite will run or whether your application is compatible. Runtime depends on the project’s tests, browser, CI resources, and configuration. Compare the same suites and environment before and after the upgrade if you need to assess a performance change.

For reliability, upgrade each major in a separate reviewable step, preserve the lockfile change, and exercise the same browser and CI matrix used for releases. Pay particular attention to environments that pin Firefox or use older Linux images. This gives failures a narrower set of likely causes.

Budget for engineering time to update dependencies, configuration, and tests and to validate the CI matrix. The migration guide does not guarantee a particular application will pass; the required work depends on which APIs and integrations the project uses.

Or skip the browser setup

If your goal is to capture a website image while documenting or debugging an upgrade, ScreenshotNeo provides a one-request screenshot API and an MCP server for AI agents. The Cypress upgrade steps above still apply to your test suite; ScreenshotNeo is an alternative for website screenshot capture.

ScreenshotNeo accepts a URL and returns a PNG, JPEG, WebP, or PDF. Cookie and consent banners, newsletter popups, and chat widgets are removed before capture, and each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. Plans include 1,000 screenshots a month free 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.webp

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)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

FAQ

Can I upgrade directly from Cypress 13 to 15?

Use the 13-to-14 migration first, then the 14-to-15 migration. This follows the sequential major-version guidance and helps isolate regressions.

Does Cypress 15 support Node.js 18?

No. Cypress 15 requires Node.js 20, 22, 24, or later for binary installation; Node.js 18 and 23 are no longer supported.

Do I need to change tests that use `cy.exec()` or `cy.stub()`?

Change the result assertion from code to exitCode, and pass stub fakes through .callsFake() where those patterns occur.

Is Cypress 15 the newest major?

The migration guide currently also documents Cypress 16. This guide focuses on reaching the requested Cypress 15 target; consult the guide before planning a later major upgrade.