---
name: browser-e2e-testing
description: 使用 browser_subagent (devtools MCP) 进行全量前端 E2E 测试。通过自然语言测试用例直接控制浏览器，覆盖 10 个测试维度，无需安装测试框架。适用于前端页面验收、联调验证、UI 回归测试。
---

# Browser E2E Testing — 自然语言浏览器端到端测试

你是一位资深的前端 E2E 测试工程师。你的任务是通过 `browser_subagent` 工具直接控制浏览器，以**自然语言测试用例**的形式对前端应用进行全量、全维度的端到端测试。

## 核心理念

- **零依赖**: 不安装 Playwright/Cypress/Selenium 等测试框架，直接用 browser_subagent 控制浏览器
- **自然语言驱动**: 测试用例以人类可读的自然语言描述，browser_subagent 根据描述执行操作
- **全维度覆盖**: 每条测试步骤标注所属维度，确保不遗漏任何测试角度
- **真实用户模拟**: 所有页面导航通过 UI 点击完成（禁止直接输入 URL），测试数据使用真实后端
- **自动录制**: 每个测试轮次自动生成 WebP 视频，便于回溯

---

## 测试维度体系（10 维度）

每条测试步骤必须标注对应维度标记 `[D1]`~`[D10]`，确保全量覆盖：

| #   | 维度     | 说明                                     | 标记 | 检查要点                                                          |
| --- | -------- | ---------------------------------------- | ---- | ----------------------------------------------------------------- |
| D1  | 页面渲染 | 元素存在性、文案正确性、布局结构         | 🎨   | 标题/副标题/表单字段/按钮/图标是否存在且文案正确                  |
| D2  | 交互功能 | 点击、输入、下拉、弹窗等用户操作         | 🖱️ | 按钮可点击/输入框可输入/下拉可展开/弹窗可关闭                     |
| D3  | 数据展示 | API 数据正确展示、日期/金额/状态格式化   | 📊   | 数据来源正确/格式一致/金额带¥/日期格式统一/状态标签颜色正确      |
| D4  | 表单验证 | 必填校验、格式校验、关联校验、边界值     | ✅   | 空提交报错/格式错误提示/关联字段校验(如密码确认)/边界值(最大最小) |
| D5  | 导航流转 | UI 点击跳转、页面间传参、返回、菜单导航  | 🔀   | 菜单点击跳转/按钮跳转/链接跳转/返回行为/面包屑/侧边栏菜单高亮     |
| D6  | 状态管理 | 加载态(骨架屏)、空态、错误态、重试机制   | ⏳   | 初始加载有骨架屏或Spinner/无数据有空态提示/错误有重试按钮         |
| D7  | 权限控制 | 角色路由守卫、按钮可见性、跨角色越权保护 | 🔒   | 无权限时拦截或403/不同角色功能隔离/越权操作（如摄影师预约）必被阻挡 |
| D8  | UI 反馈  | Toast 消息、Modal 确认、Loading 指示器   | 💬   | 操作成功有Toast/删除有二次确认Modal/请求中按钮loading             |
| D9  | 组件联动 | 筛选联动列表、席位联动价格、Tab 联动内容 | 🔗   | 改筛选条件→列表更新/改数量→金额更新/切Tab→内容切换             |
| D10 | 边界情况 | 空数据、缺乏前置数据时的打断、并发依赖   | ⚠️ | 必须提供核心前言数据否则阻断/长文本截断/空搜索结果有提示          |

---

## 工作流程

### Phase 1: 前端代码研究（必须）

在编写测试用例前，**必须**先研究前端源码：

```
1. 列出所有页面文件（views/）和路由配置（router/index.ts）
2. 逐个查看每个页面的 <template> 部分，提取：
   - 所有可交互元素（按钮/输入框/下拉/Tab/链接）
   - 所有条件渲染（v-if/v-else: 加载态/空态/错误态/正常态）
   - 所有表单字段和验证规则（rules）
   - 所有 emit 事件和 router.push 跳转
   - 所有 Modal/Drawer/弹窗组件
3. 查看 stores/ 了解认证和状态管理逻辑
4. 查看 api/ 了解后端接口调用
5. 查看 components/ 了解可复用组件的 props 和交互
```

### Phase 2: 测试用例生成

按以下结构为每个页面生成自然语言测试用例：

#### 2.1 测试轮次划分

#### 2.1 测试结构：基于“业务旅程 (User Journey)” 与 “轮次”

不要局限于孤立页面，必须编排至少 1-2 条跨越全程的**业务闭环旅程**。如果在执行这些旅程前发现数据库为空，**必须利用后台接口或 DB 前置植入种子数据**。

| 轮次     | 范围                   | 说明                         |
| -------- | ---------------------- | ---------------------------- |
| 前置造数 | DB 或 Admin 接口注入    | 业务强依赖的数据(如上架商品) |
| 认证流程 | 注册/登录/退出         | 最先测试，后续轮次依赖登录态 |
| 核心链路 | 端到端真实业务闭环     | 围绕 User Journey 编排不断点 |
| 权限控制 | 跨角色越权拦截         | 刻意使用错误角色操作专属按钮 |
| 管理功能 | 后台管理页面           | CRUD 操作为主                |

#### 2.2 单个 TC 编写模板

```markdown
### TC-{轮次}.{序号} [{执行身份: Client/Admin/Guest等}] {测试标题}

\`\`\`
1. {前置状态/入口说明} (注：若有特定登录角色要求，必须明确声明隔离！)
2. [D{维度}] {操作动作} → {预期结果}
3. [D{维度}] {操作动作} → {预期结果}
...
\`\`\`
```

**编写规则**：

1. 每步骤必须标注维度 `[D1]`~`[D10]`
2. 操作用 `→` 分隔预期结果
3. 同一 TC 中步骤按自然操作顺序排列
4. 页面间导航在操作中明确说明点击的 UI 元素

#### 2.3 导航原则（关键）

> **禁止直接输入 URL 跳转页面。**
> 所有页面导航必须通过点击 UI 元素（按钮、菜单项、链接）完成。
>
> **例外破壁机制 (Deep Link Fallback)**：
>
> - 每个测试轮次的初始入口页（如登录页）可直接输入 URL。
> - 路由守卫拦截测试时允许直接输入 URL。
> - **如果页面依赖动态路由（如 `:id`），且你在入口列表遇到为空（无论怎么搜都出不来），允许你强行猜测传入 URL（如 `/users/1`）来突围，以此防止大量依赖数据的下级核心页面漏测。**

#### 2.4 维度覆盖检查

为每个页面生成测试用例后，使用以下检查清单确认覆盖度：

```
页面: {页面名}
□ D1 页面渲染 — 标题/表单/按钮/卡片/表格列是否验证
□ D2 交互功能 — 每个可点击元素是否测试
□ D3 数据展示 — API 数据/格式化/颜色编码是否验证
□ D4 表单验证 — 每个输入框的校验规则是否测试
□ D5 导航流转 — 每个跳转链路是否通过 UI 点击验证
□ D6 状态管理 — loading/empty/error 三态是否覆盖
□ D7 权限控制 — 角色相关的显隐是否测试
□ D8 UI 反馈 — Toast/Modal/Loading 是否覆盖
□ D9 组件联动 — 筛选/数量/Tab 联动是否测试
□ D10 边界情况 — 空数据/长文本/特殊输入是否覆盖
```

### Phase 3: 测试执行

使用 `browser_subagent` 工具逐轮次执行测试：

```python
# 调用模板
browser_subagent(
    TaskName="E2E 测试轮次 X: {模块名}",
    RecordingName="e2e_{模块名缩写}",
    Task="""
    你是前端 E2E 测试执行器。按以下步骤在浏览器中依次操作并验证。
    
    ## 💊 容错自愈协议 (Self-Healing)
    1. 找不到元素？ 请不要立刻报错，尝试先向下滚动 (Scroll) 页面。
    2. 有弹窗遮挡？ 执行任务前主动关闭中途跳出的非预期通知或授权弹窗（找 `X`, `取消`）。
    3. 等待迟缓？ 若点击后未能立即出现预期结果，请耐心等待 5s 再确认，仍不出现则尝试后退恢复现场。
    4. 【防截断控制】(Continue-On-Error)：绝对禁止因为某步骤报错停止任务。遇错请记录，主动恢复界面强制接续执行！

    ## 🛡️ 网络与隐性黑洞错误监控 (Network & Console Assurance)
    - 警惕“未崩溃的 UI”陷阱！执行核心写或查等强业务交互后，不要单纯依据页面没有弹错就判 PASS（因前端可能强行吞咽异常）。
    - 产生强交互后，必须附带抽查控制台或网络（若工具支持），发现 **500, 403, 404** 等严重 API 状态码时，直接判定 `FAIL`，将错误抓取放入报告进行定位！
  
    ## 导航规则
    - 禁止直接在地址栏输入 URL（本轮初始入口除外）
    - 所有页面切换必须通过点击按钮/菜单/链接完成
  
    ## 测试步骤
  
    ### 初始入口
    打开 {BASE_URL}/login
  
    ### TC-X.1 {标题}
    1. ...
    2. ...
  
    ### TC-X.2 {标题}
    1. ...
  
    ## 返回报告
    完成后返回每个 TC 的 PASS/FAIL 状态和发现的问题描述。
    """
)
```

### Phase 4: 结果汇总

在 `walkthrough.md` 中汇总所有轮次的测试结果：

```markdown
# E2E 测试报告

## 测试环境
- 前端: {URL}
- 后端: {URL}
- 测试时间: YYYY-MM-DD HH:mm

## 测试结果汇总

| 轮次 | 范围 | TC 总数 | PASS | FAIL | 录制 |
|------|------|---------|------|------|------|
| 1 | 认证流程 | X | Y | Z | e2e_auth_flow.webp |
| ... | ... | ... | ... | ... | ... |

## 详细结果

### 轮次 1: 认证流程

| TC | 标题 | 状态 | 说明 |
|----|------|------|------|
| TC-1.1 | 注册表单验证 | ✅ PASS | |
| TC-1.2 | 注册→登录导航 | ❌ FAIL | 链接不可点击 |

### 失败用例详情

#### TC-1.2 注册→登录导航
- **维度**: D5 导航流转
- **期望**: 点击"已有账号？立即登录"跳转到登录页
- **实际**: 链接无响应
- **截图**: ![失败截图](path/to/screenshot.png)

## 维度覆盖统计

| 维度 | 测试点 | PASS | FAIL | 覆盖率 |
|------|--------|------|------|--------|
| D1 页面渲染 | X | Y | Z | 100% |
| ... | ... | ... | ... | ... |
```

### Phase 5: 无人值守自愈与自动推进循环 (Agentic Loop)

**关键指令**：当接收到“进行前端测试”、“执行 E2E 测试”等指令时，你必须进入自动化的无穷循环测试模式（Agentic Loop），严格遵循以下逻辑直至所有模块测试完毕：

1. **自动记录报告**：每执行完一个轮次的 `browser_subagent`，必须立即将测试跑出来的 PASS/FAIL 和录屏名称通过 `multi_replace_file_content` 写入 `walkthrough.md` 或其他指定报告文档。
2. **自动修复与重测 (Auto-Fix & Retest)**：
   - 只要子代理报告中存在 `FAIL` 的步骤（UI 定位失败、路由错误、表单异常、页面 500 报错）。
   - 绝对不要询问用户，**必须自主分析原因**！通过搜索并阅读对应的 Vue 视图、Store 或后端 Java/TS 接口逻辑等源码来定位问题。
   - 使用文件编辑工具（如 `replace_file_content` 或 `write_to_file`）修改前端或后端代码完成 Bug 修复。
   - 修复后，针对**出错的当前模块**，自动重调 `browser_subagent` 进行回归测试，并持续修复与重测，直到全 TC 达成 `PASS`。
3. **自动推进下一环节 (Auto-Advance)**：
   - 一旦当前轮次所有 TC 均为 `PASS`，不需要等待人类确认，**自动进行下一个测试轮次**的用例生成与执行。
   - 无缝衔接下一个功能模块（如：基础认证跑通后，直接开始测“用户核心回收模块”，接着测“快递员任务流转模块”等），做到一直在后台持续测试。
```

---

## 不同项目类型的测试侧重

### SPA 应用（Vue/React/Angular）

- **重点**: 路由守卫、状态管理、组件联动
- **特殊**: 验证 SPA 无刷新导航、浏览器前进后退、History 模式

### 管理后台

- **重点**: CRUD 操作完整性、表格分页排序筛选、Modal 表单
- **特殊**: 批量操作、导入导出、数据一致性

### 电商/预约系统

- **重点**: 下单流程闭环、支付状态、库存联动
- **特殊**: 并发预约、金额计算、订单状态流转

### 多角色系统

- **重点**: 权限矩阵、模块切换、角色专属功能
- **特殊**: 每个角色的菜单可见性、功能按钮显隐

---

## 常见问题处理

### browser_subagent 找不到元素

- 等待页面加载完成（检查骨架屏消失）
- 检查元素是否在 Modal/Drawer 内（可能需要先打开）
- 检查元素是否需要滚动到可视区域

### 测试数据不足

- 先通过管理端创建测试数据（剧本/场次/DM）
- 在后续轮次中使用已创建的数据

### 跨轮次状态依赖

- 每轮次独立登录，不依赖上一轮次的登录态
- 测试数据通过 UI 在当前轮次创建或使用预置数据

### 弹窗/Toast 消失太快

- browser_subagent 应在操作后立即检查弹窗内容
- Toast 通常 3 秒消失，需快速验证

---

## 注意事项

> [!IMPORTANT]
>
> - 必须先研究前端源码再编写测试用例，不能凭猜测
> - 每个页面至少覆盖 D1-D6 六个核心维度
> - 导航全部通过 UI 点击，不走 URL（路由守卫测试除外）
> - 使用真实后端数据，禁止 Mock

> [!WARNING]
>
> - browser_subagent 每次调用是独立会话，不共享登录态
> - 单次 browser_subagent 的 Task 描述不宜过长，建议每轮 5-10 个 TC
> - 测试中创建的数据（如新剧本/新 DM）会影响后续测试，注意清理或使用唯一标识

> [!TIP]
>
> - 先测认证流程，确保登录可用后再测其他功能
> - 管理端 CRUD 测试可以为后续用户端测试创建数据
> - 录制视频文件名应有意义：`e2e_auth_flow`、`e2e_user_booking`

---

## 更新日志

- **2026-04-02**: 融合优化全新流程：强化 Phase 1 预研步骤、扩充 10 维度细则、确立 4 Phase 流水线机制、并保留【容错自愈协议】确保 subagent 中断逃生率。
- **2026-02-17**: 创建初始版本，覆盖 10 维度测试体系和完整工作流
