\n\nFacts verified as of 2026-07.
\n
Version context (verified against docs.cypress.io, 2026-06): Cypress 14.x, Test\nReplay (v13+), cy.session with cacheAcrossSpecs. APIs move — confirm against the live\ndocs when a detail is load-bearing.
End-to-end and component testing with Cypress (cypress, TS/JS). The runner executes\ntests inside a real browser via the Cypress App (cypress open) or headlessly\n(cypress run). The defining mental model: cy.* commands are not promises — they\nenqueue onto an async command chain that Cypress drains for you. Internalise that and the\nagentic gotchas below disappear.
npm install -D cypress\nnpx cypress open # launch the Cypress App: pick E2E or Component, real browser\nnpx cypress run # headless run, all specs (CI default)\nnpx cypress run --spec \"cypress/e2e/auth/*.cy.ts\"\nnpx cypress run --component # run component specs\nnpx cypress run --browser chrome --headed\nnpx cypress run --record --key <k> # upload to Cypress Cloud (enables Test Replay, v13+)\nSpecs live in cypress/e2e/**/*.cy.ts (E2E) and beside components or cypress/component/\n(component). Config is a single cypress.config.ts at the repo root.
cy.get(...) returns a Chainer, not the element and not a Promise. Commands are\nscheduled, then run in order after the test function returns. This is the source of\nnearly every Cypress mistake an agent makes.
// WRONG — cy.get does not return a value; `el` is a Chainer, this is meaningless\nconst el = cy.get('[data-test=total]');\nif (el.text() === '$0') { /* never works */ }\n\n// WRONG — async/await does nothing useful; cy commands aren't awaitable promises\nconst text = await cy.get('[data-test=total]'); // do NOT do this\n\n// RIGHT — yield the value into a callback; assertions inside .should() retry\ncy.get('[data-test=total]').should('have.text', '$0');\n\n// RIGHT — need the raw value? use .then() (but it does NOT retry — see below)\ncy.get('[data-test=total]').invoke('text').then((text) => {\n // text is a string here; runs after the queue reaches this point\n});\nRules that follow from this:
\nconst/let to \"store\" a command result. Use .as() aliases + cy.get('@alias').async/await on cy.*. The queue handles ordering. Mixing in real promises?\nwrap them with cy.then(() => promise) or cy.wrap(promise).if/else on element state read synchronously. Conditional testing is an\nanti-pattern in Cypress (the DOM may not have settled); make the app deterministic, or\ndrive the branch off a server/cy.intercept state you control. Deep dive:\nreferences/network-and-auth.md.Cypress retries queries and assertions until they pass or the command times out\n(default 4s). It does not retry actions (.click(), .type(), .select()) —\nthose fire once, though the queries leading up to them retry until the element is\nactionable (visible, not disabled, not animating).
| Construct | \nRetries? | \nUse for | \n
|---|---|---|
cy.get / .find / .contains / .its / .invoke (queries) | \nYes — whole chain re-queries | \nLocating/reading DOM that may not be ready | \n
.should(...) / expect inside it | \nYes — the callback re-runs | \nAssertions; conditional waits on settled state | \n
.click / .type / .select (actions) | \nNo — fire once | \nInteractions (leading queries still retry) | \n
.then(cb) | \nNo — runs once, no retry protection | \nExtracting a value; NOT for assertions | \n
// .should(callback) retries the whole callback — safe for racy DOM\ncy.get('[data-test=rows] li').should(($li) => {\n expect($li).to.have.length(3);\n expect($li.first()).to.contain('Alice');\n});\n\n// .then() does NOT retry — capturing $el here then asserting later races the render\nIf you reach for cy.wait(3000), you're missing an assertion or an aliased intercept.\nThe only legitimate cy.wait takes an alias (cy.wait('@getUsers')), never a number.
Prefer a dedicated test attribute over CSS classes, IDs, or tag names — the latter are\nbrittle and change with styling/refactors. Cypress recommends data-cy or data-test\n(the Cypress Real World App standardises on data-test); pick one and enforce it.
// GOOD — decoupled from styling and structure\ncy.get('[data-test=submit]').click();\n\n// AVOID — couples the test to CSS/markup that changes for non-test reasons\ncy.get('.btn-primary').click();\ncy.get('#submit').click();\nWrap the convention in a custom command so specs stay terse:
\n// cypress/support/commands.ts\nCypress.Commands.add('getBySel', (sel, ...args) =>\n cy.get(`[data-test=${sel}]`, ...args));\nCypress.Commands.add('getBySelLike', (sel, ...args) =>\n cy.get(`[data-test*=${sel}]`, ...args)); // substring match\n// usage: cy.getBySel('submit').click();\nReserve cy.contains('Log In') for when the visible text itself is what you're\nasserting; otherwise it couples tests to copy.
cy.interceptcy.intercept is the single API for spying on and stubbing network traffic. Set it up\nbefore the action that triggers the request, alias it, then wait on the alias.
// Stub with a fixture, alias, wait\ncy.intercept('GET', '/api/users', { fixture: 'users.json' }).as('getUsers');\ncy.visit('/users');\ncy.wait('@getUsers'); // resolves when the request fires\n\n// Inline body / status\ncy.intercept('POST', '/api/login', { statusCode: 401, body: { error: 'nope' } }).as('login');\n\n// routeMatcher object (method + glob/regex url) + dynamic reply\ncy.intercept({ method: 'GET', url: '/api/orders/*' }, (req) => {\n req.reply((res) => { res.body.hasMore = false; }); // tweak the real response\n}).as('orders');\n\n// Assert against the captured request/response\ncy.wait('@login').its('response.statusCode').should('eq', 401);\n\n// Wait on several at once\ncy.wait(['@getUsers', '@orders']);\nStub what you don't own, exercise what you do. Stubbing third-party/slow endpoints\nmakes tests fast and deterministic; hitting your real backend (seeded via cy.request)\nverifies the client↔server contract. Decide per endpoint. GraphQL, request modification,\nand seed-via-cy.request patterns: references/network-and-auth.md.
cy.sessionLog in once, cache the session, restore it across tests (and optionally specs). This is\nthe biggest suite-speed win after stubbing.
\n// cypress/support/commands.ts\nCypress.Commands.add('login', (username: string, password: string) => {\n cy.session(\n [username, password], // cache key — array/object is stringified\n () => { // setup: runs only on cache miss\n cy.visit('/login');\n cy.get('[data-test=name]').type(username);\n cy.get('[data-test=password]').type(password);\n cy.get('form').contains('Log In').click();\n cy.url().should('contain', '/dashboard'); // assert logged-in before caching!\n },\n {\n validate() { // runs after setup AND after each restore\n cy.getCookie('auth_token').should('exist'); // invalid -> setup re-runs\n },\n cacheAcrossSpecs: true, // default false; true = reuse in every spec\n },\n );\n});\nCritical behaviour: cookies, localStorage, and sessionStorage across all domains are\ncleared before setup runs, regardless of testIsolation. Faster still: skip the UI and\nlog in via cy.request inside setup, persisting the token. Patterns (API login, token\npriming, cy.origin for cross-origin SSO): references/network-and-auth.md.
Same runner, two testing types. E2E drives a deployed app through cy.visit.\nComponent mounts a single component in a real browser via cy.mount — no server, no\nnavigation, props/events under direct control.
| \n | E2E | \nComponent | \n
|---|---|---|
| Entry | \ncy.visit('/path') | \ncy.mount(<Comp/>) | \n
| Needs running app server | \nYes | \nNo (bundler dev server only) | \n
| Spec location | \ncypress/e2e/**/*.cy.ts | \nbeside the component / cypress/component/ | \n
| Support file | \ncypress/support/e2e.ts | \ncypress/support/component.ts (registers cy.mount) | \n
| Best for | \nUser flows, integration, auth | \nProps/events/slots, edge states, visual | \n
// cypress/support/component.ts (React example)\nimport { mount } from 'cypress/react';\nCypress.Commands.add('mount', mount);\n\n// Button.cy.tsx\ncy.mount(<Button label=\"Save\" onClick={cy.stub().as('onClick')} />);\ncy.get('[data-test=button]').click();\ncy.get('@onClick').should('have.been.calledOnce');\nFrameworks: React 18–19, Vue 3, Angular 18–21, Svelte 5. Bundlers: Vite 5–8 (React/Vue/\nSvelte) or webpack 5 (all + Next.js). Configured under component.devServer.{framework,bundler}.\nMounting per framework, store/router mocking, slots: references/component-testing.md.
testIsolation: true (default, E2E) clears cookies/storage and resets to about:blank\nbefore each test. Each test must pass run in isolation (it.only to verify) — never\nrely on a previous test's state. Reset server-side state in beforeEach, not afterEach\n(an after hook may not run if you refresh mid-test).cypress/fixtures/, loaded by cy.fixture('users.json')\nor referenced directly in cy.intercept(..., { fixture: 'users.json' }).Cypress.Commands.add) live in cypress/support/commands.ts; add\nthe cypress/react (etc.) types and a declare global block for TS autocomplete.# GitHub Actions — the official cypress-io/github-action handles install + cache + run\n- uses: actions/checkout@v5\n- uses: cypress-io/github-action@v6\n with:\n build: npm run build\n start: npm start # boots app, waits on baseUrl before running\n wait-on: 'http://localhost:3000'\n browser: chrome\n record: true # upload to Cypress Cloud (Test Replay)\n env:\n CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}\n| Decision | \nGuidance | \n
|---|---|
| Start the app | \nStart it before Cypress (start + wait-on), kill after — never cy.exec a server mid-test | \n
| Parallelism | \ncypress run --record --parallel splits specs across machines — requires Cypress Cloud (paid). Free alternative: shard specs manually across matrix jobs with --spec | \n
| Retries | \nConfig retries: { runMode: 2, openMode: 0 } — surface flakes as a queue, don't paper over them | \n
| Debugging CI failures | \nTest Replay (v13+, Chromium-only) over video: captures DOM, network, console, errors for time-travel debugging in Cloud | \n
Full workflows (matrix sharding, containers, artifact upload): references/ci-and-flake.md.
\nMost Cypress flake traces to one of: an action chained where a query/assertion belonged, a\nmissing aliased cy.wait, conditional logic on un-settled DOM, or leaked state between tests.
| Symptom | \nLikely cause | \nFix | \n
|---|---|---|
| \"element detached from DOM\" | \nre-render between query and action | \nsplit the chain; let the action's leading query retry | \n
| passes alone, fails in suite | \ninter-test state coupling | \nreset server state in beforeEach; it.only to confirm | \n
cy.wait(number) \"fixes\" it | \nracing the network | \nreplace with cy.intercept(...).as() + cy.wait('@alias') | \n
value read with .then() is stale | \n.then doesn't retry | \nmove the assertion into .should(cb) | \n
Diagnosis tooling (Test Replay, cypress run --headed, time-travel in the App, screenshots/\nvideo), retry config, and a systematic playbook: references/ci-and-flake.md.
| Factor | \nCypress | \nPlaywright | \n
|---|---|---|
| Execution model | \nIn-browser, async command queue (no await) | \nOut-of-process, real async/await | \n
| Browsers | \nChrome-family, Firefox, Electron; WebKit experimental | \nChromium, Firefox, WebKit (real Safari) | \n
| Parallelism | \nCypress Cloud (paid) or manual sharding | \nFree, built-in, shardable | \n
| Multi-tab / multi-origin | \nConstrained (cy.origin for cross-origin) | \nNative | \n
| Component testing | \nMature, first-class | \nExperimental | \n
| Interactive DX | \nThe original benchmark (Cypress App, time-travel) | \nUI mode (excellent) | \n
| API testing | \ncy.request / cy.intercept | \nBuilt-in request context | \n
Reach for Cypress when component-testing maturity, an existing Cypress investment, or its\nin-browser DX dominate. Default to Playwright for new E2E needing WebKit, free parallelism,\nor heavy multi-tab/multi-origin work. Sibling skill: playwright-ops.
Full commented production template: assets/cypress.config.template.ts
\nimport { defineConfig } from 'cypress';\n\nexport default defineConfig({\n e2e: {\n baseUrl: 'http://localhost:3000', // cy.visit('/path') resolves against this\n specPattern: 'cypress/e2e/**/*.cy.{ts,tsx}',\n retries: { runMode: 2, openMode: 0 }, // retry in CI only\n setupNodeEvents(on, config) { return config; },\n },\n component: {\n devServer: { framework: 'react', bundler: 'vite' },\n },\n // testIsolation defaults true; viewportWidth/Height, defaultCommandTimeout tunable here\n});\n| File | \nContents | \n
|---|---|
| references/network-and-auth.md | \ncy.intercept matching/modifying/GraphQL, cy.session deep dive, API login, cy.origin, seed-via-request | \n
| references/component-testing.md | \nPer-framework cy.mount, store/router/context mocking, slots/events, Vite vs webpack config | \n
| references/ci-and-flake.md | \nFull GH Actions workflows, sharding, Test Replay, retry config, systematic flake playbook | \n
| assets/cypress.config.template.ts | \nCommented production config template (E2E + component) | \n