Playwright Test 交付规范

目录

1. 安装与放置
2. 配置最小集
3. 登录处理
4. 用例结构
5. 测试数据
6. 定位和等待
7. 判定与证据
8. 运行和验证

1. 安装与放置

• 先查找项目现有 playwright.config.*、@playwright/test、e2e/、tests/ 和包脚本。
• 已存在 Playwright Test 时只在现有结构中加用例。
• 不存在时，使用项目已有包管理器安装 @playwright/test，再通过对应的包执行命令运行 playwright install chromium，确认 Chromium 可以启动。
• 单应用项目把测试放在应用包内；多子模块共享同一测试环境时，优先使用已有根测试工作区。
• 不为初版建立公共包、服务、Page Object 框架或自研执行器。至少 3 条流程真实复用同一操作后再抽取小辅助函数。

2. 配置最小集

复用项目现有配置。新配置默认只包含：

• 从明确的测试环境取 baseURL，缺失时在打开浏览器前失败；
• Chromium 一个项目；
• 共享且会写数据的测试环境使用一个 worker；
• HTML 报告；
• 失败时保留截图和 trace，只有观察操作过程确实需要时才开启录像；
• 手动发起命令，不默认加 CI。

Playwright CLI 或 Playwright MCP 可以帮 AI 探索页面，但提交的用例始终由 Playwright Test 执行。

3. 登录处理

• 优先使用 Playwright storageState 复用专用测试账号的登录状态。
• 登录状态保存在 playwright/.auth/ 或项目已有私密状态目录，并加入忽略清单。
• 沿用项目已有运行产物目录；没有约定时，把 playwright/.auth/、playwright-report/、blob-report/ 和 test-results/ 加入项目忽略清单。.ai/web-e2e/ 中的任务卡需要长期保留，不得整体忽略。
• 首次登录使用可见浏览器。验证码、扫码和二次确认由用户完成。
• 如果测试可能同时改共享数据，禁止多个 worker 共用同一账号。
• 检测到登录跳转时立即报 BLOCKED，提示重新保存登录状态；不绕过安全校验。

4. 用例结构

• 一个用例只保护一个业务目标。
• 使用 test.step 按业务动作分段，步骤名使用页面负责人能看懂的语言。
• 在用例内创建唯一 runId，并在 finally 中清理本次写入。
• 前置数据缺失应显式失败或标记 BLOCKED，不改用 mock 跳过真实链路。
• API request 只用于任务卡授权的前置、触发或清理，用户主路径仍使用页面。

5. 测试数据

• 固定样本用业务名称或公开编号定位，不在仓库中硬编码短期数据库 ID。
• 动态数据同时包含项目专用前缀和 runId。
• 不使用真实手机号、真实用户信息和生产数据。
• 清理前再次确认前缀、runId 和记录 ID 均与本次创建一致。
• 当前无安全删除入口时，不直接删库；在任务卡说明会留下的测试记录。

6. 定位和等待

定位优先级：

1. getByRole、getByLabel、getByPlaceholder、getByText 等用户可见语义；
2. 包含本次唯一数据的表格行、弹窗或局部区域；
3. 页面已有稳定属性；
4. 只有前三种方式在真实运行中不稳定时才添加最少 data-testid。

等待用页面状态、请求结果或可见元素驱动。不用固定 sleep 隐藏加载、调度或竞态问题。轮询异步业务结果时，任务卡必须提供最长等待时间和可观察完成条件。

7. 判定与证据

• 使用 Playwright 自动重试的网页判定，验证最终业务状态而不是单次函数调用。
• 不因为点击成功就判定业务通过。
• 不对所有控制台消息一律判失败；只记录并判定与本次流程相关的页面错误和失败请求。
• HTML 报告用于总结，截图用于看现场，trace 用于还原每步页面和网络状态。
• 报告必须说明数据是否变更、是否清理，以及失败属于产品、测试还是环境。

8. 运行和验证

1. 运行项目现有的类型检查、构建或与本次测试相关的现有检查。
2. 在目标环境用可见浏览器运行新用例。
3. 检查 HTML 报告，不只看命令退出码。
4. 在只读步骤临时把一条关键断言改为必然失败，确认截图和 trace 存在，然后立即恢复断言。
5. 正常状态连续运行两次。两次都通过、清理结果一致，才报告完成。