cypress-automation
Build Cypress test suites in TypeScript: E2E tests, component tests, custom commands, cy.intercept network control, cy.session login, Cypress Cloud, and CI integration. Covers retry-ability, the command queue, cross-origin flows with cy.origin, and data-driven testing with fixtures. Use when: "write E2E test in Cypress," "Cypress page object / custom command," "cy.," "cy.intercept," "Cypress component test," "Cypress Cloud," "cypress.config.ts." Not for: Playwright suites — use playwright-automation; flaky-test healing or quarantine — use test-reliability; bulk selector regeneration after a UI refactor — use selector-drift-recovery; Selenium-to-Cypress conversion — use test-migration. Related: playwright-automation, ci-cd-integration, visual-testing, unit-testing, test-reliability.
petrkindlmann · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add petrkindlmann/qa-skills --skill cypress-automation技能说明
name: cypress-automation description: >- Build Cypress test suites in TypeScript: E2E tests, component tests, custom commands, cy.intercept network control, cy.session login, Cypress Cloud, and CI integration. Covers retry-ability, the command queue, cross-origin flows with cy.origin, and data-driven testing with fixtures. Use when: "write E2E test in Cypress," "Cypress page object / custom command," "cy.," "cy.intercept," "Cypress component test," "Cypress Cloud," "cypress.config.ts." Not for: Playwright suites — use playwright-automation; flaky-test healing or quarantine — use test-reliability; bulk selector regeneration after a UI refactor — use selector-drift-recovery; Selenium-to-Cypress conversion — use test-migration. Related: playwright-automation, ci-cd-integration, visual-testing, unit-testing, test-reliability. license: MIT metadata: author: kindlmann version: "2.0" category: automation
Quick Route
| You need to... | Go to |
|---|---|
| Write an E2E spec (load, intercept, assert) | Core Principles + references/intercept-patterns.md |
Add a typed custom command / cy.session login | Custom Commands + references/config-and-commands.md |
| Mount and test a single component | Component Testing + references/component-and-fixtures.md |
Scaffold cypress.config.ts / project layout | Project Structure + references/config-and-commands.md |
| Stub, spy, simulate errors, or poll an API | cy.intercept Patterns + references/intercept-patterns.md |
| Run in CI / parallelize on Cypress Cloud | CI Integration + references/ci-recipes.md |
| Handle an SSO / OAuth redirect | Cross-Origin Flows + references/intercept-patterns.md |
Discovery Questions
Check .agents/qa-project-context.md first -- if it exists, use it and skip questions already answered there.
- Component testing, E2E, or both? Component testing mounts individual components in isolation; E2E tests the full app through the browser. Most projects need both. Component testing requires a framework-specific mount (React, Vue, Angular, Svelte).
- Cypress Cloud? Cloud provides parallelization, flake detection, analytics, Test Replay, and the AI add-on. If the team uses it, configure
projectIdand the record key. If not, everything runs locally or in CI without Cloud. - TypeScript? Strongly recommended and the default here -- Cypress supports it natively. All examples use TypeScript.
- Framework and bundler? React + Vite, Next.js + Webpack, Vue + Vite, Angular -- component-testing config depends on this.
- Cross-origin auth? If login redirects to a separate domain (SSO, OAuth provider), you need
cy.origin. Note it now so the login command is built for it. - Existing suite or fresh start? If migrating, start with the flakiest or most critical tests, not a big-bang rewrite (see
test-migration).
Core Principles
1. Commands Are Enqueued, Not Executed Immediately
The single most important concept. Cypress commands (cy.get, cy.click, cy.type) do not execute when called -- they are added to a queue and run serially, asynchronously. You cannot use async/await with Cypress commands, and you cannot store the return value in a variable.
// WRONG -- this looks synchronous but is not
const button = cy.get('[data-testid="submit"]'); // button is a Chainable, not an element
button.click(); // works only by accident, via chaining
// CORRECT -- chain commands; use .then() when you need a value
cy.get('[data-testid="submit"]').click();
cy.get('[data-testid="price"]').invoke('text').then((text) => {
const price = parseFloat(text.replace('$', ''));
expect(price).to.be.greaterThan(0);
});
2. Retry-ability Is Built-In (For Queries, Not Actions)
Cypress automatically retries queries (cy.get, cy.find, cy.contains) and assertions until they pass or time out. It does not retry actions (cy.click, cy.type, cy.select):
cy.get('.loading').should('not.exist')waits for the indicator to disappearcy.get('.item').should('have.length', 5)waits for 5 itemscy.click()executes once -- if the element is not actionable, it fails
3. Network Control with cy.intercept
cy.intercept intercepts HTTP requests at the network layer -- stub responses, wait for requests to complete, assert on request bodies. Mastering it is the difference between flaky and stable tests. Always wait on a network alias or a DOM assertion, never a fixed cy.wait(ms).
4. Isolation: Each Test Starts Clean
Every it() runs in fresh browser state -- Cypress clears cookies, localStorage, and sessionStorage between tests by default. Tests must not depend on other tests' state or order. Use beforeEach for shared setup, not inter-test dependencies.
5. Data Attributes for Test Selectors
Use data-testid, data-cy, or data-test. They survive CSS refactors, class renames, and localization. Configure the preferred attribute in cypress.config.ts.
Project Structure & Configuration
Standard layout splits e2e/, component/, fixtures/, and support/, with cypress.config.ts at the root configuring both runners. Key config choices: baseUrl from env (never hardcode for CI), explicit viewport, retries.runMode: 2 for CI, and the framework/bundler pair under component.devServer. Component specs live under cypress/component/**/*.cy.tsx.