cypress-ops

用途

本技能面向使用 Cypress 进行端到端（E2E）与组件测试的开发者，基于 Cypress 14.x（文档核验于 2026-06）。测试运行器通过 Cypress App（cypress open）在真实浏览器中执行测试，或以无头模式（cypress run）运行。核心心智模型：cy.* 命令不是 Promise，而是排入异步命令队列，由 Cypress 自动按序执行。理解这一点可避免绝大多数常见错误。

主要能力

异步命令队列：cy.get 返回 Chainer 而非元素或 Promise；不能用 const/let 存储命令结果，应使用 .as() 别名配合 cy.get('@alias')；不能在 cy.* 上使用 async/await；不能对元素状态做同步 if/else 条件判断。
重试能力：查询（cy.get/.find/.contains/.its/.invoke）与断言（.should）会重试直到通过或超时（默认 4 秒）；动作（.click/.type/.select）不重试，但前置查询会重试直到元素可操作；.then(cb) 不重试，仅用于取值而非断言。
选择器策略：优先使用专用测试属性（data-cy 或 data-test），避免 CSS 类、ID、标签名；可通过自定义命令 getBySel/getBySelLike 封装约定。
网络桩 cy.intercept：用于监听和桩化网络流量，支持 fixture、内联响应、routeMatcher 对象、动态回复，配合别名与 cy.wait('@alias') 使用。
认证 cy.session：登录一次并缓存会话，跨测试（可选跨 spec）恢复；setup 仅在缓存未命中时运行，validate 在 setup 后及每次恢复后运行；cacheAcrossSpecs 默认 false。
组件测试与 E2E 对比：E2E 通过 cy.visit 驱动已部署应用；组件测试通过 cy.mount 在真实浏览器中挂载单个组件，无需服务器。支持 React 18–19、Vue 3、Angular 18–21、Svelte 5，构建工具支持 Vite 5–8 或 webpack 5。
测试隔离与 fixtures：testIsolation 默认 true，每个测试前清除 cookies/storage 并重置到 about:blank；fixtures 为 cypress/fixtures/ 下的静态 JSON；自定义命令位于 cypress/support/commands.ts。
CI 集成：官方 cypress-io/github-action 处理安装、缓存与运行；并行需 Cypress Cloud（付费）或手动分片；retries 配置建议 runMode: 2, openMode: 0；Test Replay（v13+，仅 Chromium）用于调试 CI 失败。
Flake 诊断：常见原因包括动作与查询/断言链混淆、缺少别名 cy.wait、对未稳定 DOM 做条件逻辑、测试间状态泄漏；提供症状-原因-修复对照表。
Cypress 与 Playwright 对比：从执行模型、浏览器支持、并行、多标签/多源、组件测试、交互 DX、API 测试等维度给出选择建议。

使用方式

快速开始：

npm install -D cypress
npx cypress open                  # 启动 Cypress App：选择 E2E 或 Component，真实浏览器
npx cypress run                   # 无头运行全部 spec（CI 默认）
npx cypress run --spec "cypress/e2e/auth/*.cy.ts"
npx cypress run --component       # 运行组件 spec
npx cypress run --browser chrome --headed
npx cypress run --record --key <k>  # 上传到 Cypress Cloud（启用 Test Replay，v13+）

Spec 位置：E2E 位于 cypress/e2e/**/*.cy.ts；组件测试位于组件旁或 cypress/component/。配置为仓库根目录单一 cypress.config.ts。

配置骨架示例：

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.{ts,tsx}',
    retries: { runMode: 2, openMode: 0 },
    setupNodeEvents(on, config) { return config; },
  },
  component: {
    devServer: { framework: 'react', bundler: 'vite' },
  },
})

适用场景

需要成熟组件测试能力、已有 Cypress 投入、或偏好其浏览器内交互 DX 的项目。
用户流程、集成、认证等 E2E 场景；组件 props/事件/插槽、边界状态、视觉等组件场景。
需要网络桩化、会话缓存、CI 集成与 flake 诊断的测试体系。

限制

并行执行需 Cypress Cloud（付费），免费替代为手动分片。
多标签/多源支持受限（跨源需 cy.origin）。
WebKit 支持为实验性。
Test Replay 仅支持 Chromium。
新 E2E 项目若需 WebKit、免费并行或大量多标签/多源工作，建议默认选择 Playwright（姊妹技能：playwright-ops）。

参考文档

references/network-and-auth.md：cy.intercept 匹配/修改/GraphQL、cy.session 深入、API 登录、cy.origin、通过请求播种。
references/component-testing.md：各框架 cy.mount、store/router/context 模拟、插槽/事件、Vite 与 webpack 配置。
references/ci-and-flake.md：完整 GitHub Actions 工作流、分片、Test Replay、重试配置、系统化 flake 手册。
assets/cypress.config.template.ts：带注释的生产配置模板（E2E + 组件）。

技能介绍

用途

主要能力

使用方式

适用场景

限制

参考文档