Cypress Testing Guide

The complete reference for Cypress — the developer-first frontend testing framework. Covers E2E tests, component testing, network interception, custom commands, and CI integration.

What is Cypress?

Cypress is a JavaScript testing framework built specifically for the modern web. Unlike Selenium-era tools that drive browsers through WebDriver, Cypress runs directly inside the browser alongside your application. This architecture enables unique features: time-travel debugging (hover over any command in the runner to see the DOM state at that moment), real-time test reloading, direct access to application code and network requests, and automatic retries on assertions.

Cypress unified E2E and component testing under one API. With Component Testing mode, you can mount a React or Vue component directly in Cypress without a full app running, test it with the same cy.get() and cy.contains() commands, and get screenshots and video. This makes Cypress the only tool that covers both granular component tests and full user journey tests in a single runner.

Installation

# Install Cypress
npm install --save-dev cypress

# Open interactive runner
npx cypress open

# Run headlessly (CI)
npx cypress run

# cypress.config.ts
import { defineConfig } from 'cypress';

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.ts',
    supportFile: 'cypress/support/e2e.ts',
    video: false,               // Enable for CI
    screenshotOnRunFailure: true,
  },
  component: {
    devServer: { framework: 'react', bundler: 'vite' },
  },
});

Basic E2E Test: cy.visit, cy.get, cy.contains

// 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('secret{enter}');

    cy.url().should('include', '/dashboard');
    cy.contains('h1', 'Dashboard').should('be.visible');
  });

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

    cy.get('[role="alert"]').should('contain', 'Invalid credentials');
  });
});

Network Stubbing with cy.intercept()

describe('Products page', () => {
  it('shows products from API', () => {
    // Stub the API response
    cy.intercept('GET', '/api/products', {
      statusCode: 200,
      body: [
        { id: 1, name: 'Widget', price: 9.99 },
        { id: 2, name: 'Gadget', price: 19.99 },
      ],
    }).as('getProducts');

    cy.visit('/products');
    cy.wait('@getProducts');

    cy.contains('Widget').should('be.visible');
    cy.contains('Gadget').should('be.visible');
  });

  it('shows empty state when API returns empty array', () => {
    cy.intercept('GET', '/api/products', { body: [] }).as('getProducts');
    cy.visit('/products');
    cy.wait('@getProducts');
    cy.contains('No products found').should('be.visible');
  });

  it('handles API error', () => {
    cy.intercept('GET', '/api/products', { statusCode: 500 }).as('getProducts');
    cy.visit('/products');
    cy.wait('@getProducts');
    cy.contains('Something went wrong').should('be.visible');
  });
});

Custom Commands

// cypress/support/commands.ts
Cypress.Commands.add('login', (email: string, password: string) => {
  // Programmatic login via API — much faster than UI login
  cy.request('POST', '/api/auth/login', { email, password })
    .then(({ body }) => {
      window.localStorage.setItem('token', body.token);
    });
});

// Use cy.session() to cache login across tests
Cypress.Commands.add('loginAs', (role: 'admin' | 'user') => {
  cy.session(role, () => {
    const creds = { admin: ['[email protected]', 'admin'], user: ['[email protected]', 'user'] };
    cy.request('POST', '/api/auth/login', {
      email: creds[role][0], password: creds[role][1],
    }).then(({ body }) => {
      window.localStorage.setItem('token', body.token);
    });
  });
});

// In tests:
// cy.login('[email protected]', 'password');
// cy.loginAs('admin');

Component Testing

// cypress/component/Button.cy.tsx
import Button from '../../src/components/Button';

describe('Button component', () => {
  it('renders with correct label', () => {
    cy.mount(<Button label="Click me" onClick={cy.stub()} />);
    cy.contains('Click me').should('be.visible');
  });

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

  it('is disabled when disabled prop is true', () => {
    cy.mount(<Button label="Disabled" onClick={cy.stub()} disabled />);
    cy.get('button').should('be.disabled');
  });
});

Key Features

• Time-travel debugging — hover any command in the runner to inspect the DOM at that moment
• Automatic retry — assertions retry for up to 4 seconds before failing
• Real browser — runs in Chrome, Firefox, or Edge (not a headless simulation)
• Component testing — mount React/Vue/Angular components without a full app
• cy.intercept() — stub, spy on, or modify any HTTP request/response
• cy.session() — cache and restore login state for fast test setup
• Screenshots and video — automatic capture on failure, configurable

Comparison: Cypress vs Alternatives

Pros & Cons