用 Cypress + TypeScript 编写稳定…

当需要用 Cypress 在 TypeScript 中编写 E2E 或组件测试、控制网络请求、复用登录会话并接入 CI 时使用。

适用场景

解决思路

1. 先检查 `.agents/qa-project-context.md`，若存在则直接使用并跳过已回答的问题；否则确认：组件测试/E2E/两者、是否用 Cypress Cloud、是否用 TypeScript、框架与打包器、是否有跨域登录、是新建还是迁移现有套件。
2. 牢记 Cypress 命令是入队异步执行而非立即执行：不要用 `async/await`，不要把 `cy.get()` 的返回值存进变量；需要取值时用 `.then()`，例如 `cy.get('[data-testid="price"]').invoke('text').then((text) => { ... })`。
3. 利用内置重试：查询（`cy.get`、`cy.find`、`cy.contains`）和断言会自动重试直到通过或超时，但动作（`cy.click`、`cy.type`、`cy.select`）只执行一次；用 `cy.get('.loading').should('not.exist')`、`cy.get('.item').should('have.length', 5)` 这类断言等待状态。
4. 用 `cy.intercept` 做网络控制：stub 响应 `{ statusCode, body }` 后 `cy.wait('@alias')`；只监听不 stub 时 `.as('createOrder')` 再断言 `interception.request.body` 与 `interception.response?.statusCode`；用闭包 `callCount` 模拟轮询（202 → 200）；用 `{ statusCode: 500 }`、`{ forceNetworkError: true }`、`req.reply({ delay })` 模拟错误与慢响应；用 `req.continue((res) => { ...; res.send(); })` 修改真实响应；用 `{ fixture: 'api-responses/checkout-success.json' }` 走 fixture。拦截必须在触发请求的动作之前注册。
5. 保证测试隔离：每个 `it()` 默认清空 cookies、localStorage、sessionStorage，测试不得依赖其他测试的状态或顺序；共享准备放在 `beforeEach`，不要跨测试依赖。
6. 选择器统一用 `data-testid`、`data-cy` 或 `data-test`，并在 `cypress.config.ts` 中配置首选属性，避免 CSS 类选择器。
7. 按标准目录组织项目：拆分 `e2e/`、`component/`、`fixtures/`、`support/`，根目录放 `cypress.config.ts`；`baseUrl` 从环境变量读取（CI 中不要硬编码），显式设置 viewport，CI 下 `retries.runMode: 2`，组件测试在 `component.devServer` 配置框架/打包器，组件 spec 放在 `cypress/component/**/*.cy.tsx`。
8. 把重复动作封装为带类型的自定义命令：如 `login`（用 `cy.session` + API 而非 UI）、`getByTestId` 选择器简写、`shouldShowToast` 断言助手；在 `cypress/support/index.d.ts` 中用 `declare namespace Cypress { interface Chainable { ... } }` 加 JSDoc `@example` 声明以获得自动补全与编译期检查。
9. `cy.session` 必须传 `validate()` 回调（例如 `cy.request('/api/me').its('status').should('eq', 200)`），否则过期 token 会静默复用失效会话。
10. 自定义可重试查询用 `Cypress.Commands.addQuery()`，回调必须是非箭头 `function () {}`，因为 Cypress 需要把 `this` 绑定到命令超时；箭头函数会静默破坏重试能力（而 intercept 处理器用 `(req) => {}` 是可以的）。
11. 组件测试用 `cy.mount(<Component .../>)` 挂载单个组件，用 `cy.stub()`/`cy.spy()` 传回调，断言仍用 `cy.contains`/`cy.get`；组件测试中绝不使用 `cy.visit`；Vue 用 `cy.mount(Component, { props: { ... } })`。
12. 数据驱动测试分三层：静态 fixture 用 `cy.fixture('users').as('users')` 并在 `beforeEach(function () { ... })` 中通过 `this.users` 读取；动态数据在 `setupNodeEvents` 注册 `cy.task` 做 API 调用或 DB 播种（task 体在 Node 中运行，`fetch` 是 Node 全局 fetch）；环境相关配置在 `setupNodeEvents` 中按 `--env ENVIRONMENT=...` 合并 `baseUrl` 映射。
13. 跨域流程（SSO、OAuth、独立认证域）用 `cy.origin` 包裹在另一源上运行的命令，不要用 `chromeWebSecurity: false` 或 `experimentalSessionAndOrigin` 绕过；第三方支付 iframe（Stripe/PayPal）用 `cy.intercept` stub，绝不深入其内部。
14. CI 集成：GitHub Action 固定用 `cypress-io/github-action@v7`（最新 7.2.0，Node 24；仅 Node 20 runner 用 `@v6`）；用 Cypress Cloud 时设置 `projectId`、运行 `npx cypress run --record --key $CYPRESS_RECORD_KEY`，并用容器矩阵（`fail-fast: false`）并行以获得 flake 检测、Test Replay 与分析；不用 Cloud 时用 `@v7` 配合 `build`/`start`/`wait-on`，失败时上传 `cypress/screenshots` 与 `cypress/videos` 作为 artifacts。
15. 了解 Cypress AI（付费 Cloud 附加组件，2026 GA）：Auto Heal、AI Test Generation、AI Bug Triage，以及 `cy.prompt`（英文生成测试并运行时自愈）和 Cloud MCP（2026 年 5 月 GA，所有 Cloud 计划免费）；若团队已用 Cypress Cloud，购买附加组件可能比自建更便宜，在框架选型时提出。
16. 避免反模式：不要用 `cy.wait(3000)` 做同步（仅节流/防抖测试可接受，其余等网络别名或 DOM 断言）；不要基于 DOM 状态做条件测试（改为 stub 驱动该元素的 API）；不要用 CSS 选择器；不要在测试间共享状态（模块级 `let orderId` 等）；不要测第三方 iframe；不要每次 UI 登录（用 `cy.session` 且带 `validate()`）；不要在 `addQuery` 中用箭头函数；套件超过 5 分钟就并行化（Cypress Cloud、`cypress-split` 或 CI 矩阵手动分片）。
17. 按失败模式排查：`element is detached from the DOM` → 在 `.should`/`.then` 内重新查询而非持有旧引用；intercept 不匹配/别名不解析 → 检查方法或 glob，并确保拦截在触发命令之前注册；重定向报 `cross origin` → 用 `cy.origin` 包裹，不要禁用 `chromeWebSecurity`；会话复用但用户已登出 → 补 `validate()`；自定义查询永不超时 → 把箭头函数改成 `function () {}`。
18. 完成后验证：`npx cypress verify` 确认二进制可运行；`npx cypress run --spec "cypress/e2e/<file>.cy.ts"` 退出码 0；`npx cypress run --component --spec "cypress/component/<File>.cy.tsx"` 退出码 0；`npx tsc --noEmit` 通过。
19. 完成标准：`cypress.config.ts` 存在且 `baseUrl` 来自环境变量、显式设置 viewport，`npx cypress verify` 通过；自定义命令在 `cypress/support/commands.ts` 且 `index.d.ts` 声明齐全，`npx tsc --noEmit` 退出 0；`login` 命令用 `cy.session` 且带 `validate()`；套件中无用于同步的 `cy.wait(<数字>)`（`grep -rn "cy.wait([0-9]" cypress/` 除节流/防抖外无结果）；组件 spec 位于 `cypress/component/**/*.cy.tsx` 且 `npx cypress run --component` 退出 0；E2E 在 CI 通过（`npx cypress run` 退出 0），并有 Cypress Cloud 录制（并行）或失败时上传本地视频/截图 artifacts。

适用边界 · 注意事项

• 套件是 Playwright 而非 Cypress 时，改用 playwright-automation。
• 需要运行时逐测试 flake 修复、自愈定位器或隔离时，改用 test-reliability。
• UI 重构后需要批量重新生成选择器时，改用 selector-drift-recovery；从 Selenium 等其他套件迁移时用 test-migration。