automated-e2e-testing

Files (3)

• SKILL.md
• helpers_reference.md · references/
• playwright-conventions.md · references/

SKILL.md (first lines)

# 自动化 E2E 测试（automated-e2e-testing）

本 skill 覆盖 Web 应用自动化测试的完整工作流：将手动测试用例（markmap + Schema）转化为 Playwright spec → 运行并验证 → 发现 Bug → 输出测试报告。

核心原则：
1. **先熟悉业务再写测试** — 对功能不熟悉时，先用自动化脚本主动探索系统，理解实际行为后再动手写测试代码
2. **有疑问就提问，不自行假设** — 编写过程中遇到任何不明确的地方，必须向用户提问澄清，绝不凭猜测写代码
3. **每条自动化用例对应一条手动用例，每条 test 只测一个点**
4. **每个 test 独立**（自建数据 + 自清理）
5. **必须使用 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

- 端到端测试整个需求（理解→策略→用例→执行→报告的流水线）→ 用 `qa` skill 编排
- 编写手动测试用例 → 用 `test-case-writing` skill
- 纯 API 接口测试（无 Web UI 流程）→ 用 `api-testing` skill
- 以**理解系统 / 发现风险**为目的的独立探索式测试会话（charter 驱动、产出探索笔记）→ 用 `exploratory-testing` skill；本 skill 的工作流零只做「为写自动化踩点」的小规模探索
- 已确认 Bug 的根因定位、影响分析、回归建议 → 用 `bug-analysis` skill；本 skill 只负责收集 Bug 证据（截图/API/控制台）并记录报告条目
- 代码变更后判断回归范围 → 用 `regression-testing` skill
- 单元测试 → 用 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-testing` skill。

### 步骤

1. **探索页面结构**：登录 → 导航到目标页面 → 截图 → 枚举所有可交互元素
2. **体验核心流程**：按测试用例步骤走一遍完整流程，每步截图，记录 API 调用
3. **记录发现**：页面导航路径、关键元素选择器、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` 产出）按用户的执行策略裁决执行；策略未定时向用户确认哪些用例转自动化

### 步骤

1. **解析测试用例**：从 markmap Markdown 提取场景与预期；test 名沿用用例的 TC 编号（如 `TC-01-03: {用例名称}`），手动用例缺编号时先补编号再转换
2. **选择/新建 Page Object**：检查 `tests/pages/` 下是否已有对应 Page Object，优先复用
3. **编写 spec**：使用 Page Object 封装所有页面交互。每条 test 收笔前过**断言三问**：① 前置里有"不应匹配/应被排除"的数据吗？断言覆盖了"不在"吗？② 被测步骤的触发方式与用例规格一致吗（不得为绕开不稳定换触发路径）？③ 失败时能区分"功能坏了"还是"环境没加载"吗？——判定与反例见工程约定第 15 节
4. **运行验证**：`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-analysis` skill（对应报告条目中根因分析等五个扩展字段留 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`**。

From fishzjp/qa-skills, MIT.

More from fishzjp/qa-skills