cypress-ops

Files (6)

• SKILL.md
• cypress.config.template.ts · assets/
• ci-and-flake.md · references/
• component-testing.md · references/
• network-and-auth.md · references/
• .gitkeep · scripts/

SKILL.md (first lines)

# Cypress Operations

> Facts verified as of 2026-07.

**Version context (verified against docs.cypress.io, 2026-06):** Cypress 14.x, Test
Replay (v13+), `cy.session` with `cacheAcrossSpecs`. APIs move — confirm against the live
docs when a detail is load-bearing.

End-to-end and component testing with Cypress (`cypress`, TS/JS). The runner executes
tests *inside* a real browser via the **Cypress App** (`cypress open`) or headlessly
(`cypress run`). The defining mental model: **`cy.*` commands are not promises** — they
enqueue onto an async command chain that Cypress drains for you. Internalise that and the
agentic gotchas below disappear.

## Quick Start

```bash
npm install -D cypress
npx cypress open                  # launch the Cypress App: pick E2E or Component, real browser
npx cypress run                   # headless run, all specs (CI default)
npx cypress run --spec "cypress/e2e/auth/*.cy.ts"
npx cypress run --component       # run component specs
npx cypress run --browser chrome --headed
npx cypress run --record --key <k>  # upload to Cypress Cloud (enables Test Replay, v13+)
```

Specs live in `cypress/e2e/**/*.cy.ts` (E2E) and beside components or `cypress/component/`
(component). Config is a single `cypress.config.ts` at the repo root.

## The Async Command Queue (read this first)

`cy.get(...)` returns a **Chainer**, not the element and not a Promise. Commands are
*scheduled*, then run in order after the test function returns. This is the source of
nearly every Cypress mistake an agent makes.

```ts
// WRONG — cy.get does not return a value; `el` is a Chainer, this is meaningless
const el = cy.get('[data-test=total]');
if (el.text() === '$0') { /* never works */ }

// WRONG — async/await does nothing useful; cy commands aren't awaitable promises
const text = await cy.get('[data-test=total]');   // do NOT do this

// RIGHT — yield the value into a callback; assertions inside .should() retry
cy.get('[data-test=total]').should('have.text', '$0');

// RIGHT — need the raw value? use .then() (but it does NOT retry — see below)
cy.get('[data-test=total]').invoke('text').then((text) => {
  // text is a string here; runs after the queue reaches this point
});
```

Rules that follow from this:
- **No `const`/`let` to "store" a command result.** Use `.as()` aliases + `cy.get('@alias')`.
- **No `async/await` on `cy.*`.** The queue handles ordering. Mixing in real promises?
  wrap them with `cy.then(() => promise)` or `cy.wrap(promise)`.
- **No `if/else` on element state read synchronously.** Conditional testing is an
  anti-pattern in Cypress (the DOM may not have settled); make the app deterministic, or
  drive the branch off a server/`cy.intercept` state you control. Deep dive:
  [references/network-and-auth.md](references/network-and-auth.md).

## Retry-ability (why you almost never need waits)

Cypress retries **queries** and **assertions** until they pass or the command times out
(default 4s). It does **not** retry **actions** (`.click()`, `.type()`, `.select()`) —
those fire once, though the queries *leading up to* them retry until the element is
actionable (visible, not disabled, not animating).

| Construct | Retries? | Use for |
|-----------|----------|---------|
| `cy.get` / `.find` / `.contains` / `.its` / `.invoke` (queries) | Yes — whole chain re-queries | Locating/reading DOM that may not be ready |
| `.should(...)` / `expect` inside it | Yes — the callback re-runs | Assertions; conditional waits on settled state |
| `.click` / `.type` / `.select` (actions) | No — fire once | Interactions (leading queries still retry) |
| `.then(cb)` | **No** — runs once, no retry protection | Extracting a value; NOT for assertions |

```ts
// .should(callback) retries the whole callback — safe for racy DOM
cy.get('[data-test=rows] li').should(($li) => {
  expect($li).to.have.length(3);
  expect($li.first()).to.contain('Alice');
});

// .then() does NOT retry — capturing $el here then asserting later races the render
```

If you reach for `cy.wait(3000)`, you're missing an assertion or an aliased intercept.
The only legitimate `cy.wait` takes an **alias** (`cy.wait('@getUsers')`), never a number.

## Selector Strategy

**Prefer a dedicated test attribute over CSS classes, IDs, or tag names** — the latter are
brittle and change with styling/refactors. Cypress recommends `data-cy` **or** `data-test`
(the Cypress Real World App standardises on **`data-test`**); pick one and enforce it.

```ts
// GOOD — decoupled from styling and structure
cy.get('[data-test=submit]').click();

// AVOID — couples the test to CSS/markup that changes for non-test reasons
cy.get('.btn-primary').click();
cy.get('#submit').click();
```

Wrap the convention in a custom command so specs stay terse:

```ts
// cypress/support/commands.ts
Cypress.Commands.add('getBySel', (sel, ...args) =>
  cy.get(`[data-test=${sel}]`, ...args));
Cypress.Commands.add('getBySelLike', (sel, ...args) =>
  cy.get(`[data-test*=${sel}]`, ...args));  // substring match
// usage: cy.getBySel('submit').click();
```

Reserve `cy.contains('Log In')` for when the **visible text itself** is what you're
asserting; otherwise it couples tests to copy.

## Network Stubbing — `cy.intercept`

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods