do-test

驱动工程中所有测试场景的执行：API 基本功能验证（委托 /api-test）+ 场景用例验证（test/cases/），汇总为统一测试报告。

定位：测试编排入口。本身不做具体探测逻辑，API 部分完全委托 /api-test，场景部分按用例定义执行。

触发条件：用户要求运行全部测试、执行测试场景、回归验证，或直接输入 /do-test。

执行方式：必须串行执行，禁止并行。 同一时刻只允许一个本 skill 实例；每个用例通过子 agent 执行，严格逐条串行——上一个用例的子 agent 出结论后，才可为下一个用例启动子 agent。禁止并行启动多个实例、并行启动多个子 agent 同时执行不同用例，也禁止与 /aibug、/aicase 并发运行。唯一的并发例外：API 阶段委托 /api-test 时固定按 --bucket=4 发请求（同一条 Bash 命令内 4 条一桶并等齐），桶与桶之间仍然串行。

零、参数处理

如果用户传入 -h 或 --help，不执行任何操作，直接把下面的帮助信息原样输出在本次回复正文里后结束（斜杠命令把 SKILL.md 注入我的上下文不等于已展示给用户，正文里只回一句"已输出"就是没输出）。-h 与其它参数或说明文字同时出现时，一律只出帮助、忽略其余参数：本轮不猜附加要求，需要同时执行就把 -h 去掉分两次调用：

用法: /do-test [选项]

选项（通过命令行传入的参数直接使用，不再交互询问）
  --task=<任务>     只执行指定单项任务：api（API 基本功能验证）或
                    cases（场景用例验证）；可多次传入；不传则默认全部执行
  --case=<名称>     只执行指定场景用例（文件名或场景名，可多次传入；
                    隐含 --task=cases）
  --bucket=N        透传给 /api-test 的 HTTP 请求桶并发大小（整数 1-4）。
                    本 skill 默认按 --bucket=4 调用（4 条一桶、桶间串行）；
                    显式传入时以用户值为准，1 = 严格逐条
  --base-url=URL    透传给 /api-test 的后端 API 基础地址（不传由 /api-test 自动探测）
  --no-fix          只检查并输出报告，不修改任何代码
  -h, --help        显示本帮助（出现即忽略其它参数，只出帮助）

工作流程
  1. 前置检查：确认工程结构（src/ 存在）、按任务范围确认 test/cases/ 用例
  2. API 验证：调用 /api-test skill（固定 --bucket=4 桶并发探测，桶间串行），全端
     扫描 API 并逐个验证 HTTP 200、检查业务合理性，产出 test/api/url-list.md 与
     test/api/test-result.md
  3. 场景验证：逐个委托子 agent 执行 test/cases/ 下的用例文件（严格串行），
     按步骤执行并判定结果；case-summary.md 存在时按其优先级
     （P0→P1→P2）排序执行，否则默认顺序
  4. 汇总报告：按实际执行的任务合并结果写入 test/test-report.md，输出中文摘要

产物
  test/api/url-list.md     API URL 清单（由 /api-test 产出）
  test/api/test-result.md  API 验证与修复结果（由 /api-test 产出）
  test/test-report.md      总测试报告（按执行范围：API 结果 + 场景用例结果）

示例
  /do-test                     默认全部执行：API 验证 + 全部场景用例
  /do-test --task=api          只执行 API 基本功能验证
  /do-test --task=cases        只执行场景用例验证
  /do-test --case=下单流程     只执行指定场景
  /do-test --bucket=1          API 阶段改为严格逐条（默认按 4 条一桶并发）
  /do-test --no-fix            只出报告，不改代码
  /do-test -h                  显示本帮助

一、前置检查

0. 确定任务范围：解析 --task（可多个：api / cases）；传入 --case 时隐含包含 cases；未传 --task 与 --case 时默认 api + cases 全部执行。取值非法则报错并输出帮助后终止。同时解析 --bucket（整数 1-4，未传按默认 4 透传给 /api-test）。
1. 确认当前工作目录存在 src/（工程根）；不存在则报告并终止。
2. 任务含 cases 时，检查 test/cases/ 目录：
   • 存在且有用例文件 → 记录待执行清单。主循环禁止读取用例文件全文：case-summary.md 存在时只从其中提取 编号/名称/优先级；不存在时只 ls 文件名列表。用例内容由执行该用例的子 agent 自行读取。
   • 不存在或为空 → 提示用户"暂无场景用例"，跳过 cases 任务。
3. 若 test/test-report.md 已存在，只 grep 提取上一轮汇总行（如 grep -E "^结果：|^## 三、结论" test/test-report.md），供本轮报告标注"回归对比"；禁止整份读取报告。

二、API 基本功能验证

仅当任务范围含 api 时执行：

1. 用 Skill 工具调用 api-test skill 执行全端 API 验证；固定附加 --bucket=4（4 条一桶并发、桶间串行），并透传本命令收到的 --no-fix、用户提供的 --base-url 等参数。用户在 /do-test 里显式给出 --bucket=N 时以用户值为准（仍受 1-4 上限约束，超出由 /api-test 报错终止）。桶并发下的时长只作初筛，>200ms 与超时条目由 /api-test 按 --bucket=1 串行复测后定级，本 skill 不重复测量。
2. /api-test 完成后确认产物存在：test/api/url-list.md、test/api/test-result.md。
3. 从 test/api/test-result.md 只 grep 提取汇总数字（通过 / 修复 / 未解决 / 跳过条数）与未解决清单行，供第四步引用；禁止整份读取该文件。

三、场景用例验证

仅当任务范围含 cases 时执行。

执行顺序：test/cases/case-summary.md 存在时，按其中定义的优先级排序执行（P0 → P1 → P2，同优先级按用例编号升序）；摘要中未收录的用例排在最后（按编号升序）。不存在 case-summary.md 时按默认顺序执行（文件名/编号升序）。

3.1 用例格式

test/cases/ 下每个 .md 或 .yaml 文件是一个测试场景（标准用例由 /new-test-case 生成，命名 TEST-CASE-{4位编号}.md）。case-summary.md 是摘要索引文件（由 /new-test-case 维护），不作为用例执行。Markdown 用例为专业模板结构：

• 元信息：用例编号、测试类型（API / UI(Playwright) / 混合）、优先级、创建时间
• 前置条件：执行前必须成立的状态
• 测试数据：数据依赖及准备方式
• 测试步骤：步骤表，每步含 类型 / 操作 / 输入参数 / 预期结果。类型三种：
  • API：接口请求（方法 + 路径 + 参数）
  • UI：Playwright 页面操作（goto/fill/click + 选择器 + 断言）
  • 人工：需人工执行的操作（附操作指引）
• 结果验证：全部步骤完成后的整体断言（数据状态、跨步骤一致性）
• 善后清理：执行后的数据还原/清理操作

## 测试步骤

| # | 类型 | 操作 | 输入/参数 | 预期结果 |
|---|------|------|-----------|----------|
| 1 | API | `GET /api/mall/products/1` | - | HTTP 200，且 price > 0 |
| 2 | UI | Playwright: goto `/login` → fill `#username` → click `button[type=submit]` | 测试账号 | 跳转至 `/home` |

兼容旧格式用例（"测试步骤"为编号列表 + "预期结果"列表），按原样执行。YAML 用例字段：name、preconditions、steps、expected。

结构不完整（缺步骤或预期结果）的用例标记 无效用例，跳过并在报告中列出。

3.2 执行规则

执行方式（必做）：每个用例单独委托一个子智能体（Agent 工具，subagent_type 用 general-purpose）执行，主循环只传入用例文件路径与相关上下文，接收其返回的用例结论；严格逐条串行，同一时刻最多只有一个子智能体在运行，上一个用例出结论后才启动下一个，禁止同时派出多个子智能体并行执行。

上下文控制（必做）：

1. 干净上下文（防串味）：子智能体 prompt 只包含——当前用例文件路径（由它自己读取）、base url 与 token（如已有）、--no-fix 等执行约束；禁止携带之前任何用例的内容、结论、失败现象或已定位原因，主循环也不复用上一个用例的判断。

2. 固定返回格式（≤4 行），主循环只记一行台账 TEST-CASE-<编号> → 通过/失败/阻塞/需人工（一句话原因），不追问细节：

   结论: 通过 | 失败 | 阻塞 | 需人工
   失败/阻塞步骤: <# 或 ->
   说明: <一句话原因或待人工操作指引>
   修改文件: <最小化修复时列出；否则 ->

3. 定期压缩：每执行完 5 个用例，或感知上下文占用约 60% 时，执行一次 /compact，明确要求保留：任务范围与 base url/token、台账表、当前未完成用例的状态。
4. 子智能体返回的失败证据（响应片段/截图说明）一律截断至 15 行内，超长不重试、不追问。

对每个用例（传入 --case 时只执行匹配项），以下步骤在子智能体内执行：

1. 检查前置条件与测试数据：能用 API/数据库查询验证的先验证；不满足时尝试构造（如先调登录接口、经用户同意造最小测试数据）；无法满足则标记 阻塞 并记录原因。
2. 逐步执行，按步骤类型：
   • API → curl 实际请求（复用 /api-test 阶段的 base url 与 token）。
   • UI → 工程支持 Playwright（存在 playwright 依赖/配置）时，将 UI 步骤转写为临时 spec（test/.tmp-case-<编号>.spec.ts，headed=false）运行后删除；不支持时标记 需人工 并给出 Playwright 操作步骤指引。
   • 人工 → 标记 需人工，输出操作指引与判定标准。
3. 逐步判定：对照步骤表中"预期结果"判定每步 通过/失败；失败时保留实际响应/截图说明（截断 50 行内）。
4. 结果验证：全部步骤执行后，逐条核对"结果验证"整体断言（需要时补发查询请求/数据库查询取证）；任一断言不成立则该用例判 失败。
5. 善后清理：执行用例中定义的清理步骤（同样逐步判定），清理失败在报告中单列提醒。
6. 用例结论：全部步骤与结果验证通过 → 通过；任一失败 → 失败；存在阻塞 → 阻塞；存在需人工步骤且其余全通过 → 部分通过（待人工）。
7. 传入 --no-fix 时只判定不修复；否则对可明确定位的失败（如接口 404、断言字段名错误、选择器失效），按最小化原则修复后重跑该用例，最多一轮。

四、汇总报告

将总结果写入 test/test-report.md（只写实际执行的任务对应章节，未执行的任务注明"本轮未执行"）：

# 测试报告

测试时间：<YYYY-MM-DD HH:mm>
执行范围：API 验证 + 场景用例 N 个

## 一、API 基本功能验证（/api-test）

- 清单：test/api/url-list.md（M 条）；明细：test/api/test-result.md
- 结果：通过 X / 修复 Y / 未解决 Z / 跳过 W
- 未解决项：<列表，含原因>

## 二、场景用例（test/cases/）

| # | 场景 | 文件 | 结论 | 说明 |
|---|------|------|------|------|
| 1 | 下单流程 | order-flow.md | 通过 | - |
| 2 | 退款流程 | refund.md | 失败 | 步骤 3 实际返回 500（已修复后复验通过 → 通过） |
| 3 | 后台审核 | admin-audit.md | 部分通过（待人工） | 步骤 2 需页面操作 |

结果：通过 a / 失败 b / 阻塞 c / 部分通过 d / 无效用例 e

## 三、结论与遗留问题

- 总体结论：<全部通过 / 存在未解决问题>
- 遗留问题清单：<未解决 API + 失败场景 + 需人工项>
- 修改文件清单：<本轮修复改动的文件>

同时向用户输出上述报告的中文摘要（总体结论 + 失败/阻塞项清单）。

五、注意事项

• /api-test 的交互确认规则（写操作逐条询问、凭据不落盘）在本 skill 中同样有效；透传用户已给出的确认，不重复询问。API 阶段固定以 --bucket=4 调用（写操作与修复后复验按 /api-test 规则仍不进桶）。
• 探测使用的账号、token 只出现在请求中，不写入文件、不在报告中明文输出。
• 造测试数据、执行写操作前必须经用户确认，并说明作用于当前后端环境。
• 工程根目录 v0/ 是只读产品设计文档，禁止修改。
• 必须串行执行：本 skill 全程单实例、每个用例委托子 agent 逐条串行执行，禁止并行（多实例、多个子 agent 同时执行多用例、与 /aibug 或 /aicase 并发均不允许）；用户要求并行时应明确拒绝并说明该约束。口径澄清：这里禁止的是"用例级/实例级并行"，API 阶段 /api-test 的桶内 HTTP 并发（--bucket=4，桶间仍串行）是允许的提速方式，不视为并行违规。
• 本 skill 只修改代码文件与 test/ 下的产物文件，不执行 git commit，由用户决定是否提交。