Cache and restore authenticated session state across Cypress tests using cy.session()

domain: browser-automation · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Call `cy.session(id, setup)` with a string/array/object `id` and a required `setup` function that performs the login flow once
  2. Rely on Cypress caching cookies, `localStorage`, and `sessionStorage` (across all domains) under that `id` and restoring them instantly on subsequent calls with the same `id`
  3. Pass an `options.validate` callback to re-verify the restored session is still good; a failing assertion, thrown exception, or rejected promise invalidates the cache and re-runs `setup`
  4. Set `options.cacheAcrossSpecs: true` to share the in-memory session across every spec file in the same Cypress run (not written to disk, not shared across machines/runs)
  5. Keep the `id`, `setup`, `validate`, and `cacheAcrossSpecs` identical everywhere the same session is reused — Cypress throws if two calls with the same `id` disagree on any of them
  6. Call `cy.session()` at the start of each test rather than only in a global `before` hook, since sessions are restored per test, not persisted automatically between tests

Known gotchas

Related routes

test authentication flows that redirect across origins in cypress using cy.origin()
docs.cypress.io · 5 steps · unrated
stabilize dynamic ui before cypress screenshot comparisons using disabletimersandanimations
docs.cypress.io · 5 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans