Playwright E2E Gap Testing
根据需求文档、前端代码，以及可选的后端代码和已有前端 E2E，用 Playwright 补齐可验证的端到端测试。只适配 Playwright；不要把本 skill 用于 Cypress、Selenium 或单元/组件测试。
强制流程
严格执行“入口阶段 0 + 七个执行阶段”：头脑风暴 → 测试设计文档 → 可执行任务计划 → 并行生成测试代码 → TDD 验证测试有效性 → 代码审查 → 运行与交付。每个阶段结束时暂停，向用户展示该阶段产物、未决问题和风险，并获得明确确认后才进入下一阶段。用户未确认时，不提前写后续阶段的代码或文档。
每个阶段都使用固定契约：
- 读取本阶段允许的输入。
- 产出可审阅的文件或结果。
- 标记假设、证据、未知项和阻塞项。
- 请求确认；收到确认后记录状态并继续。
0. 入口与测试模式判定
接收这些输入：
- 必需：项目需求/验收文档、前端代码。
- 可选：后端代码、已有前端 E2E 测试、运行说明和测试环境变量。
先确认 Playwright 配置、启动命令、浏览器矩阵、测试目录、认证方式和数据清理方式；缺失时一次只提出一个最影响推进的问题，不猜测命令。若需求文档和前端代码已经足以识别测试边界，仍先完成阶段 1 头脑风暴，把运行信息列为阻塞项并在确认门停止；只有连测试边界都无法判断时，阶段 0 才先提问并停留在入口。
按被测边界选模式：
| 需求证据 | 模式 | 后端处理 |
|---|---|---|
| 只验证页面状态、交互、路由、校验、可访问性或错误呈现 | 前端行为 | 默认使用 Playwright route/mock；契约来自前端调用和需求文档 |
| 验收依赖真实持久化、真实角色授权/服务端权限策略、异步任务、服务端计算、跨服务链路或数据库状态 | 前后端链路 | 启动真实后端；读取后端代码确认契约、种子数据和清理策略 |
| 无法判定边界 | 待确认 | 先向用户说明两种成本与风险，不生成测试代码 |
“权限错误”若只是验证页面如何呈现受控 401/403、禁用操作或错误页，属于前端行为，使用 route/mock；只有要证明真实角色授权或服务端权限策略时才使用真实后端。若同一验收同时要求 UI 呈现和服务端拒绝越权，拆成前端 mock 用例与真实后端链路用例，分别声明证据边界。没有后端代码且需求未要求证明服务端授权语义时，默认前端 mock；无法确认时停在待确认模式。
已有测试只能证明“当前覆盖现状”，不能当作需求真相。设计前先盘点已有测试文件、覆盖场景、当前执行结果和已知失败；若尚未运行 baseline，明确记录为“未知”，不能把测试文件内容当作执行证据。把已有测试用于去重、发现既有 fixture/selector 和识别回归风险，仍需按需求重新建立覆盖矩阵。已有测试通过不等于新增需求已覆盖。
1. 头脑风暴
阶段 1 不是一次性罗列场景，而是一个有确认门的澄清循环。只使用用户提供的需求、前端代码、可选后端代码和已有 E2E；不在此阶段写测试代码、测试设计文档或实现计划。
1.1 先分类，再开始提问
先向用户说明当前任务属于哪一类：
bounded：单一或少量前端旅程，验收标准清楚，主要工作是补测缺口。cross-flow：涉及多个角色、跨页面状态、真实后端链路、复杂数据准备或多个独立业务域。unclear：缺少需求边界、关键角色/状态、预期结果或测试运行前提，暂不能可靠识别场景。
分类只决定澄清深度，不代表可以跳过确认。头脑风暴中发现多个独立子系统、真实链路需求或隐藏依赖时，立即升级分类并重新确认范围；不能为了赶进度继续沿用较轻流程。
1.2 读取上下文并建立证据表
先盘点：用户角色和权限、入口页面、关键状态、业务对象、网络请求、错误状态、已有 fixture/locator、已有测试覆盖和当前 baseline 结果。为每个发现标记证据来源：requirement、frontend、backend、existing-test 或 assumption，并附可定位依据（文档章节、文件路径/行号、接口契约、测试名称或运行命令）。没有可定位依据的内容只能标为 assumption，不能冒充已验证事实。existing-test 只能说明现状，assumption 必须在后续提问中验证。
1.3 一次只问一个高影响问题
按对测试范围影响从高到低提问，每条消息只问一个问题；优先澄清：
- 这次验收要证明前端呈现，还是要证明真实后端/权限/持久化链路？
- 用户角色、前置数据和状态组合是什么？
- 成功、失败、空数据、无权限和网络异常分别应看到什么可观察结果？
- 哪些场景是本次必须补齐，哪些可以延后？
- 认证、数据隔离、清理和运行环境有什么约束？
问题应尽量提供 2–3 个可选解释或方案，并给出推荐及原因；不要把一长串问题一次抛给用户。用户回答后，先更新已确认事实、剩余假设和范围变化，再提出下一个问题。只有明确证明某问题不影响测试模式、可观察断言、数据隔离或用例范围时，才可记录为低优先级开放项；否则必须阻塞主线。
1.4 从发散收敛到测试范围
围绕用户旅程而不是页面清单发散：角色、前置状态、主成功路径、分支、失败/权限/空数据/网络异常、跨页面状态和高风险业务规则。对候选场景标为 must、should 或 defer，并记录证据、风险、前置条件和预期可观察结果。
对仍有多种合理解释的范围，提出 2–3 个切片方案，例如“最小关键路径”“关键路径 + 失败分支”“完整角色矩阵”，说明覆盖收益、实现成本和遗漏风险，给出推荐方案。不要为了追求全面而无条件扩大范围；不影响验收的内容标为 defer 或非目标。
收敛前必须给出一段简短总结：
- 已确认的角色、旅程、状态和验收结果；
- 采用前端 mock 还是真实后端，以及选择依据；
- 进入下一阶段的
must场景； - 明确排除或延后的场景及原因；
- 仍未解决的假设、风险和阻塞。
向用户请求对这份范围总结的明确批准，并附本次 e2e-brainstorm.md 的版本标识或变更摘要。只有用户明确批准该范围快照（如“确认 v1 范围”“继续当前版本”），才可进入阶段 2；未批准时继续澄清或修改总结。若发现新信息改变了已批准范围，暂停并重新打开本阶段，不得直接修改后续设计或测试代码。
1.5 阶段产物
输出 e2e-brainstorm.md，至少包含：任务分类、输入证据表、已确认事实、问题与用户决策记录、候选用户旅程、风险排序、must/should/defer 场景、mock/真实后端判定、非目标、开放阻塞项和批准状态。阶段确认语句必须说明“用户批准了哪些场景、哪些被排除、依据是什么，以及是否存在仍会阻塞测试设计的问题”。
2. 测试设计文档
把已确认场景转成可执行设计。至少包含：
- 需求 → 用户旅程 → 测试用例的可追溯矩阵；
- 每个用例的前置数据、动作、可观察断言、负面变体和清理；
- mock 响应或真实后端接口/数据契约；
- 稳定 locator 策略（优先角色、标签、可访问名称和显式
data-testid）； - 认证、隔离、并行安全、超时和重试策略；
- 不测什么，以及尚不能证明什么。
断言必须面向用户可见结果或业务状态，禁止只断言请求发出、任意 URL 片段或内部实现细节。输出 e2e-test-design.md，并在末尾列出“待用户确认”清单。
3. 可执行任务计划
把设计拆成能独立验收的小任务：fixture/数据、mock 或服务启动、认证、页面流、负面场景、清理、配置和文档。每项写明目标文件、前置依赖、实现步骤、验收命令和预期证据。标记可并行组与必须串行的依赖；避免两个任务修改同一文件的同一段。输出 e2e-test-plan.md，确认后才生成代码。
4. 并行生成测试代码（
有多代理能力时，每个独立任务分派一个干净上下文；提示中只传任务、设计片段、允许修改的文件和验收标准。各代理不得重写别人的 fixture、全局配置或既有测试；共享资源先由一个任务完成，再让依赖任务使用。没有多代理能力时按同一任务边界串行执行，不改变设计。
实现约束：使用 Playwright 原生 fixture、test.step、expect 和 route/mock；等待使用条件或 Playwright 自动等待，禁止固定 sleep；测试数据可重复、相互隔离、失败保留 trace/screenshot/video；真实后端测试必须有可逆清理，不能污染共享环境。
5. TDD 验证测试有效性
每个新增测试先证明“能抓到问题”，再证明“正常路径通过”：
- 先运行测试设计中的最小断言，建立红/阻塞证据；若立即通过，判断是已有覆盖、断言过弱还是缺少负例。
- 使用临时且可撤销的 mock 故障、筛选响应变体、权限响应变体或测试夹具变异制造预期失败；不要修改生产逻辑来制造失败。
- 加入最小测试实现（fixture、mock、测试步骤或稳定 locator），确认正常路径通过；除非用户明确授权，本 skill 不修改产品代码。
- 恢复正常数据，再运行负面变体，确认它确实因预期原因失败；记录红绿证据、命令和产物。
测试只测前端行为时，故障注入优先在 route/mock 层；链路测试可在隔离后端数据或受控服务响应层完成。无法制造可信负例时，标记为“有效性未证实”，不得宣称测试已验证。
6. 代码审查
审查以设计矩阵为基准，而不是以代码数量为基准。逐项检查：需求可追溯性、断言是否有意义、mock 是否掩盖真实契约、真实后端是否确实必要、locator 稳定性、竞态/重试/并行隔离、数据清理、错误信息和维护成本。审查发现问题时回到对应阶段修正并重新确认；不要用“测试能跑”替代设计审查。输出审查意见和已修复项。
7. 运行与交付
按范围递进运行：单文件/单项目 → 新增测试集 → 相关回归集 → 用户要求的全量 Playwright 集。记录实际命令、浏览器、环境、通过/失败/跳过、耗时和 trace 路径。失败先区分产品缺陷、测试缺陷、环境问题和数据污染；未定位的失败不得标为通过。
交付至少包括：新增/修改测试文件、e2e-brainstorm.md、e2e-test-design.md、e2e-test-plan.md、已有测试 baseline、运行结果、已知覆盖缺口、后续建议。最终确认中明确哪些结论由 mock 得出、哪些由真实后端得出，以及哪些场景仍缺证据；必须单列未验证的真实后端行为，不能把 mock 通过表述为端到端链路已验证。
阻塞与安全边界
- 缺少需求、无法启动应用、缺失认证/数据策略或模式有歧义：停在当前阶段并提问，不靠猜测推进。
- 不读取当前项目之外的文档或代码来补全业务假设；只使用用户提供的输入。
- 不把已有 E2E 复制成“新增覆盖”，不为了绿色结果放宽断言，不删除失败测试或隐藏 flaky 证据。
- 只创建或修改用户授权范围内的测试和文档；真实后端运行前确认环境、数据清理和副作用边界。
阶段确认模板
每阶段结束使用：
阶段 N 完成：<产物>。证据：<命令/结果>。风险与待确认：<列表>。是否进入阶段 N+1？
入口阶段使用：
阶段 0 完成：<已识别输入与边界>。阻塞：<缺失运行信息或“无”>。是否进入阶段 1？
只有用户明确确认（如“继续”“确认进入下一阶段”）才可推进；“看起来可以”但未明确确认时继续停留在当前阶段。
