🌲 Cypress Testing Framework

What Makes Cypress Different

Traditional tools like Selenium sit outside the browser and send commands across a network protocol (WebDriver). Cypress runs in the same run loop as your application, with direct access to the DOM, the network layer, and the browser's own APIs. That architecture is the source of nearly every Cypress feature you'll love.

💡 A useful analogy: A Selenium test is like operating a car by remote control from across the street — every command has a delay and you only see it from a distance. Cypress puts you in the driver's seat, hands on the wheel, watching the dashboard directly.

Installing & Configuring

Cypress installs as a single dev dependency — no separate browser drivers to manage.

# add Cypress to your project
npm install --save-dev cypress

# open the interactive Test Runner (also scaffolds the folders)
npx cypress open

# run everything headlessly (for CI)
npx cypress run

Add scripts so your team has a consistent entry point:

{
  "scripts": {
    "cy:open": "cypress open",
    "cy:run": "cypress run"
  }
}

The first run creates this structure:

cypress/
├── e2e/               # your test (spec) files, named *.cy.js
├── fixtures/          # static test data (JSON)
├── support/
│   ├── commands.js    # custom cy.* commands
│   └── e2e.js         # runs before every spec
└── cypress.config.js  # main configuration

The config file is a normal JS module. A modern setup with a base URL, sensible viewport, and CI retries:

// cypress.config.js
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    viewportWidth: 1280,
    viewportHeight: 720,
    // retry failed tests in CI only
    retries: { runMode: 2, openMode: 0 },
    setupNodeEvents(on, config) {
      // register plugins and Node-side tasks here
      return config;
    },
  },
});

Your First Test

A Cypress spec reads almost like plain English. describe groups related tests, it is one test, cy.* are commands, and .should() makes assertions.

// cypress/e2e/first-test.cy.js
describe('My first test', () => {
  it('visits a page and fills a field', () => {
    cy.visit('https://example.cypress.io');

    // find a link by its text and click it
    cy.contains('type').click();

    // Cypress waited for navigation automatically
    cy.url().should('include', '/commands/actions');

    // type into an input and assert its value
    cy.get('.action-email')
      .type('hello@example.com')
      .should('have.value', 'hello@example.com');
  });
});

You run tests two ways, and you'll use both:

• Interactive (cypress open) — a real browser with time-travel snapshots at every step. This is where you write and debug.
• Headless (cypress run) — command-line, records video and screenshots. This is what CI uses.

Automatic Waiting & Assertions

This is the concept that changes how you write tests. Cypress commands and assertions are retry-able: instead of failing the instant an element isn't ready, Cypress keeps re-trying (up to a timeout, 4 seconds by default) until the condition passes.

// Cypress automatically waits for the button to:
//   1. exist in the DOM
//   2. be visible
//   3. be enabled
//   4. not be covered by another element
// ...before it clicks. No manual wait needed.
cy.get('button[data-testid="save"]').click();

// The assertion retries too — it polls until the text
// appears or the timeout is reached.
cy.get('[data-testid="status"]').should('have.text', 'Saved');

Assertions chain naturally, and .and() adds more checks to the same subject:

cy.get('form.signup')
  .should('be.visible')
  .and('have.class', 'ready')
  .and('not.have.class', 'submitted');

// For custom logic, drop into .then() to get the raw element
cy.get('.item').should('have.length', 5).then(($items) => {
  expect($items.eq(0)).to.contain('First item');
});

Use aliases with .as() to reference an element or a request later without re-querying:

cy.get('button.submit').as('submitBtn');
cy.get('@submitBtn').click();

Selectors & Actions

The single biggest factor in whether your tests survive a redesign is how you select elements. Prefer selectors tied to meaning, not to styling or position.

The Cypress team recommends a dedicated data-testid (or data-cy) attribute for elements you test — it signals intent and never changes for cosmetic reasons.

Common actions

// mouse
cy.get('[data-testid="menu"]').click();
cy.get('.tile').dblclick();

// keyboard & special keys
cy.get('#search').type('cypress{enter}');
cy.get('body').type('{ctrl+k}');

// forms
cy.get('[type="checkbox"]').check();
cy.get('[type="radio"]').check('express');
cy.get('select').select('Priority');
cy.get('textarea').clear().type('New note');

Intercepting the Network

Because Cypress sits in the browser, it can watch and control every network request with cy.intercept(). This unlocks two superpowers: waiting on real requests and stubbing responses to test states that are hard to reproduce.

Wait on a request, not the clock

// register an interception and alias it
cy.intercept('GET', '/api/users').as('getUsers');

cy.visit('/users');

// wait until that exact request finishes — reliable, no guessing
cy.wait('@getUsers').its('response.statusCode').should('eq', 200);

Stub a response to force a scenario

// pretend the server returned an empty list
cy.intercept('GET', '/api/users', { statusCode: 200, body: [] }).as('empty');
cy.visit('/users');
cy.wait('@empty');
cy.contains('No users yet').should('be.visible');

// pretend the server errored — test your error UI
cy.intercept('GET', '/api/users', { statusCode: 500 }).as('boom');
cy.visit('/users');
cy.wait('@boom');
cy.get('[data-testid="error-banner"]').should('be.visible');

Inspect and assert on an outgoing request

cy.intercept('POST', '/api/users', (req) => {
  expect(req.body.email).to.equal('john@example.com');
  req.reply({ statusCode: 201, body: { id: 1 } });
}).as('createUser');

cy.get('form').submit();
cy.wait('@createUser').its('response.statusCode').should('eq', 201);

Organising a Suite

Three tools keep a growing suite fast and maintainable: custom commands, sessions, and Page Objects.

Custom commands

Wrap a repeated flow in a reusable cy command. Prefer the API-based version for speed — logging in through the UI on every test wastes seconds that add up to minutes.

// cypress/support/commands.js
Cypress.Commands.add('loginByApi', (email, password) => {
  cy.request('POST', '/api/login', { email, password }).then((res) => {
    window.localStorage.setItem('token', res.body.token);
  });
});

Persist login with cy.session()

Modern Cypress caches and restores browser state between tests, so you authenticate once instead of every test:

Cypress.Commands.add('login', (email, password) => {
  cy.session([email, password], () => {
    cy.loginByApi(email, password);
  });
});

// in a spec — instant on every run after the first
beforeEach(() => {
  cy.login('user@example.com', 'password123');
  cy.visit('/dashboard');
});

The Page Object pattern

Centralise a page's selectors and actions so a UI change means editing one file:

// cypress/support/pages/LoginPage.js
class LoginPage {
  visit() {
    cy.visit('/login');
    return this;
  }
  fillEmail(email) {
    cy.get('[data-testid="email"]').type(email);
    return this;
  }
  fillPassword(password) {
    cy.get('[data-testid="password"]').type(password);
    return this;
  }
  submit() {
    cy.get('[data-testid="submit"]').click();
    return this;
  }
  login(email, password) {
    return this.fillEmail(email).fillPassword(password).submit();
  }
}
export default new LoginPage();

// cypress/e2e/login.cy.js
import LoginPage from '../support/pages/LoginPage';

describe('Login', () => {
  it('logs in with valid credentials', () => {
    LoginPage.visit().login('user@example.com', 'password123');
    cy.url().should('include', '/dashboard');
  });
});

Hands-on Exercise

it('shows an error on bad credentials', () => {
  cy.intercept('POST', '/api/login', {
    statusCode: 401,
    body: { error: 'Invalid credentials' },
  }).as('login');

  cy.get('[data-testid="email"]').type('user@example.com');
  cy.get('[data-testid="password"]').type('wrong');
  cy.get('[data-testid="submit"]').click();

  cy.wait('@login');
  cy.get('[data-testid="error"]')
    .should('be.visible')
    .and('contain', 'Invalid credentials');
});

Summary & Quiz

📚 Further Reading

• Cypress — Best Practices
• Cypress — cy.intercept() reference
• Cypress — cy.session() reference

🚀 What's Next?

You can now write reliable Cypress tests. The final piece is running them automatically on every change: the next lesson wires your tests into a CI pipeline with GitHub Actions, parallelisation, reporting, and flaky-test handling.