cypress-e2e

When to Use

• Writing end-to-end tests for web applications with Cypress.
• Setting up API mocking with cy.intercept for deterministic tests.
• Creating reusable custom commands for common workflows.
• Configuring Cypress for CI/CD pipelines.
• Debugging flaky E2E tests or improving test reliability.

Critical Patterns

• Use data-cy Attributes: NEVER select elements by class name, tag, or content that changes with design or i18n. Use dedicated data-cy attributes that exist solely for testing.
• No Arbitrary Waits: NEVER use cy.wait(5000). Always wait for specific conditions: route aliases, DOM elements, or assertions that Cypress retries automatically.
• Test User Flows, Not Units: E2E tests validate complete workflows (login → navigate → perform action → verify result). For isolated logic, use unit tests.
• API-First Setup: Use cy.request() or API calls to set up test state (create users, seed data) instead of navigating through the UI. Reserve UI interactions for what you're actually testing.
• Each Test Stands Alone: Tests must not depend on previous tests or shared state. Use beforeEach to set up and clean state for each test.

Code Examples

Test Structure with Selectors

// cypress/e2e/dashboard.cy.ts
describe("Dashboard", () => {
  beforeEach(() => {
    // Set up state via API — fast and reliable
    cy.request("POST", "/api/test/seed", {fixture: "dashboard"});
    cy.loginByApi("[email protected]", "password123");
    cy.visit("/dashboard");
  });

  it("displays project list with correct count", () => {
    cy.get("[data-cy=project-list]").should("be.visible");
    cy.get("[data-cy=project-card]").should("have.length", 3);
  });

  it("creates a new project", () => {
    cy.get("[data-cy=create-project-btn]").click();
    cy.get("[data-cy=project-name-input]").type("New Project");
    cy.get("[data-cy=project-form-submit]").click();

    // Assert on visible result, not internal state
    cy.get("[data-cy=project-card]").should("have.length", 4);
    cy.contains("[data-cy=project-card]", "New Project").should("exist");
  });

  it("filters projects by status", () => {
    cy.get("[data-cy=filter-dropdown]").click();
    cy.get("[data-cy=filter-option-active]").click();

    cy.get("[data-cy=project-card]").should("have.length", 2);
    cy.get("[data-cy=active-filter-badge]").should("be.visible");
  });
});