Cypress

A JavaScript end-to-end and component testing framework that runs inside a real browser. Time-travel debugging, automatic retries, network stubbing with cy.intercept(), session caching, and an interactive test runner — all built in.

What is Cypress?

Cypress is an open-source end-to-end testing framework for JavaScript applications. Unlike Selenium-based tools that control the browser remotely via WebDriver, Cypress runs directly inside the browser alongside your application. This architecture gives Cypress access to real DOM events, network requests, cookies, and application state — and enables the time-travel debugging experience in its interactive test runner.

Cypress supports two modes: E2E testing (loading your full app in the browser) and component testing (mounting individual React, Vue, Angular, or Svelte components in isolation). Both use the same assertion and command API. Tests are written in JavaScript or TypeScript, and the interactive runner shows you a live DOM preview at every command step.

Key Features

• Time-travel debugging — hover over any command in the log to see a DOM snapshot of that exact moment
• Automatic retry — commands and assertions auto-retry until they pass or time out, reducing flaky tests
• cy.intercept() — intercept, stub, or spy on any network request with fixture data or dynamic responses
• Component testing — mount and test individual components in real browser conditions (React, Vue, Angular, Svelte)
• cy.session() — cache and restore authentication state across tests and spec files for fast, DRY test suites
• Custom commands — extend cy with reusable commands (login, drag-and-drop, accessibility checks)
• Cypress Cloud — optional SaaS for parallel execution, test recording, video artifacts, and PR reporting
• Plugins ecosystem — first-class support for accessibility testing, visual regression, coverage, and more

Installation

# Install Cypress as a dev dependency
npm install --save-dev cypress

# Open the Cypress interactive test runner
npx cypress open

# Run tests headlessly (for CI)
npx cypress run

# Run a specific spec file
npx cypress run --spec "cypress/e2e/login.cy.ts"

# Run against a specific browser
npx cypress run --browser firefox

Writing E2E Tests

Tests are written with describe / it blocks using the cy command object. Commands chain together and execute sequentially; assertions auto-retry until they pass or time out.

// cypress/e2e/login.cy.ts
describe("Login flow", () => {
  beforeEach(() => {
    cy.visit("/login");
  });

  it("logs in with valid credentials", () => {
    cy.get('[data-testid="email"]').type("[email protected]");
    cy.get('[data-testid="password"]').type("s3cret");
    cy.get('[data-testid="submit"]').click();

    // Cypress auto-retries until the assertion passes or times out
    cy.url().should("include", "/dashboard");
    cy.contains("h1", "Dashboard").should("be.visible");
  });

  it("shows an error for wrong password", () => {
    cy.get('[data-testid="email"]').type("[email protected]");
    cy.get('[data-testid="password"]').type("wrong");
    cy.get('[data-testid="submit"]').click();

    cy.contains("Invalid credentials").should("be.visible");
  });
});

Network Stubbing with cy.intercept()

cy.intercept() lets you stub API responses with fixture files or inline objects, simulate error states, and alias requests to wait for them explicitly. This makes testing loading states and error handling deterministic.

// Intercept and stub network requests
describe("Posts page", () => {
  it("displays stubbed posts", () => {
    // Intercept GET /api/posts and return fixture data
    cy.intercept("GET", "/api/posts", { fixture: "posts.json" }).as("getPosts");

    cy.visit("/posts");
    cy.wait("@getPosts");

    cy.get('[data-testid="post-list"]').children().should("have.length", 3);
  });

  it("shows error state when API fails", () => {
    cy.intercept("GET", "/api/posts", { statusCode: 500 }).as("postsFail");

    cy.visit("/posts");
    cy.wait("@postsFail");

    cy.contains("Failed to load posts").should("be.visible");
  });
});

Custom Commands and Session Caching

Define custom commands in cypress/support/commands.ts. Combine them with cy.session() to cache authentication state across the entire test suite — login once, reuse everywhere.

// cypress/support/commands.ts — custom command for login
Cypress.Commands.add("login", (email: string, password: string) => {
  cy.session(
    [email, password],
    () => {
      cy.visit("/login");
      cy.get('[data-testid="email"]').type(email);
      cy.get('[data-testid="password"]').type(password);
      cy.get('[data-testid="submit"]').click();
      cy.url().should("include", "/dashboard");
    },
    {
      cacheAcrossSpecs: true, // reuse session across spec files
    }
  );
});

// In any test file:
beforeEach(() => {
  cy.login("[email protected]", "adminpass");
});

Component Testing

Cypress component testing mounts a component in a real browser environment. Use cy.mount() to render the component and the same cy assertions to verify behavior — no jsdom limitations.

// cypress/component/Button.cy.tsx — component test
import Button from "../../src/components/Button";

describe("Button", () => {
  it("renders the label", () => {
    cy.mount();
    cy.contains("Save").should("be.visible");
  });

  it("calls onClick when clicked", () => {
    const onClick = cy.stub().as("clickHandler");
    cy.mount();
    cy.get("button").click();
    cy.get("@clickHandler").should("have.been.calledOnce");
  });
});

Cypress vs Playwright

Pros and Cons