cypress-e2e

Files (1)

• SKILL.md

SKILL.md (first lines)

## 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

```typescript
// 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("admin@test.com", "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");
  });
});
```

### Custom Commands

```typescript
// cypress/support/commands.ts
declare global {
  namespace Cypress {
    interface Chainable {
      loginByApi(email: string, password: string): Chainable<void>;

      getByDataCy(selector: string): Chainable<JQuery<HTMLElement>>;
    }
  }
}

// Login via API — skip the UI for non-login tests
Cypress.Commands.add("loginByApi", (email: string, password: string) => {
  cy.request("POST", "/api/auth/login", {email, password}).then((resp) => {
    window.localStorage.setItem("auth_token", resp.body.token);
  });
});

// Shorthand for data-cy selectors
Cypress.Commands.add("getByDataCy", (selector: string) => {
  return cy.get(`[data-cy=${selector}]`);
});
```

### API Mocking with cy.intercept

```typescript
describe("User Profile", () => {
  it("displays user data from API", () => {
    // Intercept and mock the API response
    cy.intercept("GET", "/api/users/me", {
      statusCode: 200,
      body: {
        id: "1",
        name: "Alice",
        email: "alice@test.com",
        role: "admin",
      },
    }).as("getProfile");

    cy.visit("/profile");
    cy.wait("@getProfile"); // Wait for the specific request

    cy.getByDataCy("user-name").should("contain", "Alice");
    cy.getByDataCy("user-role").should("contain", "admin");
  });

  it("handles API errors gracefully", () => {
    cy.intercept("GET", "/api/users/me", {
      statusCode: 500,
      body: {error: "Internal server error"},
    }).as("getProfileError");

    cy.visit("/profile");
    cy.wait("@getProfileError");

From dallay/agents-skills, MIT.

More from dallay/agents-skills