Cypress: E2E and Component Testing Reference Guide

# Install
npm i -D cypress
# Component testing also needs your framework adapter (auto-installed by the wizard):
#   @cypress/react / @cypress/vue / @cypress/svelte / etc.

# Open the GUI (first run sets up cypress.config.ts + folders)
npx cypress open

# Run headlessly
npx cypress run                              # all e2e specs
npx cypress run --browser chrome             # pick a browser
npx cypress run --component                  # component testing
npx cypress run --spec "cypress/e2e/auth/**" # path filter
npx cypress run --env tag=smoke              # custom env var
npx cypress run --record --key $CY_KEY       # to Cypress Cloud / Currents

# cypress.config.ts (minimum)
import { defineConfig } from "cypress";
export default defineConfig({
  e2e: {
    baseUrl: "http://localhost:3000",
    setupNodeEvents(on, config) { return config; },
  },
  component: {
    devServer: { framework: "react", bundler: "vite" },
  },
  video: false,
  retries: { runMode: 2, openMode: 0 },
});

# package.json scripts
{
  "scripts": {
    "e2e":       "cypress run",
    "e2e:open":  "cypress open",
    "e2e:ci":    "start-server-and-test dev http://localhost:3000 e2e"
  }
}

// cypress/e2e/cart.cy.ts
describe("cart", () => {
  beforeEach(() => {
    // Stub list endpoint with a fixture
    cy.intercept("GET", "/api/items*", { fixture: "items.json" }).as("items");

    // Stub mutation with an explicit response
    cy.intercept("POST", "/api/checkout", {
      statusCode: 201,
      body: { paid: 999, id: "ord_1" },
      delay: 200,                              // simulate latency
    }).as("checkout");

    cy.visit("/cart");
  });

  it("submits the order", () => {
    cy.wait("@items");                         // pause until request fires
    cy.findByRole("button", { name: /pay/i }).click();

    cy.wait("@checkout").its("request.body").should("deep.include", { items: [] });

    cy.findByText(/order placed/i).should("be.visible");
  });

  it("handles a 500 from checkout", () => {
    cy.intercept("POST", "/api/checkout", { statusCode: 500 }).as("fail");
    cy.findByRole("button", { name: /pay/i }).click();
    cy.wait("@fail");
    cy.findByText(/something went wrong/i).should("be.visible");
  });
});

// cypress/support/commands.ts
Cypress.Commands.add("login", (email: string, pwd: string) => {
  // cy.session caches cookies + localStorage between tests
  cy.session(
    [email, pwd],                              // key — re-login when it changes
    () => {
      cy.request("POST", "/api/login", { email, pwd })
        .its("body.token")
        .then((token) => window.localStorage.setItem("token", token));
    },
    {
      validate() {                             // confirm cached session still works
        cy.request("/api/me").its("status").should("eq", 200);
      },
      cacheAcrossSpecs: true,                  // share across spec files
    },
  );
});

declare global {
  namespace Cypress {
    interface Chainable { login(email: string, pwd: string): Chainable; }
  }
}

// In a test
beforeEach(() => {
  cy.login("user@x.com", "pw");
  cy.visit("/dashboard");                      // already authed
});

// cypress/e2e/login.cy.ts
describe("login", () => {
  beforeEach(() => {
    cy.intercept("POST", "/api/login").as("login");
    cy.visit("/login");
  });

  it("rejects bad password", () => {
    cy.findByLabelText(/email/i).type("user@x.com");
    cy.findByLabelText(/password/i).type("wrong{enter}");
    cy.wait("@login").its("response.statusCode").should("eq", 401);
    cy.findByRole("alert").should("contain.text", "Invalid");
  });

  it("logs in and redirects", () => {
    cy.intercept("POST", "/api/login", {
      statusCode: 200,
      body: { token: "abc" },
    }).as("login");

    cy.findByLabelText(/email/i).type("user@x.com");
    cy.findByLabelText(/password/i).type("right{enter}");

    cy.wait("@login");
    cy.location("pathname").should("eq", "/dashboard");
    cy.findByText(/welcome/i).should("be.visible");
    cy.window().its("localStorage.token").should("eq", "abc");
  });
});