Use this skill when writing Cypress e2e or component tests, creating custom commands, intercepting network requests, or integrating Cypress in CI. Triggers on Cypress, cy.get, cy.intercept, cypress component testing, custom commands, fixtures, cypress-cucumber, and any task requiring Cypress test automation.
Use this skill when writing Cypress e2e or component tests, creating custom commands, intercepting network requests, or integrating Cypress in CI. Triggers on Cypress, cy.get, cy.intercept, cypress component testing, custom commands, fixtures, cypress-cucumber, and any task requiring Cypress test automation.
When this skill is activated, always start your first response with the 🧢 emoji.
Cypress Testing
Cypress is a modern, developer-first end-to-end and component testing framework
that runs directly in the browser. Unlike Selenium-based tools, Cypress operates
inside the browser's execution context, giving it native access to the DOM, network
layer, and application state. This skill covers writing reliable e2e tests, component
tests, custom commands, network interception, auth strategies, and CI integration.
When to use this skill
Trigger this skill when the user:
Asks to write or debug a Cypress e2e test
Wants to set up Cypress component testing
Needs to intercept or stub network requests with cy.intercept
Asks how to use cy.get, cy.contains, or other Cypress commands
Wants to create reusable custom Cypress commands
Asks about fixtures, aliases, or the Cypress command queue
Is integrating Cypress into a GitHub Actions or other CI pipeline
Do NOT trigger this skill for:
Unit testing with Jest, Vitest, or similar (those don't use the Cypress runner)
Playwright or Puppeteer test authoring (different APIs entirely)
Key principles
Never use arbitrary waits - cy.wait(2000) is a smell. Use cy.intercept aliases
(cy.wait('@alias')), cy.contains, or assertion retries. Cypress retries
automatically for up to 4 seconds by default.
Select by data-testid - Never select by CSS class, tag name, or text that
changes. Add data-testid="submit-btn" to elements and select with
cy.get('[data-testid="submit-btn"]'). Classes are for styling; test IDs are for testing.
Intercept network requests - never hit real APIs - Use cy.intercept to stub
all HTTP calls. Real API calls make tests slow, flaky, and environment-dependent.
Stub responses with fixtures or inline JSON.
Each test must be independent - Tests must not share state. Use beforeEach
to reset state, reseed fixtures, and re-stub routes. Never rely on test execution
order. A test that only passes after another test ran is a bug.
Use custom commands for reuse - Repeated multi-step setups (login, seed data,
navigate to a page) belong in , not duplicated across
spec files. Custom commands keep specs readable and DRY.
cypress/support/commands.ts
Core concepts
Command queue and chaining - Cypress commands are not synchronous. Each cy.*
call enqueues a command that runs asynchronously. You cannot use const el = cy.get()
and then use el later. Instead, chain commands: cy.get('.item').click().should('...').
Never mix async/await with Cypress commands - it breaks the queue.
Retry-ability - Cypress automatically retries cy.get, cy.contains, and most
assertions until they pass or the timeout is exceeded. This is the correct alternative
to cy.wait(N). Structure assertions so they express the desired end state; Cypress
will poll until it's reached.
Intercept vs stub - cy.intercept(method, url) passively observes traffic.
cy.intercept(method, url, response) stubs the response. Both return a route that
can be aliased with .as('alias') and waited on with cy.wait('@alias'), which blocks
until the matching request fires - the correct way to synchronize on async operations.
Component vs e2e - Component testing mounts a single component in isolation
(like Storybook but with assertions). E2e testing visits a full running app in a real
browser. Use component tests for UI logic and edge-case rendering; use e2e tests for
critical user journeys. They use different cypress.config.tsspecPattern entries.
Common tasks
Write a page object pattern test
The Page Object pattern encapsulates selectors and actions behind readable methods,
decoupling tests from DOM structure.
Use cypress-image-diff or @percy/cypress. Always stub dynamic content (timestamps,
counts) before snapshotting, and wait for all async data to resolve first.
Hard-codes arbitrary delay; flaky in CI and wastes time on fast machines
Use cy.wait('@alias') on intercepted requests or assertion retry-ability
cy.get('.btn-primary')
CSS classes change with restyling, breaking unrelated tests
Use cy.get('[data-testid="..."]') exclusively for test selectors
Hitting real APIs in tests
Tests become slow, environment-dependent, and can mutate production data
Stub all HTTP with cy.intercept and fixtures
Logging in via UI in every test
Repeating form fill + submit across 50 tests is slow and brittle
Use cy.session + cy.request to authenticate programmatically
Sharing state between tests
it blocks that depend on prior it blocks fail non-deterministically
Reset state in beforeEach; each test must be self-contained
Using async/await with Cypress commands
Async/await bypasses the Cypress command queue, causing race conditions
Use .then() chaining for sequential async logic inside commands
Gotchas
Mixing async/await with Cypress commands breaks the queue - Cypress commands return a Cypress chainable, not a real Promise. Using await cy.get(...) bypasses the command queue, causing commands to run out of order or against stale DOM state. Use .then() chaining for sequential logic inside commands; never async/await in spec bodies.
cy.session cache invalidation surprises - cy.session caches authentication state across tests. If the backend invalidates the session (token expiry, server restart during the test run), all subsequent tests fail with 401s in ways that look like unrelated test failures. Add a validate callback to cy.session that confirms the session is still active before trusting the cache.
Intercepting too broadly breaks test isolation - Using cy.intercept('*', ...) to stub all requests catches requests you didn't intend to stub, including Cypress's own internal traffic and third-party scripts. Always use specific method + URL pattern matches and scope intercepts to the test that needs them.
Component tests mounting without providers - Components that rely on React context, Redux store, router, or i18n providers will crash or render incorrectly when mounted without those providers in cy.mount(). Always wrap cy.mount() with the necessary providers matching the app's actual setup.
data-testid on dynamically rendered lists - Adding a single data-testid="item" to a list renders multiple elements with the same selector. cy.get('[data-testid="item"]') returns a collection, and assertions on it behave unexpectedly. Use index-based IDs (data-testid="item-0") or use .eq(n) / .within() to scope assertions to specific list items.
References
For detailed content on specific topics, read the relevant file from references/:
references/commands-reference.md - Essential Cypress commands with real examples
Only load a references file when the current task requires deep detail on that topic.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
