@pzy560117/codex-harness 0.1.4 → 0.1.6

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/browser-e2e-testing/SKILL.md

@@ -0,0 +1,305 @@
+---
+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 维度测试体系和完整工作流