本技能用于在 TypeScript 中构建 Cypress 测试套件，覆盖 E2E 测试、组件测试、自定义命令、网络控制、登录缓存与 CI 集成。
【用途与定位】 技能面向需要编写 Cypress 测试的工程团队，帮助搭建测试项目结构、配置 cypress.config.ts、编写稳定的 E2E 与组件测试，并在 CI 中运行与并行化。技能强调用 TypeScript 编写测试（Cypress 原生支持 TypeScript）。
【核心原则】
- 命令是入队而非立即执行：cy.get、cy.click、cy.type 调用时不会执行，而是加入队列串行异步运行，不能使用 async/await，也不能把返回值存入变量，需用链式调用，需要取值时使用 .then()。
- 重试能力内建于查询而非操作：cy.get、cy.find、cy.contains 及断言会自动重试直到通过或超时，但 cy.click、cy.type、cy.select 等操作不会重试。
- 使用 cy.intercept 进行网络控制：在网络层拦截 HTTP 请求，可桩响应、等待请求完成、断言请求体；应等待网络别名或 DOM 断言，而不是固定的 cy.wait(ms)。
- 隔离性：每个 it() 运行在全新浏览器状态，Cypress 默认在测试间清除 cookies、localStorage 和 sessionStorage；测试不应依赖其他测试的状态或顺序。
- 使用数据属性作为测试选择器：如 data-testid、data-cy、data-test，可避免 CSS 重构、类名重命名和本地化影响。
【主要能力】
- E2E 测试：加载页面、拦截网络、断言。
- 自定义命令：封装重复操作，如登录（通过 cy.session + API 而非 UI）、getByTestId 简写、断言辅助。在 cypress/support/index.d.ts 中声明类型以获得自动补全和编译检查。cy.session 需要 validate() 回调，否则过期令牌会静默复用失效会话。可重试查询使用 Cypress.Commands.addQuery()，回调必须是非箭头函数。
- cy.intercept 模式：桩响应、监听不桩、条件响应（模拟轮询 202 到 200）、网络错误（500、forceNetworkError、延迟）、修改真实响应、基于 fixture 的响应。拦截需在触发请求的动作之前注册。
- 组件测试：用 cy.mount 挂载单个组件，传入 cy.stub()/cy.spy()，使用与 E2E 相同的断言链；组件测试中不要使用 cy.visit。
- 基于 fixture 的数据驱动测试：静态 fixture、通过 cy.task 在 Node 侧动态数据、按环境合并 baseUrl 配置。
- 跨域流程：对 SSO、OAuth 等跨域重定向，使用 cy.origin 包裹在另一源上运行的命令，不要关闭 chromeWebSecurity。
- CI 集成：固定 cypress-io/github-action@v7；使用 Cypress Cloud 时配置 projectId，运行 npx cypress run --record --key $CYPRESS_RECORD_KEY 并跨容器矩阵并行化；不用 Cloud 时通过 build/start/wait-on 以及上传截图和视频产物。
- Cypress AI：付费 Cloud 附加组件（2026 年 GA），包含 Auto Heal、AI Test Generation、AI Bug Triage、cy.prompt 和 Cloud MCP。
【使用方式】 标准布局将 e2e/、component/、fixtures/、support/ 分离，根目录 cypress.config.ts 配置两个运行器。关键配置：baseUrl 来自环境变量、显式 viewport、retries.runMode 设为 2（CI）、component.devServer 配置框架与打包器。组件规格位于 cypress/component/**/*.cy.tsx。验证命令包括 npx cypress verify、npx cypress run --spec、npx cypress run --component --spec、npx tsc --noEmit。
【适用场景】 需要编写稳定 E2E 或组件测试、控制网络请求、优化登录与 CI 并行执行的团队。
【限制与反模式】 避免用 cy.wait(毫秒) 同步（仅节流/防抖测试可接受）、基于 DOM 状态的条件测试、用 CSS 选择器代替数据属性、测试间共享状态、测试第三方 iframe、不用 cy.session() 登录或省略 validate()、在 addQuery 中使用箭头函数、在 CI 中串行运行全部测试。技能还列出了失败模式对照表，如元素脱离 DOM、intercept 未匹配、跨域错误、会话复用但用户已登出、自定义查询永不超时等。各参考文件（config-and-commands.md、intercept-patterns.md、component-and-fixtures.md、ci-recipes.md）的代码细节暂未提供完整内容。