Cypress

15.14.0 · active · verified Sat Apr 18

Cypress is a next-generation front-end testing tool built for the modern web, enabling fast, easy, and reliable testing for anything that runs in a browser. It supports end-to-end, component, and API testing. The current stable version is 15.14.0, and it maintains a regular release cadence with frequent minor updates and periodic major versions.

Common errors

```
Cypress detected that you are running a very old version of Node.js
```
cause Your Node.js runtime version does not meet Cypress's minimum requirements.

fix Upgrade your Node.js to a version compatible with Cypress (e.g., `^20.1.0 || ^22.0.0 || >=24.0.0`). You might use a tool like NVM (Node Version Manager) to manage multiple Node.js versions.
```
Cypress command `cy.route()` is deprecated. Please use `cy.intercept()` instead.
```
cause You are using an outdated command for network stubbing/spying.

fix Replace all instances of `cy.route()` with `cy.intercept()`. Review the Cypress documentation for `cy.intercept()` for detailed usage.
```
Timed out retrying: Expected to find element: '...', but never found it.
```
cause Cypress could not find the specified DOM element within the default command timeout (usually 4 seconds).

fix Verify the selector is correct and the element is present in the DOM within the expected time. Add explicit waits using `cy.wait('@alias')` for network requests, increase the command timeout if genuinely needed (`cy.get('selector', { timeout: 10000 })`), or ensure the element is rendered after any asynchronous operations.
```
Cypress failed to start. This may be due to a missing or invalid configuration file.
```
cause Cypress cannot find or correctly parse its configuration file.

fix Ensure you have a `cypress.config.js` or `cypress.config.ts` file in your project root, and it's correctly structured using `defineConfig`. If migrating from an older version, rename and update `cypress.json`.

Warnings

breaking Cypress requires specific Node.js versions. Ensure your Node.js environment meets the minimum requirements.
Fix: Upgrade your Node.js runtime to version `^20.1.0 || ^22.0.0 || >=24.0.0` or higher to match the package's engine requirements.
gotcha Cypress commands are asynchronous and queued, not immediately executed. They do not return promises directly, which can lead to common JavaScript asynchronous patterns (like `async/await`) not working as expected with `cy` commands.
Fix: Chain Cypress commands using their built-in chaining mechanism and `should()` or `then()` for assertions and further actions. Avoid mixing `cy` commands directly with `async/await` without careful wrapping or understanding of the command queue.
breaking Configuration files moved from `cypress.json` to `cypress.config.js` or `cypress.config.ts`.
Fix: Rename your `cypress.json` to `cypress.config.js` (or `.ts`) and update its structure to use the `defineConfig` helper. Refer to the Cypress migration guide for detailed instructions.
breaking The `cy.route()` command for network stubbing has been deprecated and replaced by `cy.intercept()`.
Fix: Refactor existing `cy.route()` calls to use `cy.intercept()`. `cy.intercept()` offers more powerful and flexible control over network requests.
gotcha Over-reliance on `cy.wait(ms)` for arbitrary time delays can lead to flaky tests, as it doesn't wait for specific conditions to be met.
Fix: Prefer using Cypress's built-in retryability and explicit waiting commands like `cy.wait('@alias')` for network requests, `cy.get('selector', { timeout: ms })` for element visibility, or `cy.contains('text')` to wait for specific content.

Install

npm install cypress npm
yarn add cypress yarn
pnpm add cypress pnpm

Imports

defineConfig
```
import { defineConfig } from 'cypress'
```
Used in `cypress.config.ts` or `cypress.config.js` for project configuration.

Quickstart

This quickstart shows how to define a basic Cypress configuration file (`cypress.config.ts`) and a simple end-to-end test (`example.cy.ts`) that navigates to a URL, interacts with an element, and asserts its state. After installing `cypress` as a dev dependency (`npm install -D cypress`), you can run `npx cypress open` to launch the test runner.

import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
  },
});

// cypress/e2e/example.cy.ts

describe('My First Test', () => {
  it('Visits the Kitchen Sink', () => {
    cy.visit('https://example.cypress.io');
    cy.contains('type').click();
    cy.url().should('include', '/commands/actions');
    cy.get('.action-email')
      .type('test@example.com')
      .should('have.value', 'test@example.com');
  });
});

view raw JSON →