🌲 Cypress Setup & Usage

Why Cypress?

Older tools like Selenium control the browser from the outside, sending commands over a network connection. That gap causes the timing bugs that plague so many test suites. Cypress takes a different approach: it runs inside the browser, in the same event loop as your app. It can see every DOM element, every network request, and every piece of state directly.

That architecture gives Cypress its signature features:

• Automatic waiting — no manual sleeps; it waits for elements to be ready
• Time-travel debugging — hover over any step to see a DOM snapshot at that moment
• Real-time reloading — save a spec and it re-runs instantly
• Network control — stub and spy on requests with cy.intercept

Installing & Opening Cypress

Cypress installs as a dev dependency in any Node project. From your project root:

npm install cypress --save-dev

Then launch the interactive test runner:

npx cypress open

The first time you run this, Cypress opens a friendly setup wizard: it asks whether you want E2E Testing or Component Testing (choose E2E), scaffolds the folder structure for you, and lets you pick a browser. From then on, cypress open shows your specs and runs them in a real, visible browser.

open vs. run

There are two ways to execute Cypress, and knowing when to use each matters.

Add both as npm scripts so your team has one obvious way to run them:

{
  "scripts": {
    "cypress:open": "cypress open",
    "cypress:run": "cypress run",
    "test:e2e": "start-server-and-test start http://localhost:3000 cypress:run"
  }
}

Folder Structure

After setup, Cypress creates a cypress/ directory. Here's what lives where:

cypress/
├── e2e/            # Your test files (specs), named *.cy.js
├── fixtures/       # Static test data (JSON) loaded with cy.fixture
├── support/
│   ├── commands.js # Custom reusable commands (cy.login, etc.)
│   └── e2e.js      # Runs before every spec — global setup
└── downloads/      # Files your tests download during a run
cypress.config.js   # Project-wide configuration (lives at the root)

Your First Test

A Cypress spec uses the same describe/it structure you met in unit testing. Create cypress/e2e/home.cy.js:

// cypress/e2e/home.cy.js

describe('Home page', () => {
  beforeEach(() => {
    // Runs before each test — start from a clean, known page
    cy.visit('/');
  });

  it('displays the welcome heading', () => {
    cy.get('h1').should('contain', 'Welcome to Our App');
  });

  it('navigates to the login page', () => {
    cy.get('a[href="/login"]').click();          // act like a user
    cy.url().should('include', '/login');        // assert the outcome
    cy.get('h1').should('contain', 'Login');
  });
});

Home page
  ✓ displays the welcome heading (412ms)
  ✓ navigates to the login page (587ms)

2 passing

Read the second test aloud: "get the login link, click it, the URL should include /login, and the heading should say Login." That readability is the whole point — a good E2E test doubles as living documentation of how the app behaves.

The Core Commands

You can go a very long way with just six commands. Learn these and you can express most user journeys.

Chaining reads like a sentence

Cypress commands chain. Each one passes its found element to the next, so a login flow becomes a readable sequence:

it('logs in with valid credentials', () => {
  cy.visit('/login');

  cy.get('[data-cy="email"]').type('ada@example.com');
  cy.get('[data-cy="password"]').type('correct-horse-battery');
  cy.get('[data-cy="submit"]').click();

  // After login, we should land on the dashboard
  cy.url().should('include', '/dashboard');
  cy.contains('Welcome, Ada').should('be.visible');
});

A tour of .should() assertions

Assertions are how you verify the app did the right thing. A few of the most common:

cy.get('[data-cy="banner"]').should('be.visible');
cy.get('[data-cy="error"]').should('not.exist');
cy.get('h1').should('contain', 'Dashboard');
cy.get('[data-cy="email"]').should('have.value', 'ada@example.com');
cy.get('[data-cy="items"]').should('have.length', 3);

// Chain several with .and()
cy.get('[data-cy="status"]')
  .should('be.visible')
  .and('contain', 'Active');

Auto-Waiting & Retry-Ability

This is the feature that saves you from the number-one cause of flaky tests: bad timing. In older tools you constantly wrote "wait 2 seconds and hope the button appeared." Cypress makes that unnecessary.

Every time you query an element, Cypress automatically retries the command and its assertion until they succeed or a timeout (4 seconds by default) is reached. It waits for the element to exist, be visible, and be actionable before clicking.

// ❌ The old, flaky way — arbitrary sleep
cy.get('[data-cy="submit"]').click();
cy.wait(2000);                     // hope 2s is enough...
cy.get('[data-cy="toast"]').should('be.visible');

// ✅ The Cypress way — it retries until the toast appears
cy.get('[data-cy="submit"]').click();
cy.get('[data-cy="toast"]').should('be.visible');   // waits automatically

Config, Fixtures & Selectors

cypress.config.js and baseUrl

Project-wide settings live in cypress.config.js. The most important is baseUrl — set it once and every cy.visit('/products') becomes relative to it.

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

module.exports = defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',   // cy.visit('/') -> localhost:3000/
    viewportWidth: 1280,
    viewportHeight: 720,
    defaultCommandTimeout: 5000,        // how long retries keep trying
    setupNodeEvents(on, config) {
      // register cy.task handlers here (see next lesson)
    }
  }
});

With baseUrl set, your specs never hard-code the host. Point it at staging in CI and the same tests run against a different environment — no code changes.

Fixtures: reusable test data

Static data lives in cypress/fixtures as JSON and loads with cy.fixture. This keeps test data out of your test logic.

// cypress/fixtures/user.json
{
  "email": "ada@example.com",
  "password": "correct-horse-battery",
  "name": "Ada Lovelace"
}

// In a spec
it('greets the user by name', () => {
  cy.fixture('user').then((user) => {
    cy.visit('/login');
    cy.get('[data-cy="email"]').type(user.email);
    cy.get('[data-cy="password"]').type(user.password);
    cy.get('[data-cy="submit"]').click();
    cy.contains(`Welcome, ${user.name}`).should('be.visible');
  });
});

data-cy selectors: your test contract

How you find elements decides how brittle your tests are. Consider the range of options, from most to least stable:

Add the attribute in your markup, then select it in tests:

<button data-cy="login-button" class="btn btn-primary">Sign In</button>

cy.get('[data-cy="login-button"]').click();

Practice & Quiz

// cypress/e2e/tasks.cy.js
describe('Task app', () => {
  it('shows the heading and navigates to About', () => {
    cy.visit('/');
    cy.get('h1').should('contain', 'My Tasks');

    cy.get('[data-cy="about-link"]').click();
    cy.url().should('include', '/about');
  });
});

cy.get('[data-cy="load-more"]').click();
cy.wait(3000);
cy.get('[data-cy="item"]').should('have.length', 20);

cy.get('[data-cy="load-more"]').click();
// Cypress retries the assertion until 20 items exist — no sleep needed
cy.get('[data-cy="item"]').should('have.length', 20);

Best Practices & Pitfalls

✅ Do

• Set baseUrl and use relative paths in cy.visit
• Select elements with data-cy attributes, not styling classes
• Lean on auto-waiting — assert on conditions, not clocks
• Keep static test data in fixtures, out of your test logic
• Use cypress open to write and debug, cypress run in CI

❌ Don't

• Sprinkle cy.wait(ms) to "fix" timing — it hides real problems and slows the suite
• Target elements by deep CSS structure like div > ul > li:nth-child(2)
• Hard-code the host (http://localhost:3000/...) in every visit
• Reuse state between tests — each spec should stand on its own

Summary

📚 Additional Resources

• Cypress Docs — Why Cypress?
• Cypress Docs — Introduction & retry-ability
• Cypress Docs — Selecting elements (data-cy)
• Playwright — Writing tests (the alternative)

🚀 What's Next?

You can now write and run a Cypress test. Next you'll level up from individual commands to complete, resilient scenarios. In Writing E2E Test Scenarios, you'll structure real user journeys, seed state through the API and cy.task, stub the network with cy.intercept, and keep every test independent.