cypress-consistency

Cypress — consistent, modern idioms

Cypress is stable and heavily represented in training data, but generated tests fight its core model: commands are enqueued, retried, and asynchronous, not values. Code drifts between removed APIs (cy.route, cy.server), hard sleeps, and Promise-style misuse (await cy.get(...), const el = cy.get(...)). This skill pins one canonical idiom set — Cypress 12+ semantics — so every spec respects the command queue and retry-ability.

Canonical idioms — always X, never Y

Always	Never	Why
cy.get("[data-cy=submit]").click() (one chain)	const btn = cy.get(...); btn.click()	Commands return chainers, not elements; the variable holds a queue handle, not a button.
cy.intercept("POST", "/api/login").as("login") then cy.wait("@login")	cy.wait(3000)	Waiting on the event is deterministic; waiting on time is flaky and slow.
cy.intercept(...)	cy.server() + cy.route()	cy.route/cy.server were removed in Cypress 12.
.then(($el) => { ... }) / aliases (.as) to use a value	let x; cy.get(...).then(v => x = v) then using x synchronously below	The synchronous code runs before any command executes; x is still undefined.
cy.session(user, loginFn) for auth	logging in through the UI in every test	One UI login spec is enough; sessions cache cookies/storage per user across specs.
[data-cy=...] / [data-testid=...] selectors	brittle CSS chains, nth-child, auto-generated classes	Test-dedicated attributes survive refactors; styling selectors don't.
assertions that retry: cy.get(...).should("have.length", 3)	expect($els.length).to.eq(3) inside a bare .then	.should re-runs the query until it passes; inside .then the snapshot is frozen.
fresh state per test via beforeEach (visit, seed, intercept)	tests depending on the previous test's end state	Order-dependent suites break under .only, retries, and parallelization.
cy.request/task for setup (seed via API)	building all preconditions through the UI	UI setup multiplies runtime and flake surface.

House style for a spec:

describe("checkout", () => {
  beforeEach(() => {
    cy.session("shopper", () => cy.login("[email protected]"));
    cy.intercept("POST", "/api/orders").as("createOrder");
    cy.visit("/cart");
  });

  it("places an order", () => {
    cy.get("[data-cy=checkout]").click();
    cy.wait("@createOrder").its("response.statusCode").should("eq", 201);
    cy.location("pathname").should("eq", "/orders/confirmation");
    cy.contains("[data-cy=banner]", "Thank you").should("be.visible");
  });
});

Pitfalls that produce flaky or vacuous tests

• async/await does not work with Cypress commands. await cy.get(...) neither waits nor errors usefully; the command queue is not a Promise chain. Use .then().
• Conditional testing on the DOM (if ($el.is(":visible"))) is a race by construction; control the application state instead (seed data, stub the response).
• Detached-element errors come from querying before a re-render, then acting after. Re-query in one chain after the action that causes the render; don't hold $el across it.
• Assertions in .then don't retry — move them to .should() (with a callback if complex: .should(($el) => { expect(...) }), which Cypress retries).
• cy.wait("@alias") without an assertion passes even on a 500 — chain .its("response.statusCode").should(...).
• Sharing cy state via closures across tests breaks under isolation; use aliases within a test and fixtures/tasks across tests.
• Visiting cross-origin needs cy.origin() — silent failures otherwise.

Version notes

Target Cypress 12+ (13/14 keep the same idioms). The key breaking lines: 10 (config moved to cypress.config.js, spec pattern, e2e/component split), 12 (removed cy.route/cy.server, test isolation on by default, cy.session stable). If a project is pre-10, flag the config migration rather than mixing both config styles.

Workflow

1. State first: decide how each precondition is created — cy.session for auth, cy.request/cy.task for data, cy.intercept for network control. UI only for the behavior under test.
2. Register intercepts before cy.visit/the triggering action; alias them.
3. Write each interaction as one query-action chain with data-cy selectors.
4. Assert with retrying .should(...) on elements, locations, and aliased responses.
5. When reviewing, hunt the classics: assigned command results, cy.wait(<number>), async test callbacks, conditional DOM logic, cy.route. Rewrite in canonical form.

For the fuller migration map (removed APIs → modern ones), aliasing and custom-command patterns, and expanded retry-ability rules, read references/cypress-patterns.md.