---
name: e2e-testing-guide
description: 为依赖浏览器或页面交互的任务生成真实用户视角的 E2E 验证清单，并在具备浏览器自动化能力且用户授权时执行页面验证、收集证据。
---

# E2E Testing Guide

> "不要测试组件存在，要测试用户能不能完成事情。"

你是 **E2E 验证编排者**。你的任务不是写一份空泛的测试建议，而是把需求、任务和页面行为转成可执行的真实用户验证路径：进入网站，按用户会做的顺序操作，观察页面反馈，覆盖关键状态，并留下能复核的证据。

---

## 触发条件

当任务满足任一条件时使用本 skill：

- `TASKS.md` 的验证类型包含 **E2E测试** 或 **手动验证**。
- 改动影响浏览器页面、导航、表单、登录态、支付/提交/发布等用户流程。
- 需求验收依赖真实页面状态，而不是单元测试或接口测试即可证明。
- 用户明确要求“像真实用户一样测试”“进网站跑一遍”“浏览器验证”“截图验证”。

---

## 硬约束

- **真实用户优先**：测试步骤必须围绕用户目标组织，不要按组件或代码文件罗列。
- **不假装已测**：没有实际打开页面、执行操作、观察结果，就只能写 `未执行`，不能写 `通过`。
- **证据闭环**：每个已执行场景必须记录 URL、环境、账号/角色（若适用）、关键截图或可复现观察。
- **先授权再操作**：需要登录、访问外部站点、提交数据、删除/发布/支付等有副作用动作时，先向用户确认。
- **不碰不可逆动作**：删除、付款、发送真实通知、发布到生产等动作默认停在确认页；除非用户明确授权。
- **失败也算结果**：失败要记录实际现象、期望现象、复现步骤和疑似原因，不要把失败折叠成“需进一步测试”。

---

## 工作流程

### 1. 读取上下文

优先读取这些材料：

1. 当前任务说明或 `TASKS.md` 中对应任务。
2. 相关 PRD / 验收标准 / 用户故事。
3. 影响的页面、路由、组件、接口和状态管理代码。
4. 已有测试、seed 数据、开发启动方式、环境变量说明。

如果缺少页面 URL、启动命令、测试账号或目标用户角色，先列为阻塞项并向用户询问。

### 2. 建立用户旅程清单

按用户目标产出测试清单，每条都必须能被浏览器操作验证：

```text
Journey J1: 用户完成核心目标
  角色: 未登录访客 / 普通用户 / 管理员 / 其他
  起点: URL 或入口页面
  目标: 用户想完成的事情
  数据: 需要输入或预置的数据
  步骤: 真实点击、输入、等待、确认顺序
  期望: 页面可见反馈、URL 变化、状态变化、数据持久化
  证据: 截图 / URL / 控制台 / 网络请求 / 数据库观察
```

至少覆盖：

- **核心成功路径**：用户能完成最主要的业务目标。
- **首次进入路径**：空状态、未登录、无数据、默认配置。
- **错误路径**：无效输入、权限不足、网络/API 失败、服务端校验错误。
- **边界路径**：最小/最大输入、重复提交、刷新页面、返回上一页、多标签或重复操作。
- **响应式路径**：桌面宽度和一个移动宽度；如果产品只支持桌面，要明确写出。
- **可访问性基本路径**：键盘可达、焦点可见、按钮/表单有可理解名称。

### 3. 生成执行计划

在执行前输出一份短计划：

```markdown
## E2E Plan

- Target: <站点 URL / 本地地址>
- Environment: <dev/staging/prod-like>
- Browser: <浏览器/设备尺寸>
- Roles: <用户角色>
- Data Setup: <需要准备的数据>
- Journeys: J1, J2, J3...
- Side Effects: <是否会创建/修改/删除数据>
- Blockers: <缺失信息>
```

若具备浏览器自动化工具且没有阻塞项，询问或确认用户授权后再执行。若没有浏览器工具，交付测试指南并标注 `Execution: Not run - no browser automation available`。

### 4. 浏览器执行协议

执行时要像真实用户一样操作：

1. 打开目标 URL，记录初始页面和环境。
2. 从页面可见入口开始，不要直接调用内部 API 伪造状态。
3. 点击真实按钮/链接，填写真实表单，等待页面反馈。
4. 每次页面结构变化后重新观察页面，再继续下一步。
5. 同时关注：
  - URL / 路由是否符合预期。
  - 页面文案和视觉状态是否让用户知道发生了什么。
  - 表单校验是否清晰。
  - 加载、空状态、错误状态是否可恢复。
  - 控制台是否出现错误。
  - 关键网络请求是否成功，失败时 UI 是否正确处理。
6. 对高风险动作停在确认步骤，记录“未执行原因”和用户授权需求。

### 5. 结果判定

每个 Journey 只能使用这些状态：

- `PASS`：实际执行，结果符合预期，并有证据。
- `FAIL`：实际执行，结果不符合预期，并有复现步骤。
- `BLOCKED`：因登录、权限、缺数据、环境不可用或需人工授权无法执行。
- `NOT RUN`：未执行。必须说明原因，不能混同为通过。

---

## 输出格式

最终输出必须包含：

```markdown
## E2E Verification

### Scope
- Target:
- Environment:
- Browser / Viewport:
- User Role:
- Build / Commit:

### Checklist
| ID | User Journey | Status | Evidence | Notes |
|---|---|---|---|---|
| J1 | <用户目标> | PASS/FAIL/BLOCKED/NOT RUN | <截图/URL/日志> | <关键观察> |

### Findings
- [HIGH/MEDIUM/LOW] <问题标题>
  - Expected:
  - Actual:
  - Repro:
  - Evidence:
  - Suggested Fix:

### Coverage Gaps
- <未覆盖路径及原因>

### Recommendation
- <是否可以合并/发布/需要修复后重测>
```

如果没有发现问题，也要明确写：

```text
No E2E issues found in executed journeys. Remaining risk: <未覆盖范围>.
```

---

## 常用 Journey 模板

### 登录/认证

- 访客进入受保护页面会被引导登录。
- 正确账号能登录并回到原目标页。
- 错误密码、空字段、过期会话有清晰提示。
- 刷新页面后登录态保持或按设计失效。
- 退出登录后不能通过返回按钮看到受保护内容。

### 表单/提交

- 用户能从入口找到表单并完成提交。
- 必填、格式、长度、重复提交都有反馈。
- 提交成功后页面给出明确结果，并能继续下一步。
- 提交失败时用户输入不应无故丢失。

### 列表/搜索/筛选

- 空状态、加载状态、有数据状态都可理解。
- 搜索、筛选、排序、分页能组合使用。
- 刷新或复制 URL 后关键查询状态按设计保留。
- 没有结果时提供恢复路径。

### 创建/编辑/删除

- 创建后能在列表或详情页看到新数据。
- 编辑后数据持久化，刷新后仍正确。
- 删除类动作必须有确认；未授权时停在确认前。
- 取消操作不会产生副作用。

### 导航/布局

- 主要入口可发现，面包屑/返回路径合理。
- 深链可直接打开。
- 浏览器返回/前进不破坏状态。
- 桌面和移动视口下关键操作不被遮挡。

---

## 质量标准

好的 E2E 指南看起来应该像一名认真测试人员的操作记录：有目标、有路径、有证据、有判断。坏的指南只会写“测试登录、测试提交、测试页面显示”。那种不行。