end-to-end-testing

端到端测试

本技能帮助你编写、运行、审查和维护端到端（E2E）测试：这类自动化检查会像真实用户或客户端一样，对运行中的构建进行操作，测试整个系统，而不是隔离并模拟各个单元。你可以用它编写新测试套件、向现有套件添加测试、诊断不稳定或失败的测试运行，或评估他人的端到端测试变更。

此处的约定与框架无关。E2E 测试套件大致分为三类，这些原则适用于所有类型：

• 浏览器驱动的 UI（例如 Playwright、Cypress、WebdriverIO）——通过真实浏览器操作运行中的 Web 应用。
• 设备驱动的移动端 UI（例如 Maestro、Detox）——在模拟器、仿真器或设备上操作真实的应用构建。
• 协议 / HTTP 层级（例如通过 Vitest 测试真实 REST、GraphQL 或 MCP 客户端的套件）——启动真实服务，通过真实客户端测试其端点，不使用浏览器。

代码示例采用一种具体测试运行器（通常是 Playwright）作为范例。请将 API 转换为项目所用的测试运行器——真正适用于各种技术栈的是这些文字规则。

本技能负责 E2E 层级：针对真实构建进行的全系统检查。若某项检查通过模拟依赖来隔离单个单元，则属于单元测试层级；如果项目提供了单元测试技能，请遵循其中的约定。

测试层级与测试运行器无关。如果 E2E 套件使用项目提供了相关能力的测试运行器，那么该能力负责运行器自身的配置文件、项目、池、报告器和浏览器模式设置；而测试流程、定位器回退层级、服务生命周期和场景覆盖仍归本技能负责。

本文档中的关键词“MUST”“MUST NOT”“REQUIRED”“SHALL”“SHALL NOT”“SHOULD”“SHOULD NOT”“RECOMMENDED”“MAY”和“OPTIONAL”，应按 RFC 2119 中的定义进行解释。

运行端到端测试

请参阅 commands.md，了解：

• 默认的本地验证运行方式和更快的迭代运行方式
• 仅针对有意进行的视觉变更更新快照
• 通过 base-URL 环境变量指定开发环境、本地生产构建或已部署环境

测试套件结构

请参阅 structure.md，了解：

• 将 E2E 测试放在独立目录中，并使用专属的测试运行器文件匹配规则，与单元测试分开
• 路由树目录布局（默认），以及适用于单路由或以流程为中心的应用的基于用途的布局（冒烟测试 / happy-path / 回归测试 / 功能区域）
• 测试文件命名、测试用例命名和步骤粒度（多阶段场景使用步骤；简短的原子测试则省略步骤）

测试编写约定

请参阅 conventions.md，了解：

• 定位器 / 选择器回退层级（优先使用稳定的测试 ID，其次使用无障碍控件的角色，文本仅用于验证文案）
• 使用原生自动等待断言，而不是手动读取状态；并验证可观察到的约定，而非内部实现
• 使用轮询 / 等待条件辅助函数，而不是固定休眠，并了解禁止固定休眠的原因
• 不依赖具体测试用例的设置和清理钩子

测试环境与夹具

请参阅 test-environment.md，了解：

• 通过系统实际提供的客户端操作真实被测系统，并为每个文件共用一个客户端 / 上下文
• 在一个位置管理服务生命周期，并通过就绪状态轮询检查，而不是使用固定休眠
• 默认保持确定性：不访问实时外部网络；对于确实依赖网络的测试流程，提供手动绕过方式
• 在测试间复用一个已通过身份验证的会话，并集中管理返回已验证数据的数据 / API 辅助函数

场景覆盖情况

请参阅 scenario-coverage.md，了解：

• 场景覆盖率指标（断言的用户旅程，而非 e2e 行覆盖率）以及为何不采用行覆盖率
• 如何在人工编写的目录中添加或弃用旅程，以及如何为测试添加场景关联标签或 area/priority/smoke 分类标签
• 分阶段门槛（优先确保 must 优先级的旅程达到 100%）、项目自身的 CI 针对标准化 { title, tags, status } 结果结构实现的目录与标签关联，以及目录示例（assets/scenarios.example.md）