---
id: app/references/migration-guide
title: Migration Guide | Cypress Documentation
description: A guide to help you migrate to the latest version of Cypress.
section: app
source_path: docs/app/references/migration-guide.mdx
version: 1375fa62d5875962138c8c43f27d7e1235a504a5
updated_at: '2026-04-29T19:28:48.012Z'
---
# Migration Guide

## Migrating away from Cypress.env()

Starting with Cypress 15.10.0, `Cypress.env()` has been deprecated and will be removed in a future major version. This guide helps you migrate to [`cy.env()`](/llm/markdown/api/commands/env.md) (for sensitive values) or [`Cypress.expose()`](/llm/markdown/api/cypress-api/expose.md) (for public/non-sensitive values), depending on your use case.

### Why Cypress.env() is deprecated

`Cypress.env()` makes it easy to accidentally expose more data than intended because Cypress hydrates all configured environment variables into the browser context. That includes values your test never reads.

This deprecation is a precaution to reduce the risk of unintentionally exposing secrets in the browser-accessible state when run within the Cypress browser. This is about ensuring safer defaults and preventing accidental exposure of sensitive data.

#### What's the risk

When Cypress environment values are available in the browser, they can be inspected through normal browser tooling and may be accessible to code running in that context (for example, app code, third-party scripts, or extensions). The core issues are:

1. **All-or-nothing exposure**: All environment variables are serialized and sent to the browser where they can be accessed via `Cypress.env()` or inspected in the browser's developer tools.
2. **Cross-origin risks**: When using [`cy.origin()`](/llm/markdown/api/commands/origin.md) for cross-origin testing, all environment variables are automatically passed to the cross-origin context, potentially exposing sensitive data to untrusted origins.
3. **Application code access**: Since environment variables are available in the browser context when tests run, your application code or third-party scripts could potentially access them if it checks for `window.Cypress` or similar patterns.

### Choose the right migration path

When migrating from `Cypress.env()`, you have two options: `cy.env()` and `Cypress.expose()`. The choice depends on the sensitivity of your configuration values and your access requirements.

#### Use cy.env() when:

- The values are **sensitive** (API keys, passwords, tokens, credentials, secrets)
- You're using the value inside tests/hooks where async Cypress commands are fine
- You want the most conservative exposure model (only request what you need)

#### Use Cypress.expose() when:

- The value is **public/non-sensitive** (feature flags, API versions, public URLs, plugin configurations)
- You need **synchronous access**
- It's acceptable for the value to be accessible in the browser context (e.g. application code, third-party scripts, or extensions)

### Migrate sensitive values to cy.env()

`cy.env()` is read-only and asynchronous.

#### Read one value

```javascript
describe('API tests', () => {
  it('makes a request to the API', () => {
    const apiKey = Cypress.env('apiKey')
    cy.request({
      url: 'https://api.example.com/users',
      headers: { Authorization: `Bearer ${apiKey}` },
    })
      .its('status')
      .should('eq', 200)
  })
})
```

```javascript
describe('API tests', () => {
  it('makes a request to the API', () => {
    cy.env(['apiKey']).then(({ apiKey }) => {
      cy.request({
        url: 'https://api.example.com/users',
        headers: { Authorization: `Bearer ${apiKey}` },
      })
        .its('status')
        .should('eq', 200)
    })
  })
})
```

#### Read multiple values

```javascript
describe('API tests', () => {
  it('makes authenticated requests', () => {
    const apiUrl = Cypress.env('apiUrl')
    const apiKey = Cypress.env('apiKey')

    cy.request({
      url: `${apiUrl}/users`,
      headers: { Authorization: `Bearer ${apiKey}` },
    })
      .its('status')
      .should('eq', 200)
  })
})
```

```javascript
describe('API tests', () => {
  it('makes authenticated requests', () => {
    cy.env(['apiUrl', 'apiKey']).then(({ apiUrl, apiKey }) => {
      cy.request({
        url: `${apiUrl}/users`,
        headers: { Authorization: `Bearer ${apiKey}` },
      })
        .its('status')
        .should('eq', 200)
    })
  })
})
```

See [cy.env()](/llm/markdown/api/commands/env.md) for more details.

### Migrate public config to Cypress.expose()

Use this path only for non-sensitive values. `Cypress.expose()` is synchronous and is designed for configuration that is safe to be available in the browser.

#### Via configuration file

```javascript
const pluginConfig = Cypress.env('PLUGIN_CONFIG')
```

```ts
{
  env: {
    apiKey: 'secret-key-12345',
    featureFlag: true,
    apiVersion: 'v2',
    publicApiUrl: 'https://api.example.com',
    pluginConfig: 'development',
  },
}
```

```javascript
const pluginConfig = Cypress.expose('PLUGIN_CONFIG')
```

```ts
{
  expose: {
    featureFlag: true,
    apiVersion: 'v2',
    publicApiUrl: 'https://api.example.com',
    pluginConfig: 'development',
  },
  env: {
    apiKey: 'secret-key-12345',  // Sensitive - use env, not expose
  },
}
```

See [Cypress.expose()](/llm/markdown/api/cypress-api/expose.md) for more details.

#### Via CLI flags

Use the `--expose` or `-x` CLI flags when running Cypress.

```shell
cypress run --env FEATURE_FLAG=true,API_VERSION=v2,PUBLIC_API_URL=https://api.example.com
```

```shell
cypress run --expose FEATURE_FLAG=true,API_VERSION=v2,PUBLIC_API_URL=https://api.example.com
```

See [Cypress.expose()](/llm/markdown/api/cypress-api/expose.md) for more details.

#### Via runtime

You can set exposed values at runtime using `Cypress.expose(key, value)` or `Cypress.expose(object)`. Note that these changes only persist for the remainder of the current spec file:

```javascript
// Set a single value
Cypress.expose('featureFlag', true)

// Set multiple values
Cypress.expose({
  featureFlag: true,
  apiVersion: 'v2',
})
```

See [Cypress.expose()](/llm/markdown/api/cypress-api/expose.md) for more details.

### If you were setting values with Cypress.env()

`cy.env()` cannot set values. If you used `Cypress.env()` to write sensitive values at runtime, you can use `cy.task()` to store state in the Cypress config process. These are **not** environment variables and are **not** accessible through `cy.env()`.

**Setup in `cypress.config.js`:**

```javascript
// cypress.config.js
export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      const configProcessScopedVariables = {}

      on('task', {
        set: (keySet) => {
          Object.entries(keySet).forEach(([key, value]) => {
            configProcessScopedVariables[key] = value
          })
          return null
        },
        get: (keys) => {
          const variablesToReturn = {}
          keys.forEach((key) => {
            variablesToReturn[key] = configProcessScopedVariables[key]
          })
          return variablesToReturn
        },
      })

      return config
    },
  },
})
```

**Usage in your tests:**

```javascript
// spec.cy.js
describe('API tests', () => {
  it('stores and retrieves sensitive runtime values', () => {
    // Get an access token from an API
    cy.getAccessTokenFromApi().then(({ token }) => {
      // Store it securely in the config process
      cy.task('set', { accessToken: token })
    })

    // Later in the test, retrieve it
    cy.task('get', ['accessToken']).then(({ accessToken }) => {
      // Use the token securely
      cy.request({
        url: 'https://api.example.com/data',
        headers: { Authorization: `Bearer ${accessToken}` },
      })
    })
  })
})
```

### Migrate plugins that use Cypress.env()

If you're using Cypress plugins that reference `Cypress.env()`, you should check for updated versions that support the new API. When `allowCypressEnv: false` is set, plugins that still use `Cypress.env()` will throw errors.

#### Check for plugin updates

Before setting `allowCypressEnv: false`, review your installed plugins and update them to their latest versions. Many popular plugins need to be updated to use `Cypress.expose()` or `cy.env()` instead of `Cypress.env()`.

#### Plugins requiring migration

The following plugins require updates to their latest major versions and migration to the new API:

##### @cypress/code-coverage

Update to version 4.0.0+ of `@cypress/code-coverage` and follow its [migration guide](https://github.com/cypress-io/code-coverage/blob/master/README.md#migrations) to move from environment variables to `--expose` CLI flags and `expose` config.

##### @cypress/grep

Update to version 6.0.0+ of `@cypress/grep` and follow its [migration guide](https://github.com/cypress-io/cypress/tree/develop/npm/grep#migration) to move from environment variables to `--expose` CLI flags and `expose` config.

### Lock it down with allowCypressEnv: false

Once you've migrated all `Cypress.env()` invocations to either `cy.env()` or `Cypress.expose()`, you should set `allowCypressEnv: false` in your Cypress configuration.

```ts
{
  allowCypressEnv: false,
  env: {
    apiUrl: 'https://api.example.com',
    apiKey: 'secret-key-12345',
  },
  e2e: {
    baseUrl: 'http://localhost:3000',
  },
}
```

When `allowCypressEnv` is set to `false`:

1. `Cypress.env()` calls will throw an error
2. Test configuration overrides are disabled

#### Migration Checklist

1. ✅ Search your codebase for all `Cypress.env()` calls
2. ✅ Replace each `Cypress.env()` call with either `cy.env()` or `Cypress.expose()`
3. ✅ Update code to handle the asynchronous nature of `cy.env()`
4. ✅ Migrate plugins that use `Cypress.env()`
5. ✅ Set `allowCypressEnv: false` in your Cypress configuration
6. ✅ Verify that no errors are thrown

## Migrating to Cypress 15.0

This guide details the code changes needed to migrate to Cypress
version 15.
[See the full changelog for version v15.0](/llm/markdown/app/references/changelog.md#15-0-0).

### Node.js 20, 22 and 24+ support

Cypress requires [Node.js](https://nodejs.org/en) in order to install the Cypress binary and the supported versions are now Node.js 20, 22, 24 and above.
Node.js versions 18 and 23 are no longer supported.
[See Node's release schedule](https://github.com/nodejs/Release).

### cy.exec code property renamed

The `code` property on [`cy.exec()`](/llm/markdown/api/commands/exec.md) has been renamed to `exitCode`.

```javascript
cy.exec('rake db:seed').its('code').should('eq', 0)
```

```javascript
cy.exec('rake db:seed').its('exitCode').should('eq', 0)
```

### Unsupported Linux Distributions

Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.31`.
This support is in line with Node.js's support for Linux in 20+.

If you're using a Linux distribution based on glibc `<2.31`, you'll need to
update your system to a newer version to install Cypress 15+.
To display which version of glibc your Linux system is running, execute `ldd --version`.

### Webpack 4 is no longer supported

Cypress is no longer supporting Webpack `4` as it is no longer maintained by the core Webpack team and Webpack `5` has been available since Q4 2020. This includes dropping Webpack `4` support for:

- `@cypress/webpack-dev-server` for component testing. This use case is most common and will require an update to Webpack `5`.
  - `@cypress/webpack-dev-server` also no longer supports [Webpack Dev Server v4](https://github.com/webpack/webpack-dev-server/tree/v4.15.2). We shipped [Webpack Dev Server v5](https://github.com/webpack/webpack-dev-server/tree/v5.2.1) as the default in Cypress 14 with `webpack-dev-server@4` being an option.
- `@cypress/webpack-preprocessor` for end-to-end testing. Cypress, by default, uses the [Webpack Batteries Included Preprocessor](https://github.com/cypress-io/cypress/blob/@cypress/webpack-batteries-included-preprocessor-v3.0.7/npm/webpack-batteries-included-preprocessor/README.md) to process your files for end-to-end testing, which has used Webpack 5 since Cypress 13. Unless you are already using `@cypress/webpack-preprocessor` as a standalone package, this change likely does not apply.

#### To continue using Webpack 4

##### Component Testing

If you haven't been able to migrate away from Webpack `4` or Webpack Dev Server `4` and still need to be able to run your component tests with Webpack `4` or Webpack Dev Server `4`, you can install the following packages independently:

```sh
npm install --save-dev @cypress/webpack-dev-server@4
```

and configure the dev server within your `cypress.config.js` or `cypress.config.ts` file:

```js
import { devServer } from '@cypress/webpack-dev-server'
import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer(devServerConfig) {
      return devServer({
        ...devServerConfig,
        framework: 'react',
        webpackConfig: require('./webpack.config.js'),
      })
    },
  },
})
```

Note that this package version is deprecated and no longer supported by Cypress and is intended as a workaround until you can migrate to Webpack `5`. More information on how to configure the dev server `v4 `can be found in the [Cypress Webpack Dev Server documentation](https://github.com/cypress-io/cypress/blob/@cypress/webpack-dev-server-v4.0.2/npm/webpack-dev-server/README.md) and [Custom Dev Server documentation](/llm/markdown/app/component-testing/component-framework-configuration.md#Custom-Dev-Server).

##### End-to-End Testing

If you haven't been able to migrate away from Webpack `4`, need custom end-to-end spec file preprocessing, are already using `@cypress/webpack-preprocessor` as a standalone package, and still need to be able to run your end-to-end tests with Webpack `4`, you can install the following package independently:

```sh
npm install --save-dev @cypress/webpack-preprocessor@6
```

and configure the preprocessor within your `cypress.config.js` or `cypress.config.ts` file:

```js
import { defineConfig } from 'cypress'
import webpackPreprocessor from '@cypress/webpack-preprocessor'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      on('file:preprocessor', webpackPreprocessor())
    },
  },
})
```

As stated earlier, this is likely unnecessary unless you are already using `@cypress/webpack-preprocessor` as a standalone package. Cypress by default uses the [Webpack Batteries Included Preprocessor](https://github.com/cypress-io/cypress/blob/@cypress/webpack-batteries-included-preprocessor-v3.0.7/npm/webpack-batteries-included-preprocessor/README.md) to process your spec files for end-to-end testing.

Note that this package version is deprecated and no longer supported by Cypress and is intended as a workaround until you can migrate to Webpack `5`. More information on how to configure the preprocessor can be found in the [Preprocessors API documentation](/llm/markdown/api/node-events/preprocessors-api.md#Usage) and [Webpack Preprocessor documentation](https://github.com/cypress-io/cypress/blob/@cypress/webpack-preprocessor-v6.0.4/npm/webpack-preprocessor/README.md).

### @cypress/webpack-batteries-included-preprocessor no longer shims all built-ins provided by webpack v4

The default file preprocessor, `@cypress/webpack-batteries-included-preprocessor`, no longer shims all built-ins that were previously provided by webpack v4. This is mainly to reduce security vulnerabilities and bundle size within the end-to-end file preprocessor.

However, `@cypress/webpack-batteries-included-preprocessor` still ships with *some* built-ins, such as `buffer`, `path`, `process`, `os`, and `stream`. If other built-ins are required, install `@cypress/webpack-batteries-included-preprocessor` independently and follow the webpack documentation described in [webpack's resolve.fallback](https://webpack.js.org/configuration/resolve/#resolvefallback) to configure the built-ins you need.

For example, the following code shows how to provide the `querystring` built-in to the preprocessor:

```javascript
const webpackPreprocessor = require('@cypress/webpack-batteries-included-preprocessor')

function getWebpackOptions() {
  const options = webpackPreprocessor.getFullWebpackOptions()

  // add built-ins as needed
  // NOTE: for this example, querystring-es3 needs to be installed as a dependency
  options.resolve.fallback.querystring = require.resolve('querystring-es3')
  return options
}

module.exports = (on) => {
  on(
    'file:preprocessor',
    webpackPreprocessor({
      // if using typescript, you will need to set the typescript option to true
      typescript: true,
      webpackOptions: getWebpackOptions(),
    })
  )
}
```

### Angular 17 CT no longer supported

With [LTS end](https://angular.dev/reference/releases#actively-supported-versions) for Angular 17, the minimum required Angular version for component testing is now `18.0.0`.

#### To continue using Angular below 18.0.0

If you haven't been able to migrate away from an older Angular version and still need that test harness, it can be installed independently via the [`@cypress/angular`](https://www.npmjs.com/package/@cypress/angular) `3.x.x` package from `npm`.

Note that this test harness version is deprecated and no longer supported by Cypress. This version is intended to serve as a temporary workaround to migrate your project to Angular v18.0.0+.

```sh
npm install --save-dev @cypress/angular@3
```

Inside your support file (ex: `./cypress/support/component.(js|ts)`), or wherever your mount function is imported, make the following update to add `@`.

```ts
import { mount } from `cypress/angular`
```

```ts
import { mount } from `@cypress/angular`
```

### Selector Playground API changes

The `Cypress.SelectorPlayground` API has been renamed to
[`Cypress.ElementSelector`](/llm/markdown/api/cypress-api/element-selector-api.md). Additionally, the `onElement` function has been removed as an option to the `defaults` method.

This change was made in order to reflect its use in features beyond just the Selector Playground - like Cypress Studio.

The following code shows how to migrate from the `Cypress.SelectorPlayground` API to the
[`Cypress.ElementSelector`](/llm/markdown/api/cypress-api/element-selector-api.md) API.

```ts
Cypress.SelectorPlayground.defaults({
  selectorPriority: ['class', 'id'],
})
```

```ts
Cypress.ElementSelector.defaults({
  selectorPriority: ['class', 'id'],
})
```

## Migrating to Cypress 14.0

This guide details the code changes needed to migrate to Cypress
version 14.
[See the full changelog for version v14.0](/llm/markdown/app/references/changelog.md#14-0-0).

### Node.js 18+ support

Cypress comes bundled with its own
[Node.js version](https://github.com/cypress-io/cypress/blob/develop/.node-version).
However, installing the `cypress` npm package uses the Node.js version installed
on your system.

[See Node's release schedule](https://github.com/nodejs/Release). Node.js
version 16 and 21 will no longer be supported when installing Cypress. The minimum Node.js
version supported to install Cypress is Node.js 18+.

### Unsupported Linux Distributions

Prebuilt binaries for Linux are no longer compatible with Linux distributions based on glibc `<2.28`.
This support is in line with Node.js's support for Linux in 18+.

If you're using a Linux distribution based on glibc `<2.28`, for example, Ubuntu 14-18, RHEL 7, CentOS 7, Amazon Linux 2, you'll need to
update your system to a newer version to install Cypress 14+.

### Minimum macOS 11 (Big Sur)

[Cypress 14.0](/llm/markdown/app/references/changelog.md#14-0-0) upgrades Electron to `33.2.1`.
On macOS this requires a minimum version of macOS 11 (Big Sur).

If you're using a lower version of macOS make sure that you update.

### Updated Browser Support

Starting in Cypress 14, Cypress will officially support [the latest 3 major versions of Chrome, Firefox, and Edge](/llm/markdown/app/references/launching-browsers.md#Browser-versions-supported).

Older browser versions may still work with Cypress, but we recommend keeping your browsers up to date to ensure compatibility with Cypress.

### Changes to cy.origin()

To account for Chrome's [impending deprecation](https://developer.chrome.com/blog/document-domain-setter-deprecation) of setting `document.domain`, and to support sites that use [origin-keyed agent clusters](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin-Agent-Cluster),
Cypress no longer injects `document.domain` into `text/html` content by default.

Because of this, tests that visit more than one origin (defined as a composite of the URL *scheme*, *hostname*, and *port*) must now use `cy.origin()`.
Without `cy.origin()`, interacting with a second origin in the same test will cause the test to fail, even if the two origins
are in the same superdomain. This means you must now use `cy.origin()` in more situations than before.

/\* prettier-ignore-start \*/

 **Failing Test**

```js
cy.visit('https://www.cypress.io')
cy.visit('https://docs.cypress.io')
// Cypress will not be able to interact with the page, causing the test to fail
cy.get('[role="banner"]').should('be.visible')
```

 **Fixed Test**

```js
cy.visit('https://www.cypress.io')
cy.visit('https://docs.cypress.io')
cy.origin('https://docs.cypress.io', () => {
  cy.get('[role="banner"]').should('be.visible')
})
```

/\* prettier-ignore-end \*/

To ease this transition, Cypress v14.0 introduced the ["injectDocumentDomain" configuration option](/llm/markdown/app/references/configuration.md#injectDocumentDomain). When this option
is set to true, `cy.origin()` will not be required to navigate between origins, as long as the superdomain matches.

 If `injectDocumentDomain` is set to `true`,
Cypress will warn that this option is deprecated.

 `injectDocumentDomain` will be removed in a
future version of Cypress.

 Setting `injectDocumentDomain` to `true`
may cause certain sites to stop working in Cypress. Please read the
[configuration notes](/llm/markdown/app/references/configuration.md#injectDocumentDomain) before
use.

 If your test suites require
`experimentalWebKitSupport`, `injectDocumentDomain` must be set to `true`.

 Chrome may remove support for
`document.domain` at any time; if this configuration option is enabled, Cypress
may cease to work in Chrome at any time. If this occurs, Chrome will raise an
issue in its developer tools indicating that the deprecated `document.domain` is
in use. To resolve this issue, set the `injectDocumentDomain` option to `false`
and issue any newly necessary `cy.origin()` commands.

### Deprecation of resourceType on cy.intercept

The `resourceType` option on [`cy.intercept`](/llm/markdown/api/commands/intercept.md) has been deprecated in Cypress 14.0.0. We anticipate the types of the `resourceType` to change in the future or be completely removed
from the API.

Our intention is to replace essential functionality dependent on the `resourceType` within Cypress in a future version (like [hiding network logs that are not fetch/xhr](/llm/markdown/api/commands/intercept.md#Disabling-logs-for-a-request)). If you're using `resourceType` in your tests, please leave feedback on which `resourceType` values are important to you in this [GitHub issue](https://github.com/cypress-io/cypress/issues/30447).

### CT Just in Time Compile changes

In Cypress 13.14.0, we released an experimental flag, `experimentalJustInTimeCompile`,
to enable Just in Time (JIT) compilation for Component Testing with `vite` and `webpack`. The response from this change was positive and we've made a few changes in response:

- JIT compilation is the default behavior for component tests as a [`justInTimeCompile`](/llm/markdown/app/references/configuration.md#component) component configuration option.
- JIT compilation no longer applies with `vite`, since there is no benefit to enabling this with `vite`.

This option will only compile resources directly related to your spec, compiling them 'just-in-time' before spec execution. This should result in improved memory management and performance for component tests in `cypress open` and `cypress run` modes, especially for large test suites.

#### Disable JIT Compilation

If you would like to disable JIT compilation, you can do so by setting [`justInTimeCompile`](/llm/markdown/app/references/configuration.md#component) to `false` in your component configuration.

```js
{
  component: {
    justInTimeCompile: false
  }
}
```

For users with the existing `experimentalJustInTimeCompile` flag set, you can remove this flag from your configuration.

### React <18 CT no longer supported

With [LTS ending](https://github.com/reactjs/react.dev/issues/1745#issuecomment-466767389) for React 16 and 17 several years ago, the minimum required React version for component testing is now `18.0.0`.

Now that the minimum version of React supported for Component Testing is `18.0.0`, Cypress is able to merge the `cypress/react18` test harness into the main `cypress/react` test harness. Because of this, the `@cypress/react18` harness is deprecated and no longer shipped with the binary. Support has been moved to `cypress/react`.

To migrate, change the test harness from `cypress/react18` to `cypress/react`.

```ts
import { mount } from 'cypress/react18'
```

```ts
import { mount } from 'cypress/react'
```

#### To continue using React below v18

If you haven't been able to migrate away from an older React version and still need that test harness, it can be installed independently via the [`@cypress/react`](https://www.npmjs.com/package/@cypress/react) `8.x.x` package from `npm`.

Note that this test harness version is deprecated and no longer supported by Cypress. This version is intended to serve as a temporary workaround to migrate your project to React v18+.

```sh
npm install --save-dev @cypress/react@8
```

Inside your support file (ex: `./cypress/support/component.(js|ts)`), or wherever your mount function is imported, make the following update to add `@`.

```ts
import { mount } from 'cypress/react'
```

```ts
import { mount } from '@cypress/react'
```

### Angular <17.2.0 CT no longer supported

With [LTS ending](https://angular.dev/reference/releases#actively-supported-versions) for Angular 16, the minimum required Angular version for component testing is now `17.2.0` in order to support [signals](/llm/markdown/app/component-testing/angular/examples.md#Signals) as a first class citizen.

Now that the minimum version of Angular supported for Component Testing is `17.2.0`, Cypress is able to merge the `cypress/angular-signals` test harness into the main `cypress/angular` test harness. Because of this, the `@cypress/angular-signals` harness is deprecated and no longer shipped with the binary. Support has been moved to `cypress/angular`.

To migrate, just change the test harness from `cypress/angular-signals` to `cypress/angular`.

```ts
import { mount } from 'cypress/angular-signals'
```

```ts
import { mount } from 'cypress/angular'
```

#### To continue using Angular below v17.2.0

If you haven't been able to migrate away from an older Angular version and still need that test harness, it can be installed independently via the [`@cypress/angular`](https://www.npmjs.com/package/@cypress/angular) `2.x.x` package from `npm`.

Note that this test harness version is deprecated and no longer supported by Cypress. This version is intended to serve as a temporary workaround to migrate your project to Angular v17.2.0+.

```sh
npm install --save-dev @cypress/angular@2
```

Inside your support file (ex: `./cypress/support/component.(js|ts)`), or wherever your mount function is imported, make the following update to add `@`.

```ts
import { mount } from 'cypress/angular'
```

```ts
import { mount } from '@cypress/angular'
```

### Vue 2 CT no longer supported

[Vue 2 reached end-of-life on December 31st, 2023](https://v2.vuejs.org/eol/). With Cypress 14, Cypress no longer ships the Vue 2 component testing harness with the Cypress binary.

#### To continue using Vue 2

If you haven't been able to migrate away from Vue 2 and still need that test harness, it can be installed independently via the [@cypress/vue2](https://www.npmjs.com/package/@cypress/vue2) package.

Note that this test harness is deprecated and no longer supported by Cypress. This package is intended to serve as a temporary workaround to migrate your project to Vue 3. The Cypress launchpad will warn against Component testing mismatched dependencies, but this will not stop you from running your component tests.

```sh
npm install --save-dev @cypress/vue2
```

Inside your support file (ex: `./cypress/support/component.(js|ts)`), or wherever your mount function is imported, make the following update to add `@`.

```ts
import { mount } from 'cypress/vue2'
```

```ts
import { mount } from '@cypress/vue2'
```

### Create React App CT no longer supported

[create-react-app](https://create-react-app.dev/) is no longer actively maintained or supported (see [CRA issue #13393](https://github.com/facebook/create-react-app/issues/13393)). Your component tests will now need a bundler to run. If still using [create-react-app](https://create-react-app.dev/), you'll either need to:

- [Eject](https://create-react-app.dev/docs/available-scripts/#npm-run-eject) the configuration to bundle with webpack.
- Leverage [vite](https://vite.dev/guide/) to bundle your component tests (quick setup with [create-vite](https://github.com/vitejs/vite/tree/main/packages/create-vite)).

After selecting a bundler, change the `framework` option in your Cypress config from `create-react-app` to `react`. If ejecting the `create-react-app`, change your cypress config to look something like this:

```js
process.env.NODE_ENV = 'development'
const { defineConfig } = require('cypress')
const webpackConfig = require('./config/webpack.config.js')

module.exports = defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'webpack',
      webpackConfig: webpackConfig('development'),
    },
  },
})
```

### @vue/cli-service CT no longer supported

`@vue/cli-service` is in [maintenance mode](https://cli.vuejs.org/guide/cli-service.html) and is no longer maintained by the Vue core team. Your component tests will now need a bundler to run. If still using [Vue CLI](https://cli.vuejs.org/), you will either need to:

- Migrate to webpack ([see example](https://github.com/cypress-io/cypress-component-testing-apps/tree/main/vue3-webpack-ts)).
- Leverage [vite](https://vite.dev/guide/). The Vue team recommends migrating to using `create-vue` to scaffold a [Vite](https://vite.dev/)-based project.

After selecting a bundler, change the `framework` option in your Cypress config from `"vue-cli"` to `"vue"`. Your Cypress configuration should change as outlined below.

```
{
  component: {
    devServer: {
      framework: 'vue-cli',
      bundler: 'webpack',
    },
  }
}
```

```
{
  component: {
    devServer: {
      framework: 'vue',
      bundler: 'vite', // or 'webpack'
    },
  }
}
```

### Svelte 3 & 4 CT no longer supported

With Cypress 14, Cypress no longer ships the Svelte 3 and 4 component testing harness with the Cypress binary.

However, if you have not been able to upgrade Svelte and still need the Cypress Svelte 3 and 4 test harness, it can be installed independently via version 2.x.x of the [@cypress/svelte](https://www.npmjs.com/package/@cypress/svelte) package.

```sh
npm install --save-dev @cypress/svelte@2
```

Note that this version of the test harness is deprecated and no longer actively supported by Cypress and is intended to serve as a temporary work around until you are able to migrate your project to Svelte 5+. The Cypress launchpad will also warn against Component testing mismatched dependencies, but this will not stop you from running your component tests.

To update, inside your support file (ex: `./cypress/support/component.(js|ts)`) or wherever your mount function is imported, change

```ts
import { mount } from 'cypress/svelte'
```

to

```ts
import { mount } from '@cypress/svelte'
```

Your code should now look like this:

```ts
import MySvelteComponent from './MySvelteComponent'
import { mount } from '@cypress/svelte'

it('renders', () => {
  cy.mount(MySvelteComponent)
})
```

## Migrating to Cypress 13.0

This guide details the changes and how to change your code to migrate to Cypress
version 13.
[See the full changelog for version v13.0](/llm/markdown/app/references/changelog.md#13-0-0).

### Cypress Cloud Test Replay

[Test Replay](/llm/markdown/cloud/features/test-replay.md) is enabled by default in `v13` of the Cypress App.

You may need to allowlist `capture.cypress.io` if you work with a strict VPN. See our FAQ section about [VPN subdomain allowlisting](/llm/markdown/cloud/faq.md#Im-working-with-a-restrictive-VPN-Which-subdomains-do-I-have-to-allow-on-my-VPN-for-Cypress-Cloud-to-work-properly).

With Test Replay enabled, the Cypress Runner UI is hidden by default when recording a run to the Cloud. If the Runner UI is needed during the run, you can enable it by passing [`--runner-ui`](/llm/markdown/app/references/command-line.md#cypress-run-runner-ui) to the [`cypress run`](/llm/markdown/app/references/command-line.md#cypress-run) command.

You can [opt-out](/llm/markdown/cloud/features/test-replay.md#Opt-out-of-Test-Replay) of this feature in Cloud project-level settings.

### Video updates

#### video is set to false by default

You can continue recording video by setting `video` to `true` either in your Cypress configuration or via [overriding options](/llm/markdown/app/references/configuration.md#Overriding-Options). This can be useful if you want video locally or want video for some other reason, like in non-Chromium browsers where [Test Replay](/llm/markdown/cloud/features/test-replay.md) is not available.

```ts
{
  video: true
}
```

#### videoUploadOnPasses configuration option has been removed

Most users used `videoUploadOnPasses` as a way to skip the time to compress and upload videos to the Cloud. Since we're turning off `videoCompression` by default, this configuration option does not offer the time saving value that it once would.

If you want to prevent a passing test from uploading to the Cloud, we recommend deleting the video using our [guide with code examples to discard captured video of passing tests](/llm/markdown/app/guides/screenshots-and-videos.md#Control-which-videos-to-keep-and-upload-to-Cypress-Cloud).

#### videoCompression is set to false by default

Cypress has the capability to compress recorded videos after a run to reduce the video file size. By default, compression is now turned off. This results in a reduced run time by removing the time to compress the video, a larger video file size and better video quality.

You can enable this with the `videoCompression` [configuration](/llm/markdown/app/references/configuration.md#Videos) option if you'd like to reduce the video file size for any reason. This will also reduce the video quality and take slightly longer to process and complete the run.

```ts
{
  // value can be true/false -or- an integer between 0 and 51
  videoCompression: true,
}
```

### cy.readFile() is now a query command

In Cypress `v13`, the [`.readFile()`](/llm/markdown/api/commands/readfile.md) command is now a query.
Tests written using it should continue to operate exactly as before; no changes
are necessary.

`readFile()` will re-read the file from disk if any upcoming command in the same
chain fails. Assertions no longer have to be directly attached.

```js
cy.readFile(`users.json`).its('users.123.fullName').should('eq', 'John Doe')
```

Beginning with Cypress `v13`, the above test will re-read the file until the file
exists, it has the requested property, and it passes the assertion.

In previous versions of Cypress, the above command would retry until the file
existed, but would *not* re-read it from disk if the file didn't have the
requested property or the contents didn't match.

#### .readFile() can no longer be overwritten with Cypress.Commands.overwrite()

Queries must be overwritten using `Cypress.Commands.overwriteQuery()`. If you
were previously overwriting `cy.readFile()`, you will need to update your code
to use `Cypress.Commands.overwriteQuery('readFile', function() { ... })` rather
than `Cypress.Commands.overwrite('readFile', () => { ... })`. For more details
on overwriting queries, see the
[Overwriting Existing Queries](/llm/markdown/api/cypress-api/custom-queries.md#Overwriting-Existing-Queries).

## Migrating to Cypress 12.0

This guide details the changes and how to change your code to migrate to Cypress
version 12.0.
[See the full changelog for version 12.0](/llm/markdown/app/references/changelog.md#12-0-0).

The Session and Origin experiment has been released as General Availability
(GA), meaning that we have deemed this experiment to be feature complete and
free of issues in the majority of use cases. With releasing this as GA, the
`experimentalSessionAndOrigin` flag has been removed, the
[`cy.origin()`](/llm/markdown/api/commands/origin.md) and
[`cy.session()`](/llm/markdown/api/commands/session.md) commands are generally available and
[Test Isolation](/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Test-Isolation)
is enabled by default.

### Node.js 14+ support

Cypress comes bundled with its own
[Node.js version](https://github.com/cypress-io/cypress/blob/develop/.node-version).
However, installing the `cypress` npm package uses the Node.js version installed
on your system.

Node.js 12 reached its end of life on April 30, 2022.
[See Node's release schedule](https://github.com/nodejs/Release). This Node.js
version will no longer be supported when installing Cypress. The minimum Node.js
version supported to install Cypress is Node.js 14+.

### Test Isolation

The
[`testIsolation`](/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Test-Isolation)
config option is enabled by default. This means Cypress resets the browser
context *before* each test by:

- clearing the dom state by visiting `about:blank`
- clearing [cookies](/llm/markdown/api/cypress-api/cookies.md) in all domains
- clearing
  [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)
  in all domains
- clearing
  [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
  in all domains

Test suites that relied on the application to persist between tests may have to
be updated to revisit their application and rebuild the browser state for each
test that needs it.

Before this change, it was possible to write tests such that you could rely on
the application (i.e. DOM state) to persist between tests. For example you could
log in to a CMS in the first test, change some content in the second test,
verify the new version is displayed on a different URL in the third, and log out
in the fourth.

Here's a simplified example of such a test strategy.

&#x20;Multiple small tests against different
origins

```js
it('logs in', () => {
  cy.visit('https://example.cypress.io')
  cy.get('input#password').type('Password123!')
  cy.get('button#submit').click()
})

it('updates the content', () => {
  // already on page redirect from clicking button#submit
  cy.get('#current-user').contains('logged in')
  cy.get('button#edit-1').click()
  cy.get('input#title').type('Updated title')
  cy.get('button#submit').click()
  cy.get('.toast').contains('Changes saved!')
})

it('validates the change', () => {
  cy.visit('/items/1')
  cy.get('h1').contains('Updated title')
})
```

After migrating, when `testIsolation=true` by default, this flow would need to
be contained within a single test. While the above practice has always been
[discouraged](/llm/markdown/app/core-concepts/best-practices.md#Having-Tests-Rely-On-The-State-Of-Previous-Tests)
we know some users have historically written tests this way, often to get around
the `same-origin` restrictions. But with [`cy.origin()`](/llm/markdown/api/commands/origin.md)
you no longer need these kind of brittle hacks, as your multi-origin logic can
all reside in a single test, like the following.

&#x20;One big test using `cy.origin()`

```js
it('securely edits content', () => {
  cy.origin('cypress.io', () => {
    cy.visit('https://example.cypress.io')
    cy.get('input#password').type('Password123!')
    cy.get('button#submit').click()
  })

  cy.origin('cypress-dx.com', () => {
    cy.url().should('contain', 'cms')
    cy.get('#current-user').contains('logged in')
    cy.get('button#edit-1').click()
    cy.get('input#title').type('Updated title')
    cy.get('button#submit').click()
    cy.get('.toast').contains('Changes saved!')
  })

  cy.visit('/items/1')
  cy.get('h1').contains('Updated title')
})
```

The just-released `cy.session()` command can be used to setup and cache cookies,
local storage and session storage between tests to easily re-establish the
previous (or common) browser contexts needed in a suite. This command will run
setup on its initial execution and will restore the saved browser state on each
sequential command execution. This command reduces the need for repeated
application logins, while users also benefit from the test isolation guardrails
to write independent, reliable and deterministic tests from the start.

If for whatever reason you still need to persist the dom and browser context
between tests, you can disable test isolation by setting `testIsolation=false`
on the root configuration or at the suite-level. For example:

```js
describe('workflow', { testIsolation: false }, () => {
  ...
})
```

It is important to note that while disabling test isolation may improve the
overall performance of end-to-end tests, it can cause state to "leak" between
tests. This can make later tests dependent on the results of earlier tests, and
potentially cause misleading test failures. It is important to be extremely
mindful of how tests are written when using this mode, and ensure that tests
continue to run independently of one another.

&#x20;the following tests are not independent
nor deterministic:

```js
describe('workflow', { testIsolation: false }, () => {
  it('logs in', () => {
    cy.visit('https://example.cypress.io/log-in')
    cy.get('username').type('User1')
    cy.task('getSecret', 'USER1_PASSWORD').then((password) => {
      cy.get('password').type(password)
    })
    cy.get('button#login').click()
    cy.contains('User1')
  })

  it('clicks user profile', () => {
    cy.get('User1').find('#profile_avatar').click()
    cy.contains('Email Preferences')
  })

  it('updates profile', () => {
    cy.get('button#edit')
    cy.get('email').type('user1@email.com')
    cy.get('button#save').click()
  })
})
```

In the above example, each test is relying on the previous test to be
*successful* to correctly execute. If at any point, the first or second test
fails, the sequential test(s) will automatically fail and provide unreliable
debugging errors since the errors are representative of the previous test.

The best way to ensure your tests are independent is to add a `.only()` to your
test and verify it can run successfully without the test before it.

#### Simulating Pre-Test Isolation Behavior

Test isolation did not truly exist pre-12. Pre-Cypress 12, the behavior was a
hybrid of both `testIsolation` enabled and disabled. All local storage and
cookies on the current domain were cleared, but Cypress did not clear session
storage and the page always persisted.

In Cypress 12+ when `testIsolation` is enabled, local storage, session storage
and cookies in **all** domains are cleared and the page is cleared. When
`testIsolation` is disabled, nothing is cleared before the next test so all
local storage, session storage and cookies & the page persists.

If you wanted to match pre-Cypress 12 behavior, you need to disable
`testIsolation`, then run `cy.clearLocalStorage()` and `cy.clearCookies()` in a
beforeEach hook to clear the local storage and cookies in the current domain.

```js
describe('match pre-12 behavior', { testIsolation: false }, () => {
  beforeEach(() => {
    cy.clearLocalStorage()
    cy.clearCookies()
    // other beforeEach logic to restore the expected local storage or cookies needed on the client.
  })
})
```

Many of the issues test isolation solved were around cookie management with
tests trying to save and persist cookies because the page was still available,
but the cookies on the domain were unexpectedly cleared which broke interactions
with the application. It wasn’t obvious Cypress was doing a partial browser
clean up. Explicitly setting test isolation to enabled or disabled allows you to
choose what is right for your tests.

### Behavior Changes in Alias Resolution

Cypress always re-queries aliases when they are referenced. This can result in
certain tests that used to pass could start to fail. For example,

```js
cy.findByTestId('popover')
  .findByRole('button', { expanded: true })
  .as('button')
  .click()

cy.get('@button').should('have.attr', 'aria-expanded', 'false')
```

previously passed, because the initial button was collapsed when first queried,
and then later expanded. However, in Cypress 12, this test fails because the
alias is always re-queried from the DOM, effectively resulting in the following
execution:

```js
cy.findByTestId('popover').findByRole('button', { expanded: true }).click()

cy.findByTestId('popover')
  .findByRole('button', { expanded: true }) // A button which matches here (is expanded)...
  .should('have.attr', 'aria-expanded', 'false') // ...will never pass this assertion.
```

You can rewrite tests like this to be more specific; in our case, we changed the
alias to be the first button rather than the unexpanded button.

```js
cy.findByTestId('popover').findAllByRole('button').first().as('button')
```

If you want to alias a static value, such that it is never re-queried, you will
need Cypress [12.3.0](/llm/markdown/app/references/changelog.md#12-3-0) or later, which
introduced the `type` option for [`.as()`](/llm/markdown/api/commands/as.md) to opt into the old
behavior.

```
cy.get('.username').invoke('val').as('username', { type: 'static' })
```

See [`.as()`](/llm/markdown/api/commands/as.md) for more details.

### Command / Cypress API Changes

#### Cypress.Cookies.defaults and Cypress.Cookies.preserveOnce

The `Cypress.Cookies.defaults` and `Cypress.Cookies.preserveOnce` APIs been
removed. Use the [`cy.session()`](/llm/markdown/api/commands/session.md) command to preserve
cookies (and local and session storage) between tests.

If you were using `Cypress.Cookies.preserveOnce` to preserve a specific cookie
within a single spec, this might look like the following:

```diff
describe('Dashboard', () => {
  beforeEach(() => {
-    cy.login()
-    Cypress.Cookies.preserveOnce('session_id', 'remember_token')
+    cy.session('unique_identifier', cy.login, {
+       validate () {
+        cy.getCookies().should('have.length', 2)
+       },
+    })
  })
```

If you were using `Cypress.Cookies.defaults` to preserve a cookie or set of
cookies across test, this might look like the following:

```diff
describe('Dashboard', () => {
  beforeEach(() => {
-    cy.login()
-    Cypress.Cookies.defaults({
-       preserve: ['session_id', 'remember_token']
-    })
+    cy.session('unique_identifier', cy.login, {
+       validate () {
+        cy.getCookies().should('have.length', 2)
+       },
+       cacheAcrossSpecs: true
+    })
  })
```

#### cy.server(), cy.route() and Cypress.Server.defaults

The` cy.server()` and` cy.route()` commands and the `Cypress.server.defaults`
API has been removed. Use the [`cy.intercept()`](/llm/markdown/api/commands/intercept.md)
command instead.

```diff
  it('can encode + decode headers', () => {
-   Cypress.Server.defaults({
-     delay: 500,
-     method: 'GET',
-   })
-   cy.server()
-   cy.route(/api/, () => {
-      return {
-        'test': 'We’ll',
-      }
-    }).as('getApi')
+   cy.intercept('GET', /api/, (req) => {
+      req.on('response', (res) => {
+        res.setDelay(500)
+      })
+      req.body.'test': 'We’ll'
+    }).as('getApi')
    cy.visit('/index.html')
    cy.window().then((win) => {
      const xhr = new win.XMLHttpRequest
      xhr.open('GET', '/api/v1/foo/bar?a=42')
      xhr.send()
    })

    cy.wait('@getApi')
-   .its('url').should('include', 'api/v1')
+   .its('request.url').should('include', 'api/v1')
  })
```

#### .invoke()

The [`.invoke()`](/llm/markdown/api/commands/invoke.md) command now throws an error if the
function returns a promise. If you wish to call a method that returns a promise
and wait for it to resolve, use [`.then()`](/llm/markdown/api/commands/then.md) instead of
`.invoke()`.

```diff
cy.wrap(myAPI)
-  .invoke('makeARequest', 'http://example.com')
+  .then(api => api.makeARequest('http://example.com'))
   .then(res => { ...handle response... })
```

If `.invoke()` is followed by additional commands or assertions, it will call
the named function multiple times. This has the benefit that the chained
assertions can more reliably use the function's return value.

If this behavior is undesirable because you expect the function to be invoked
only once, break the command chain and move the chained commands and/or
assertions to their own chain. For example, rewrite

```diff
- cy.get('input').invoke('val', 'text').type('newText')
+ cy.get('input').invoke('val', 'text')
+ cy.get('input').type('newText')
```

#### .should()

The [`.should()`](/llm/markdown/api/commands/should.md) assertion now throws an error if Cypress
commands are invoked from inside a `.should()` callback. This previously
resulted in unusual and undefined behavior. If you wish to execute a series of
commands on the yielded value, use`.then()` instead.

```diff
cy.get('button')
-  .should(($button) => {

    })
+  .then(api => api.makeARequest('http://example.com'))
   .then(res => { ...handle response... })
```

#### .within()

The [`.within()`](/llm/markdown/api/commands/within.md) command now throws an error if it is
passed multiple elements as the subject. This previously resulted in
inconsistent behavior, where some commands would use all passed in elements,
some would use only the first and ignore the rest, and
[`.screenshot()`](/llm/markdown/api/commands/screenshot.md) would throw an error if used inside
a `.within()` block with multiple elements.

If you were relying on the old behavior, you have several options depending on
the desired result.

The simplest option is to reduce the subject to a single element.

```diff
cy.get('tr')
+  .first() // Limit the subject to a single element before calling .within()
  .within(() => {
    cy.contains('Edit').click()
  })
```

If you have multiple subjects and wish to run commands over the collection as a
whole, you can alias the subject rather than use `.within()`.

```diff
cy.get('tr')
-  .within(() => {
-    cy.get('td').should('have.class', 'foo')
-    cy.get('td').should('have.class', 'bar')
-  })
+  .as('rows') // Store multiple elements as an alias

+cy.get('@rows').find('td').should('have.class', 'foo')
+cy.get('@rows').find('td').should('have.class', 'bar')
```

Or if you have a collection and want to run commands over every element, use
`.each()` in conjunction with `.within()`.

```diff
cy.get('tr')
-  .within(() => {
-    cy.contains('Edit').should('have.attr', 'disabled')
-  })
+  .each($tr => {
+    cy.wrap($tr).within(() => {
+      cy.contains('Edit').should('have.attr', 'disabled')
+    })
+  })
```

#### Cypress.Commands.overwrite()

In Cypress 12.0.0, we introduced a new command type, called queries. A query is
a small and fast command for getting data from the window or DOM. This
distinction is important because Cypress can retry chains of queries, keeping
the yielded subject up-to-date as a page rerenders.

With the introduction of query commands, the following commands have been
re-categorized and can no longer be overwritten with
[`Cypress.Commands.overwrite()`](/llm/markdown/api/cypress-api/custom-commands.md#Overwrite-Existing-Commands):

- [`.as()`](/llm/markdown/api/commands/as.md)
- [`.children()`](/llm/markdown/api/commands/children.md)
- [`.closest()`](/llm/markdown/api/commands/closest.md)
- [`.contains()`](/llm/markdown/api/commands/contains.md)
- [`cy.debug()`](/llm/markdown/api/commands/debug.md)
- [`cy.document()`](/llm/markdown/api/commands/document.md)
- [`.eq()`](/llm/markdown/api/commands/eq.md)
- [`.filter()`](/llm/markdown/api/commands/filter.md)
- [`.find()`](/llm/markdown/api/commands/find.md)
- [`.first()`](/llm/markdown/api/commands/first.md)
- [`.focused()`](/llm/markdown/api/commands/focused.md)
- [`.get()`](/llm/markdown/api/commands/get.md)
- [`.hash()`](/llm/markdown/api/commands/hash.md)
- [`.its()`](/llm/markdown/api/commands/its.md)
- [`.last()`](/llm/markdown/api/commands/last.md)
- [`cy.location()`](/llm/markdown/api/commands/location.md)
- [`.next()`](/llm/markdown/api/commands/next.md)
- [`.nextAll()`](/llm/markdown/api/commands/nextall.md)
- [`.not()`](/llm/markdown/api/commands/not.md)
- [`.parent()`](/llm/markdown/api/commands/parent.md)
- [`.parents()`](/llm/markdown/api/commands/parents.md)
- [`.parentsUntil()`](/llm/markdown/api/commands/parentsuntil.md)
- [`.prev()`](/llm/markdown/api/commands/prev.md)
- [`.prevUntil()`](/llm/markdown/api/commands/prevuntil.md)
- [`cy.root()`](/llm/markdown/api/commands/root.md)
- [`.shadow()`](/llm/markdown/api/commands/shadow.md)
- [`.siblings()`](/llm/markdown/api/commands/siblings.md)
- [`cy.title()`](/llm/markdown/api/commands/title.md)
- [`cy.url()`](/llm/markdown/api/commands/url.md)
- [`cy.window()`](/llm/markdown/api/commands/window.md)

If you were previously overwriting one of the above commands, try adding your
version as a new command using
[`Cypress.Commands.add()`](/llm/markdown/api/cypress-api/custom-commands.md) under a different
name.

## Migrating to Cypress 11.0

This guide details the changes and how to change your code to migrate to Cypress
version 11.0.
[See the full changelog for version 11.0](/llm/markdown/app/references/changelog.md#11-0-0).

### Component Testing Updates

As of Cypress 11, Component Testing is now generally available. There are some
minor breaking changes. Most projects should be able to migrate without any code
modifications.

#### Changes to Mounting Options

Each major library we support has a `mount` function with two arguments:

1. The component
2. Mounting Options

Mounting options previously had several properties that are now removed:

- cssFile, cssFiles
- style, styles
- stylesheet, stylesheets

Read more about the rationale
[here](https://www.cypress.io/blog/2022/11/04/upcoming-changes-to-component-testing/).
We recommend writing test-specific styles in a separate `css` file you import in
your test, or in your `supportFile`.

#### Before (Cypress 10)

```jsx
import { mount } from 'cypress/react'
import { Card } from './Card'

it('renders some content', () => {
  cy.mount(<Card title="title" />, {
    styles: `
      .card { width: 100px; }
    `,
    stylesheets: [
      'https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css',
    ],
  })
})
```

#### After (Cypress 11)

```js
/** style.css */
@import "https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css";
.card { width: 100px }

/** Card.cy.jsx */
import { mount } from 'cypress/react'
import { Card } from './Card'
import './styles.css' // contains CDN link and custom styling.

it('renders some content', () => {
  cy.mount(<Card title="title" />)
})
```

### React - mountHook Removed

`mountHook` from `cypress/react` has been removed. Read more about the rationale
[here](https://www.cypress.io/blog/2022/11/04/upcoming-changes-to-component-testing/).

We recommend simply replacing it with `mount` and a component.

Consider the following `useCounter` hook:

```js
import { useState, useCallback } from 'react'

function useCounter() {
  const [count, setCount] = useState(0)
  const increment = useCallback(() => setCount((x) => x + 1), [])

  return { count, increment }
}
```

#### Before - Cypress 10 and mountHook

```js
import { mountHook } from 'cypress/react'
import { useCounter } from './useCounter'

it('increments the count', () => {
  mountHook(() => useCounter()).then((result) => {
    expect(result.current.count).to.equal(0)
    result.current.increment()
    expect(result.current.count).to.equal(1)
    result.current.increment()
    expect(result.current.count).to.equal(2)
  })
})
```

#### After - Cypress 11 and mount

```js
import { useCounter } from './useCounter'

it('increments the count', () => {
  function Counter() {
    const { count, increment } = useCounter()
    return (
      <>
        <h1 name="count">Count is {{ count }}</h1>
        <button onClick={increment}>Increment</button>
      </>
    )
  }

  cy.mount(<Counter />).then(() => {
    cy.get('[name="count"]')
      .should('contain', 0)
      .get('button')
      .click()
      .get('[name="count"]')
      .should('contain', 1)
  })
})
```

### React - unmount Removed

`unmount` from `cypress/react` has been removed. Read more about the rationale
[here](https://www.cypress.io/blog/2022/11/04/upcoming-changes-to-component-testing/).
We recommend using the API React provides for unmounting components,
[unmountComponentAtNode](https://reactjs.org/docs/react-dom.html#unmountcomponentatnode).

#### Before - Cypress 10 and unmount

```js
import { unmount } from 'cypress/react'

it('calls the prop', () => {
  cy.mount(<Comp onUnmount={cy.stub().as('onUnmount')} />)
  cy.contains('My component')

  unmount()

  // the component is gone from the DOM
  cy.contains('My component').should('not.exist')
  cy.get('@onUnmount').should('have.been.calledOnce')
})
```

#### After - Cypress 11 and unmountComponentAtNode

```js
import { getContainerEl } from 'cypress/react'
import ReactDom from 'react-dom'

it('calls the prop', () => {
  cy.mount(<Comp onUnmount={cy.stub().as('onUnmount')} />)
  cy.contains('My component')

  cy.then(() => ReactDom.unmountComponentAtNode(getContainerEl()))

  // the component is gone from the DOM
  cy.contains('My component').should('not.exist')
  cy.get('@onUnmount').should('have.been.calledOnce')
})
```

### Vue - mountCallback Removed

`mountCallback` from `cypress/vue` has been removed. Read more about the
rationale
[here](https://www.cypress.io/blog/2022/11/04/upcoming-changes-to-component-testing/).
We recommend using `mount`.

#### Before - Cypress 10 and mountCallback

```js
import { mountCallback } from 'cypress/vue'

beforeEach(mountCallback(MessageList))

it('shows no messages', () => {
  getItems().should('not.exist')
})
```

#### After - Cypress 11 and mount

```js
beforeEach(() => cy.mount(MessageList))

it('shows no messages', () => {
  getItems().should('not.exist')
})
```

### Angular - Providers Mounting Options Change

There is one breaking change for Angular users in regards to providers. In
Cypress 10, we took any providers passed as part of the Mounting Options and
overrode the component providers via the `TestBed.overrideComponent` API.

In Cypress 11, providers passed as part of the Mounting Options will be assigned
at the module level using the `TestBed.configureTestingModule` API.

This means that module-level providers (resolved from imports or
`@Injectable({ providedIn: 'root' })` can be overridden, but providers specified
in `@Component({ providers: [...] })` will not be overridden when using
`cy.mount(MyComponent, { providers: [...] })`.

To override component-level providers, use the `TestBed.overrideComponent` API.

See a concrete example
[here](https://www.cypress.io/blog/2022/11/04/upcoming-changes-to-component-testing/#angularproviders-priority).

### Vite Dev Server (cypress/vite-dev-server)

When providing an inline `viteConfig` inside of `cypress.config`, any
`vite.config.js` file is not automatically merged.

#### Before - Cypress 10 and viteConfig

```js
import { defineConfig } from 'cypress'

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite',
      viteConfig: {
        // ... custom vite config ...
        // result merged with `vite.config` file if present
      },
    },
  },
})
```

#### After - Cypress 11 and viteConfig

```js
import { defineConfig } from 'cypress'
import viteConfig from './vite.config'

export default defineConfig({
  component: {
    devServer: {
      framework: 'react',
      bundler: 'vite',
      viteConfig: {
        ...viteConfig,
        // ... other overrides ...
      },
    },
  },
})
```

Vite 3+ users could make use of the
[`mergeConfig`](https://vitejs.dev/guide/api-javascript.html#mergeconfig) API.

## Migrating to Cypress 10.0

This guide details the changes and how to change your code to migrate to Cypress
version 10.0.
[See the full changelog for version 10.0](/llm/markdown/app/references/changelog.md#10-0-0).

### Cypress Changes

- The "Run all specs" and "Run filtered specs" functionality have been removed.
- The experimental "Cypress Studio" has been removed and will be
  rethought/revisited in a later release.
- Unsupported browser versions can no longer be run via `cypress run` or
  `cypress open`. Instead, an error will display.
- In 9.x and earlier versions, `cypress open` would bring you directly to the
  project specs list. In 10.0.0, you must pass `--browser` and `--e2e` or
  `--component` as well to launch Cypress directly to the specs list.

### Configuration File Changes

Cypress now supports JavaScript and TypeScript configuration files. By default,
Cypress will automatically load a `cypress.config.js` or `cypress.config.ts`
file in the project root if one exists. The
[Configuration guide](/llm/markdown/app/references/configuration.md) has been updated to
reflect these changes, and explains them in greater detail.

Because of this, support for `cypress.json` has been removed since Cypress `v10`.

Related notes:

- If no config file exists when you open Cypress, the automatic set up process
  will begin and either a JavaScript or TypeScript config file will be created
  depending on what your project uses.
- You may use the `--config-file` command line flag or the `configFile`
  [module API](/llm/markdown/app/references/module-api.md) option to specify a `.js` or `.ts`
  file. JSON config files are no longer supported.
- Cypress now requires a config file, so specifying `--config-file false` on the
  command line or a `configFile` value of `false` in the module API is no longer
  valid.
- You can't have both `cypress.config.js` *and* `cypress.config.ts` files. This
  will result in an error when Cypress loads.
- A
  [`defineConfig()`](/llm/markdown/app/references/configuration.md#Intelligent-Code-Completion)
  helper function is now exported by Cypress, which provides automatic code
  completion for configuration in many popular code editors. For TypeScript
  users, the `defineConfig` function will ensure the configuration object passed
  into it satisfies the type definition of the configuration file.
- Many pages and examples throughout the documentation have been updated to show
  configuration using `cypress.config.js` and `cypress.config.ts` vs the older
  `cypress.json`. For example:

```ts
{
  e2e: {
    baseUrl: 'http://localhost:1234',
  },
}
```

### Plugins File Removed

Because Cypress now supports JavaScript and TypeScript configuration files, a
separate "plugins file" (which used to default to `cypress/plugins/index.js`) is
no longer needed.

Support for the plugins file has been removed, and it has been replaced with the
new [`setupNodeEvents()`](/llm/markdown/app/references/configuration.md#setupNodeEvents) and
[`devServer`](/llm/markdown/app/references/configuration.md#devServer) config options.

Related notes:

- The `cypress/plugins/index.js` plugins file is no longer automatically loaded
  by Cypress.
- The [`setupNodeEvents()`](/llm/markdown/app/references/configuration.md#setupNodeEvents)
  config option is functionally equivalent to the function exported from the
  plugins file; it takes the same `on` and `config` arguments, and should return
  the same value. See the [Config option changes section](#setupNodeEvents) of
  this migration guide for more details.
- The [`devServer`](/llm/markdown/app/references/configuration.md#devServer) config option is
  specific to component testing, and offers a much more streamlined and
  consistent way to configure a component testing dev server than using the
  plugins file. See the [Config option changes section](#devServer) of this
  migration guide for more details.
- Many pages and examples throughout the documentation have been updated to show
  configuration in `setupNodeEvents` as well as the legacy plugins file. For
  example:

```ts
// bind to the event we care about
on('<event>', (arg1, arg2) => {
  // plugin stuff here
})
```

### Config Option Changes

#### baseUrl

The `baseUrl` config option is no longer valid at the top level of the
configuration, and may only be defined inside the
[`e2e`](/llm/markdown/app/references/configuration.md#e2e) configuration object.

Attempting to set the `baseUrl` config option at the top level of the
configuration will result in an error when Cypress loads.

#### componentFolder

The `componentFolder` config option is no longer used, as it has been replaced
by the `specPattern`
[testing-type specific option](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options).

Attempting to set the `componentFolder` config option will result in an error
when Cypress loads.

#### devServer

All functionality related to starting a component testing dev server previously
in the `pluginsFile` has moved here. These options are not valid at the
top-level, and may only be defined in the
[`component`](/llm/markdown/app/references/configuration.md#component) configuration object.

Related notes:

- Do not configure your dev server inside `setupNodeEvents()`, use the
  `devServer` config option instead.

See the dev server documentation for the UI framework you're using for more
specific instructions on what the `devServer` should be for that framework. Some
examples can be found in our
[framework documentation](/llm/markdown/app/component-testing/component-framework-configuration.md).

**Variant 1 (webpack & vite dev servers)**

```js title="cypress/plugins/index.js"
const { startDevServer } = require('@cypress/webpack-dev-server')
const webpackConfig = require('../../webpack.config.js')

module.exports = (on, config) => {
  if (config.testingType === 'component') {
    on('dev-server:start', async (options) =>
      startDevServer({ options, webpackConfig })
    )
  }
}
```

**Variant 2 (react plugin dev servers)**

```js
const devServer = require('@cypress/react/plugins/react-scripts')

module.exports = (on, config) => {
  if (config.testingType === 'component') {
    injectDevServer(on, config, {})
  }
}
```

#### experimentalStudio

This option is no longer used. The experimental "Cypress Studio" has been
removed and will be rethought/revisited in a later release.

Attempting to set the `experimentalStudio` config option will result in an error
when Cypress loads.

#### ignoreTestFiles → excludeSpecPattern

The `ignoreTestFiles` option is no longer used, and has been replaced with the
`excludeSpecPattern`
[testing-type specific option](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options).

Default values

- `e2e.excludeSpecPattern` default value is `*.hot-update.js` (same as pervious
  ignore value)
- `component.excludeSpecPattern` default value is
  `['/snapshots/*', '/image_snapshots/*']` updated from `*.hot-update.js`
- The `**/node_modules/**` pattern is automatically added to both
  `e2e.specExcludePattern` and `component.specExcludePattern`, and does not need
  to be specified (and can't be overridden).

```js
{
  "ignoreTestFiles": "path/to/**/*.js"
}
```

```js
{
  component: {
    excludeSpecPattern: "path/to/**/*.js"
  },
  e2e: {
    excludeSpecPattern: "other/path/to/**/*.js"
  }
}
```

Attempting to set the `ignoreTestFiles` config option will result in an error
when Cypress loads.

Also, attempting to set the `excludeSpecPattern` config option at the top level
of the configuration will result in an error when Cypress loads.

#### integrationFolder

This option is no longer used, as it has been replaced by the `specPattern`
[testing-type specific option](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options).

Attempting to set the `integrationFolder` config option will result in an error
when Cypress loads.

#### pluginsFile

This option is no longer used, and all plugin file functionality has moved into
the [`setupNodeEvents()`](/llm/markdown/app/references/configuration.md#setupNodeEvents) and
[`devServer`](/llm/markdown/app/references/configuration.md#devServer) options. See the
[Plugins file removed](#Plugins-File-Removed) section of this migration guide
for more details.

Attempting to set the `pluginsFile` config option will result in an error when
Cypress loads.

#### setupNodeEvents()

All functionality related to setting up events or modifying the config,
previously done in the plugins file, has moved into the `setupNodeEvents()`
config options. This option is not valid at the top level of the config, and may
only be defined inside the `component` or `e2e`
[configuration objects](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options).

More information can be found in the
[Node Events Overview](/llm/markdown/api/node-events/overview.md) and the
[Configuration API documentation](/llm/markdown/api/node-events/configuration-api.md#Usage).

&#x20;`cypress/plugins/index.js`

```js
module.exports = (on, config) => {
  if (config.testingType === 'component') {
    // component testing dev server setup code
    // component testing node events setup code
  } else {
    // e2e testing node events setup code
  }
}
```

```ts
{
  component: {
    devServer(cypressConfig) {
      // component testing dev server setup code
    },
    setupNodeEvents(on, config) {
      // component testing node events setup code
    },
  },
  e2e: {
    setupNodeEvents(on, config) {
      // e2e testing node events setup code
    },
  },
}
```

Alternately, you can continue to use an external plugins file, but you will need
to load that file explicitly, and also update it to move any component testing
dev server code into the [`devServer`](#devServer) config option.

```ts
import setupNodeEvents from './cypress/plugins/index.js'
```

```ts
{
  component: {
    devServer(cypressConfig) {
      // component testing dev server setup code
    },
    setupNodeEvents,
  },
  e2e: {
    setupNodeEvents,
  },
}
```

#### slowTestThreshold

The `slowTestThreshold` configuration option is no longer valid at the top level
of the configuration, and is now a
[testing-type specific option](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options).

Note that the default values are unchanged (`10000` for `e2e` and `250` for
`component`).

Attempting to set the `slowTestThreshold` config option at the top level of the
configuration will result in an error when Cypress loads.

#### supportFile

The `supportFile` configuration option is no longer valid at the top level of
the configuration, and is now a
[testing-type specific option](/llm/markdown/app/references/configuration.md#Testing-Type-Specific-Options).
More information can be found in the
[support file docs](/llm/markdown/app/core-concepts/writing-and-organizing-tests.md#Support-file).

```js
{
  "supportFile": "cypress/support/index.js"
}
```

```js
{
  component: {
    supportFile: 'cypress/support/component.js'
  },
  e2e: {
    supportFile: 'cypress/support/e2e.js'
  }
}
```

Attempting to set the `supportFile` config option at the top level of the
configuration will result in an error when Cypress loads.

Also, for a given testing type, multiple matching `supportFile` files will
result in an error when Cypress loads.

#### testFiles → specPattern

The `testFiles` option is no longer used, and has been replaced with the
`specPattern` option, which must be defined inside the
[`component`](/llm/markdown/app/references/configuration.md#component) and
[`e2e`](/llm/markdown/app/references/configuration.md#e2e) configuration objects.

Default values:

- No longer matches with `.coffee` or `.cjsx`.
- `e2e.specPattern` default value is `cypress/e2e/**/*.cy.{js,jsx,ts,tsx}`.
- `component.specPattern` default value is `**/*.cy.{js,jsx,ts,tsx}`.

Important note about matching:

- E2E tests will be found using the `e2e.specPattern` value.
- Component tests will be found using the `component.specPattern` value but any
  tests found matching the `e2e.specPattern` value will be automatically
  excluded.

Attempting to set the `testFiles` config option will result in an error when
Cypress loads.

Also, attempting to set the `specPattern` config option at the top level of the
configuration will result in an error when Cypress loads.

### Updated Test File Locations

Previously, you could specify the locations of test files and folders using the
configuration options: `componentFolder`, or `integrationFolder`, and
`testFiles`. These options have been replaced with `specPattern`, which is not
valid at the top-level, but within the
[`component`](/llm/markdown/app/references/configuration.md#component) or
[`e2e`](/llm/markdown/app/references/configuration.md#e2e) configuration objects. For
example:

```js
{
  "componentFolder": "src",
  "integrationFolder": "cypress/integration",
  "testFiles": "**/*.cy.js"
}
```

```js
{
  component: {
    specPattern: 'src/**/*.cy.js'
  },
  e2e: {
    specPattern: 'cypress/integration/**/*.cy.js'
  }
}
```

Attempting to set `componentFolder`, `integrationFolder`, or `testFiles` in the
config will result in an error when Cypress loads.

For Cypress Cloud users, changing your `specPattern` and files names or
extensions of your spec files will result in a loss of data in Cypress Cloud.
Because of this, if we detect your project is using Cypress Cloud during
automatic migration, we won't suggest changing your spec files. We also don't
recommend doing it manually if you are a Cypress Cloud user.

### Generated Files

Generated screenshots and videos will still be created inside their respective
[folders](/llm/markdown/app/references/configuration.md#Folders--Files) (`screenshotsFolder`,
`videosFolder`). However, the paths of generated files inside those folders will
be stripped of any common ancestor paths shared between all spec files found by
the `specPattern` option (or via the `--spec` command line option or `spec`
module API option, if specified).

Here are a few examples, assuming the value of `videosFolder` is
`cypress/videos`, `screenshotsFolder` is `cypress/screenshots` and
`cy.screenshot('my-screenshot')` is called once per spec file:

**Example 1**

- Spec file found
  - `cypress/e2e/path/to/file/one.cy.js`
- Common ancestor paths (calculated at runtime)
  - `cypress/e2e/path/to/file`
- Generated screenshot file
  - `cypress/screenshots/one.cy.js/my-screenshot.png`
- Generated video file
  - `cypress/videos/one.cy.js.mp4`

**Example 2**

- Spec files found
  - `cypress/e2e/path/to/file/one.cy.js`
  - `cypress/e2e/path/to/two.cy.js`
- Common ancestor paths (calculated at runtime)
  - `cypress/e2e/path/to`
- Generated screenshot files
  - `cypress/screenshots/file/one.cy.js/my-screenshot.png`
  - `cypress/screenshots/two.cy.js/my-screenshot.png`
- Generated video files
  - `cypress/videos/file/one.cy.js.mp4`
  - `cypress/videos/two.cy.js.mp4`

### Command / Cypress API Changes

#### cy.mount()

If you set up your app using the automatic configuration wizard, a basic
[`cy.mount()`](/llm/markdown/api/commands/mount.md) command will be imported for you in your
support file from one our supported frameworks.

#### Cypress.Commands.add()

[`Cypress.Commands.add()`](/llm/markdown/api/cypress-api/custom-commands.md) has been updated to
allow the built-in "placeholder" custom `mount` and `hover` commands to be
overwritten without needing to use `Cypress.Commands.overwrite()`.

### Component Testing Changes

Component Testing has moved from experimental to beta status in 10.0.0.

Component Testing can now be ran from the main app, and launching into component
testing via the command `cypress open-ct` is now deprecated. To launch directly
into component testing, use the `cypress open --component` command instead.

All the Component Testing dev servers are now included in the main `cypress` npm
package. Configuring them is done via specifying a framework and bundler in the
`devServer` config option, and the packages are no longer directly importable.
See
[Framework Configuration](/llm/markdown/app/component-testing/component-framework-configuration.md)
for more info.

The mount libraries for React and Vue have also been included in the main
`cypress` package and can be imported from `cypress/react` and `cypress/vue`
respectively.

Any previous dev servers or mounting libraries from the `@cypress` namespace
should be uninstalled in Cypress 10.

### Clashing Types with Jest

You may want to consider configuring your app with a separate `tsconfig.json` to solve
[clashing types with jest](/llm/markdown/app/tooling/typescript-support.md#Clashing-types-with-Jest).
You will need to exclude `cypress.config.ts`, `cypress`, `node_modules` in your
root `tsconfig.json` file.

```json
{
  "exclude": ["cypress.config.ts", "cypress", "node_modules"]
}
```

### Code Coverage Plugin

The [Cypress Code Coverage](https://github.com/cypress-io/code-coverage#readme)
plugin will need to be updated to version >= 3.10 to work with Cypress 10. Using
a previous version will result in an error when tests are ran with code coverage
enabled.

\--

For earlier migration guides, see the [documentation's repo history for this file](https://github.com/cypress-io/cypress-documentation/blob/main/docs/app/references/migration-guide.mdx).