fishzjp 自动化 E2E 测试（automated-e2e-testing）
本 skill 覆盖 Web 应用自动化测试的完整工作流：将手动测试用例（markmap + Schema）转化为 Playwright spec → 运行并验证 → 发现 Bug → 输出测试报告。
核心原则：
- 先熟悉业务再写测试 — 对功能不熟悉时，先用自动化脚本主动探索系统，理解实际行为后再动手写测试代码
- 有疑问就提问，不自行假设 — 编写过程中遇到任何不明确的地方，必须向用户提问澄清，绝不凭猜测写代码
- 每条自动化用例对应一条手动用例，每条 test 只测一个点
- 每个 test 独立（自建数据 + 自清理）
- 必须使用 Page Object — 正式测试中禁止裸写定位器，所有页面交互封装在 Page Object 中
工程约定（脚手架、配置、场景代码模板、Page Object 规范）统一在 references/playwright-conventions.md——写代码时加载；通用 Helper（登录、多会话、证据收集）的参考实现在 references/helpers_reference.md；类型域三类执行片段（a11y 扫描 / 视觉基线 / 多浏览器矩阵）见工程约定第 12–14 节，type_scope 判入对应轴时按档加载取用
When to Use
- 给定测试用例（markmap / Schema），需要生成 Playwright spec 文件并执行
- 编写自动化前，需要小规模业务熟悉探索（踩点页面结构、提取选择器）
- 自动化执行中发现 Bug，需要收集证据并记录测试报告条目
- 需要编写新的 Page Object 或 Helper 函数
When NOT to Use
- 端到端测试整个需求（理解→策略→用例→执行→报告的流水线）→ 用
qaskill 编排 - 编写手动测试用例 → 用
test-case-writingskill - 纯 API 接口测试（无 Web UI 流程）→ 用
api-testingskill - 以理解系统 / 发现风险为目的的独立探索式测试会话（charter 驱动、产出探索笔记）→ 用
exploratory-testingskill；本 skill 的工作流零只做「为写自动化踩点」的小规模探索 - 已确认 Bug 的根因定位、影响分析、回归建议 → 用
bug-analysisskill；本 skill 只负责收集 Bug 证据（截图/API/控制台）并记录报告条目 - 代码变更后判断回归范围 → 用
regression-testingskill - 单元测试 → 用 Jest/Vitest；性能压测 → 专业工具（k6、locust）；安全测试 → 安全审计专项（见
test-strategy的 handoff 约定）
提问时机（必须遵守）
核心规则：不确定就问，宁可多问不要瞎猜。 格式与裁决规则统一按 ../core/clarify-pattern.md（场景用「执行确认」）。
| 场景 | 应提问的内容 | 不要自行假设 |
|---|---|---|
| 元素定位失败 | "在{页面}上找不到{元素}，实际页面结构是否与预期一致？" | 不要随意换选择器猜测 |
| 操作路径不明确 | "测试用例说{操作X}，但页面上没有直接的入口" | 不要自行拼凑操作步骤 |
| 预期行为有歧义 | "预期{结果A}，实际{结果B}，应以哪个为准？" | 不要选择性地相信其中一个 |
| 业务规则不清楚 | "规则{X}的具体边界是什么？" | 不要用常见默认值代替 |
| 探索中发现异常 | "发现{异常行为}，这是预期行为还是 Bug？" | 不要自行判定是 Bug 还是特性 |
| 用例反复超时/不稳定 | "{页面}是否存在长连接或轮询推送（WebSocket/SSE/心跳上报）导致页面永不空闲？" | 不要一律套 networkidle 等待，按等待降级阶梯处理 |
工作流零：业务熟悉（前置必做，为写自动化踩点的小规模探索）
何时需要：从未测试过该功能模块 / 出现不熟悉的页面路由 / 需要编写新的 Page Object / 拿到用例但不知道系统长什么样
本工作流是小规模踩点探索（理解页面结构、提取选择器、落 Page Object），产出服务于工作流一。以理解系统 / 发现风险为目的的完整探索会话（charter 驱动、产出探索笔记）用
exploratory-testingskill。
步骤
- 探索页面结构：登录 → 导航到目标页面 → 截图 → 枚举所有可交互元素
- 体验核心流程：按测试用例步骤走一遍完整流程，每步截图，记录 API 调用
- 记录发现：页面导航路径、关键元素选择器、API 接口、隐藏行为、编写或更新 Page Object
探索代码模板见 references/playwright-conventions.md 第 4 节（explore-*.spec.ts）。
完成标准
- 每个涉及的页面都有截图
- 理解了页面间的导航路径
- 确认了关键元素的选择器
- 记录了实际的 API 请求
- 发现了隐藏行为（隐藏字段、默认值、前置条件）
- 已编写或更新了对应的 Page Object
工作流一：手动用例 → 自动化代码
前提：已完成工作流零（业务熟悉），对目标功能有充分认知。
用例输入与自动化范围判定
输入是 test-case-writing 产出的 markmap 用例文件（如含 测试用例.schema.yaml 则一并消费）：
- Schema 的
execution_model: ui且automation.supported != no的用例 → 本工作流的转换对象 execution_model: dev-collab（无 UI 协作用例）→ 移交api-testing或保持手动协作执行，不硬造 UI 自动化automation_plan存在时（test-strategy产出）按用户的执行策略裁决执行；策略未定时向用户确认哪些用例转自动化
步骤
- 解析测试用例：从 markmap Markdown 提取场景与预期；test 名沿用用例的 TC 编号（如
TC-01-03: {用例名称}），手动用例缺编号时先补编号再转换 - 选择/新建 Page Object：检查
tests/pages/下是否已有对应 Page Object，优先复用 - 编写 spec：使用 Page Object 封装所有页面交互。每条 test 收笔前过断言三问：① 前置里有"不应匹配/应被排除"的数据吗？断言覆盖了"不在"吗？② 被测步骤的触发方式与用例规格一致吗（不得为绕开不稳定换触发路径）？③ 失败时能区分"功能坏了"还是"环境没加载"吗？——判定与反例见工程约定第 15 节
- 运行验证：
npx playwright test tests/{文件名}.spec.ts；基线零通过禁交付——首轮运行 0 条通过即视为流程认知错误（选择器/弹窗结构/等待假设与真实页面不符）：回工作流零针对性重踩核实，修订复跑至 ≥1 条通过后才可进入后续步骤，禁止交付基线零通过的规格
脚手架、场景代码模板（CRUD / 表单提交 / 状态流转 / 多用户并发）、Page Object 规范与 spec 命名此时加载 references/playwright-conventions.md（第 1、5–7 节）。
工作流二：Bug 探索与记录
在已理解业务逻辑的前提下，系统性验证页面功能，发现 Bug 和不一致。
批量失败前置分流：一轮执行结束失败 ≥3 条时，先加载
../core/triage.md做四分类定类（A 真缺陷 / B 资产问题 / C 环境 / D 不稳定），仅 A 类进入本工作流的证据收集与报告条目；<3 条维持单条流程不变。headless 流水线场景（PR 冒烟 / 夜间全量 / 发布卡点）：检查点降级为未决项、产物落盘规范与退出码语义按
../core/pipeline-integration.md（此时加载）；其回流闭环中的批量失败同样进入上方分流流程。
职责边界：本工作流负责发现 + 证据收集 + 报告条目。Bug 被确认后的根因定位、影响分析、回归建议移交
bug-analysisskill（对应报告条目中根因分析等五个扩展字段留 TODO）。
Bug 发现策略
| 策略 | 检查方式 | 典型 Bug |
|---|---|---|
| UI 预期不一致 | 对比测试用例与实际截图 | 默认值不对、文案错误 |
| 表单校验缺失 | 提交非法数据 | 必填不校验、范围不限制 |
| 网络异常 | 监听 API 响应 | 500 错误、超时 |
| 数据不一致 | 操作后 reload 验证 | 提交成功但数据丢失 |
| 状态流转错误 | 多步操作验证状态 | 状态未更新、卡死 |
| 控制台错误 | setupConsoleLogging(page) 持续监听 |
组件崩溃、静默失败 |
Bug 证据收集（发现 Bug 时必须执行）
Bug 发现 → 截图操作前 → 操作触发异常 → 截图操作后 → 收集 API/控制台日志 → 写入报告
证据收集代码（setupBugTracking / tracker.collect）见 references/playwright-conventions.md 第 8 节；通用 Helper 落地时加载 references/helpers_reference.md。
截图命名统一小写 bug-{序号}-* 前缀：手动截图记录过程两态（bug-001-01-操作前.png、bug-001-02-异常.png）；tracker.collect() 自动补一张整页汇总截图（bug-001-汇总.png）并 attach 到 HTML 报告。Bug 报告标题中的 BUG-{序号} 仅为显示格式。
Bug 报告格式
记录在 {项目名}/测试报告_{来源}_{日期}.md，条目字段与 ../core/report-template.md §3（测试报告唯一来源模板，此时加载）保持一致，保证条目可直接拼装进 qa 收尾的最终报告；本 skill 的发现方式含「业务熟悉探索」。执行分报告还需包含 §2 执行统计（P0/P1/P2 × 用例数/通过/失败/阻塞/未执行表，同样按 report-template）；条目中根因分析等五个扩展字段留 TODO，由 bug-analysis 填写。按 report-template「机读摘要」约定，分报告末节追加机读摘要片段（占位符替换后），供 qa 收尾与后续回归编排机读解析。
Explore 文件生命周期管理
业务熟悉探索文件（explore-xxx.spec.ts）是临时产物，遵循以下生命周期：
创建 explore-xxx.spec.ts → 提取知识到 Page Object → 删除 explore 文件 + 截图
规则
- 知识提取后立即删除：将发现的选择器、API 路径、页面结构写入 Page Object 或 helpers 后，删除 explore 文件
- 截图清理：探索产生的
debug-*.png截图是临时调试产物，确认不需要后删除 - 不积累：
tests/目录下不应存在已完成的 explore 文件。如果存在，说明知识提取步骤被跳过了 - Bug 报告截图保留：
bug-{序号}-*.png截图属于 Bug 报告的一部分，不删除
关键技巧速查表
下表方法名（
createDualSession/tracker.collect/setupBugTracking/isServerCrash等）为本 skill 脚手架内置 helper 的示例（定义在references/），不是 Playwright 通用 API——换项目时按references/helpers_reference.md适配实际脚手架，勿假定这些函数存在。
| 场景 | 方法 | 备注 |
|---|---|---|
| 受控组件输入框（Ant Design 等） | fill() 优先，不生效再 keyboard.type() |
fill 会派发 input 事件，多数受控组件可用；keyboard.type 逐键最稳但慢 |
| 确认弹窗按钮 | 在 role=dialog 作用域内定位（如 page.getByRole('dialog').getByRole('button', { name: '确定' })） |
防止与页面同名按钮歧义命中；弹窗外「确定/删除」同名按钮是常见误击源 |
| 隐藏必填字段 | page.evaluate() 直接设值 |
阻止表单提交的常见原因 |
| 网络请求验证 | page.on('request') 监听 |
必须在操作之前设置 |
| 数据持久化验证 | page.reload() + 断言 |
确认数据真正保存 |
| 多用户会话 | createDualSession(browser, roleA, roleB) |
两个角色并发 |
| 登录态复用 | createSession(browser, role) |
缓存 storageState 免重复 UI 登录（工程约定第 10 节） |
| 等待策略 | ① auto-wait + expect 断言 → ② waitForResponse → ③ networkidle（仅传统 SSR/MPA） |
自上而下优先（工程约定第 9 节）；固定 waitForTimeout 仅临时调试；长轮询/心跳页对 networkidle 永不空闲 |
| 并行执行 | 默认串行，独立性达标后开 workers |
前提：自建数据 + 自清理 + 唯一命名逐项核对（工程约定第 11 节） |
| flaky 定性 | 首次失败原样重跑通过 → 判 flaky | 重跑只用于定性；定位根因前标 test.fixme（工程约定第 11 节） |
| 截图调试 | page.screenshot({ fullPage: true }) |
每个关键步骤都截图 |
| 服务端崩溃检测 | isServerCrash(bodyText) |
检测 500/502 错误 |
| 唯一命名 | ${前缀}-${Date.now()} |
避免测试间名称冲突 |
| Bug 证据收集 | tracker.collect(testInfo, id, desc) |
一键收集截图+API+控制台 |
| Bug 探索前置 | setupBugTracking(page) |
注册 API 和控制台监听 |
Common Mistakes
| 错误 | 后果 | 正确做法 |
|---|---|---|
受控组件值不生效仍反复 fill() |
测试卡死或断言失败 | fill 失效时改用 keyboard.type()（见速查表） |
| 网络监听放在 click 之后 | 捕捉不到请求 | 先注册 listener，再执行操作 |
| 不清理测试数据 | 后续测试受影响 | afterEach 中删除创建的资源 |
| 用固定 timeout 等待 | 时序不稳定 | 按等待降级阶梯换用：① auto-wait+expect 断言 → ② waitForResponse → ③ networkidle（工程约定第 9 节） |
| 不验证持久化 | 数据可能只存在内存 | reload 后重新断言 |
| 正式测试不使用 Page Object | 代码重复，难以维护 | 所有页面交互封装在 Page Object 中 |
| explore 文件不删除 | 上下文污染，AI 每次读大量废代码 | 知识提取后立即删除 |
| 遇到疑问自行假设 | 产出不可靠的测试 | 不确定就向用户提问 |
| Bug 只截图不记录 API/控制台 | 开发无法定位根因 | 用 setupBugTracking() + tracker.collect() |
| 硬编码环境地址/账号 | 无法跨环境运行、泄露敏感信息 | 统一放 constants.ts / .env，代码只引用常量 |
| 失败重跑变绿就当没事 | flaky 混入主干，CI 随机红 | 按 flaky 定性流程处理：先定性再修根因，禁止调大重试硬压（工程约定第 11 节） |
| 对长轮询/推送页强套 networkidle | 超时假失败 | 按等待降级阶梯换 waitForResponse/断言自动轮询（工程约定第 9 节） |
| 每个 context 都走一遍登录页 | 执行时长翻倍、缓存认证态形同虚设 | 用 createSession() 复用 storageState，失效自动回退 UI 登录（工程约定第 10 节） |
| 所有用例永久串行不敢并行 | 全量执行时长线性膨胀 | 独立性核对通过后渐进开启 workers（工程约定第 11 节） |
| 手动用例信息不足仍硬造定位器与操作路径 | 幻觉自动化：断言全绿但没测到真实行为 | 先过 ../core/executability.md 转换闸门 + 工作流零踩点核实页面结构 |
与其他 skill 配合
- 上游：
test-case-writing产出手动用例（markmap + Schema）→ 本 skill 把execution_model: ui且可自动化的用例变成可执行代码；端到端流水线由qa编排 - 旁路：无文档 / 系统陌生的完整探索会话用
exploratory-testing，其探索笔记可作为本 skill 踩点的输入 - 下游：Bug 确认后的根因 / 影响 / 回归分析 →
bug-analysis；执行报告与 Bug 条目按../core/report-template.md对齐，供qa收尾汇总 - 平级：纯 API 用例的自动化 →
api-testing