Cypress E2E skill for Codex

A stable Cypress suite relies on retry-ability instead of waits, aliases every network call it depends on, builds state through cy.request or cy.session, and keeps each spec independent so it passes when run alone or in any order.

Inspect first

1. Read AGENTS.md, cypress.config.{ts,js}, cypress/support/e2e.*, cypress/support/commands.* and package.json scripts.
2. Check the version: npx cypress --version. Test isolation (fresh page, cookies and storage per test) is on by default since Cypress 12.
3. Look for @testing-library/cypress; if present use its findByRole queries.
4. Note how the app is started for tests (start-server-and-test, a Docker compose file, or a deployed URL). cypress run downloads nothing, but the first npm ci fetches the Cypress binary, which needs network.

Config baseline

// cypress.config.ts
import { defineConfig } from "cypress";

export default defineConfig({
  e2e: {
    baseUrl: "http://localhost:3000",
    specPattern: "cypress/e2e/**/*.cy.ts",
    retries: { runMode: 2, openMode: 0 },
    defaultCommandTimeout: 6000,
    video: false,
    screenshotOnRunFailure: true,
  },
  component: {
    devServer: { framework: "react", bundler: "vite" },
    specPattern: "src/**/*.cy.tsx",
  },
});

Secrets come from CYPRESS_* environment variables (read with Cypress.env("USER")), not from cypress.env.json committed to git.

The retry model

Cypress retries the last query in a chain until the assertion after it passes. Actions (click, type) do not retry.

// Good: query + assertion retry together
cy.findByRole("button", { name: "Place order" }).should("be.enabled").click();
cy.findByRole("status").should("have.text", "Order confirmed");

// Bad: stored value is a snapshot, never re-queried
const total = Cypress.$("[data-cy=total]").text();

• Never assign Cypress command results to variables; use .then(), .as() aliases, or cy.wrap.
• Long chains after an action re-query only from the action’s subject. Split them: cy.get("form").submit(); cy.get("[data-cy=errors]").should("be.visible");
• Use .should() callbacks for complex checks; they retry. .then() callbacks do not.

Selectors

Selector	Use
cy.findByRole("button", { name: "Save" })	first choice when Testing Library is installed
cy.get("[data-cy=cart-total]")	stable contract for elements without a good role
cy.contains("button", "Save")	quick text match scoped to a tag
CSS classes, nth-child	avoid; break on styling changes

Network: intercept, alias, wait

it("shows search results", () => {
  cy.intercept("GET", "/api/search*").as("search");
  cy.visit("/search");
  cy.findByRole("searchbox").type("lamp{enter}");
  cy.wait("@search").its("response.statusCode").should("eq", 200);
  cy.findAllByRole("article").should("have.length.at.least", 1);
});

it("renders the empty state", () => {
  cy.intercept("GET", "/api/search*", { body: { items: [] } }).as("search");
  cy.visit("/search?q=zzz");
  cy.wait("@search");
  cy.findByText("No results").should("be.visible");
});

• Register cy.intercept before the action that triggers the request, usually before cy.visit.
• cy.wait("@alias") waits for a specific request; cy.wait(2000) is never acceptable.
• Stub third-party and slow endpoints; keep at least one spec per critical flow hitting the real backend.

State setup without the UI

// cypress/support/commands.ts
Cypress.Commands.add("login", (email: string, password: string) => {
  cy.session(
    [email],
    () => {
      cy.request("POST", "/api/login", { email, password });
    },
    {
      validate() {
        cy.request("/api/me").its("status").should("eq", 200);
      },
      cacheAcrossSpecs: true,
    },
  );
});

declare global {
  namespace Cypress {
    interface Chainable {
      login(email: string, password: string): Chainable<void>;
    }
  }
}

beforeEach(() => {
  cy.login(Cypress.env("E2E_USER"), Cypress.env("E2E_PASSWORD"));
  cy.request("POST", "/api/test/seed", { scenario: "cart-with-two-items" });
});

• cy.session caches cookies and storage for the given id; validate re-runs login when the session expired.
• Test-only seed and reset endpoints must be disabled outside test environments.
• Each test sets up its own data. A test that relies on the previous test fails when run alone with --spec or it.only.

Time

cy.clock(new Date("2026-03-01T10:00:00Z").getTime());
cy.visit("/billing");
cy.tick(15 * 60 * 1000);
cy.findByRole("alert").should("contain", "Session expired");

Call cy.clock before cy.visit so the page’s timers are controlled from load.

Component testing

// src/components/QuantityPicker.cy.tsx
import { QuantityPicker } from "./QuantityPicker";

it("never goes below 1", () => {
  const onChange = cy.stub().as("onChange");
  cy.mount(<QuantityPicker value={1} onChange={onChange} />);
  cy.findByRole("button", { name: "Decrease" }).click();
  cy.get("@onChange").should("not.have.been.called");
});

Wrap providers (router, query client, theme) in a custom mount in cypress/support/component.tsx. Use component tests for interaction-heavy widgets; keep pure logic in unit tests.

Cross-origin

Visiting a second origin (an identity provider) needs cy.origin("https://idp.example", () => { ... }). Prefer logging in through an API or test-mode IdP over driving third-party login pages, which also tend to block automation.

Running

npx cypress run --spec "cypress/e2e/checkout.cy.ts"
npx cypress run --browser chrome --headless
npx cypress run --component
npx cypress open                      # interactive, needs a display; not for Codex sandboxes

Splitting specs across CI machines needs either Cypress Cloud (--record --parallel, requires a record key) or a community splitter that assigns spec files per job by timing; choose based on whether the team already pays for Cloud.

Flake checklist

• No cy.wait(<number>); every network dependency is an aliased intercept
• Intercepts registered before the triggering action
• Assertions follow the query they depend on (no stale variables)
• Data created per test via API; no reliance on spec order
• Animations do not block clicks (disable them in test builds, or assert visibility first)
• retries.runMode failures reviewed: a test that needed a retry is flaky, not passing

Gotchas

• cy.get(...).click({ force: true }) hides real bugs like overlays covering a button; use it only with a comment explaining why.
• .then() returning a non-Cypress value inside a chain can swallow retries.
• Detached DOM errors mean the element re-rendered between query and action; re-query after the state change instead of reusing an alias to the element.
• Uncaught app exceptions fail tests; fix them, or filter one known third-party error in Cypress.on("uncaught:exception"), never all.

Verification

1. Run the changed spec alone with --spec, three times in a row.
2. Run the whole suite headless in the CI browser.
3. Search the diff for cy.wait( followed by a number and for force: true.
4. Confirm a deliberate break fails with a screenshot showing the expected state.