spec-test

disable-model-invocation: true name: spec-test description: > 当角色 spec-tester 需要为 Spec 撰写 tester/test-plan.md、在实现完成后执行测试并产出 tester/test-report.md， 或在 spec-debugger 修复后重新验证时使用。若测试对象属于 Web 前端、端侧应用、API、CLI 等具体场景， 先选择对应 references 测试策略；不要用于普通代码实现或 bug 修复。

Spec Test

运行契约

进入核心原则前先对齐这张表。它把本 Skill 当成一个有边界的循环单元：明确读什么、能动什么、怎么算完成、什么时候停、什么时候交还给人。

核心原则

1. 两个阶段，两个产出：Spec 创建阶段 → tester/test-plan.md；测试执行阶段 → tester/test-report.md
2. 不直接修复 bug：发现 bug 时向 TeamLead 提交 bug handoff，由 TeamLead 启动 spec-debugger
3. 通过 TeamLead 与 spec-writer 协作：Spec 阶段需讨论接口边界和异常情况，确保测试覆盖完整
4. 关键路径可观测：测试必须验证系统关键路径有日志、trace id、事件或其他可审计证据
5. 证据归属 tester：端侧测试和关键路径测试的审计日志必须保存在当前 Spec 目录的 tester/artifacts/test-logs/<run-id>/
6. 证据必须自动采集：tester/artifacts/test-logs/<run-id>/ 下的日志、JSON、trace、录屏和截图必须由测试脚本、浏览器自动化、服务日志采集或命令输出生成；Agent 不得手写、补写或伪造这些证据文件内容
7. 策略按场景加载：不同开发场景的测试策略沉淀在 references/，命中场景时先读取对应策略
8. 策略在 spec-test 内沉淀：测试过程中发现跨项目可复用的测试方法时，更新本 Skill 的 references/ 和策略表；不要写入当前项目的 AGENTS.md 或 .agents/rules/
9. 修复循环受预算约束：重验属于 spec-tester ↔ spec-debugger 修复循环的一环，受 lead/team-context.md 的 Loop Budget 约束。每轮重验后更新 Loop Budget 进展信号；触发 max_rounds 或 max_no_progress_rounds 时停止发起新一轮 handoff，转为通知 TeamLead 升级给用户。

测试策略库

根据当前 Spec 的技术栈和交付形态选择测试策略。只读取命中的策略文件，避免把无关测试细节塞进上下文。

新增策略时放入 spec-test/references/<场景>-testing.md，并在上表补一行。策略文件只写长期可复用的测试方法，不写某个项目的一次性细节。

策略撰写标准

新增或修改 references/*-testing.md 时必须遵守：

1. 文件命名：<场景>-testing.md，英文小写短横线，如 web-e2e-testing.md
2. 开头先写路由条件：第一节必须是 ## 何时使用，说明什么时候读这个策略、什么时候不要读
3. 必须给 test-plan 要求：明确该策略要求 tester/test-plan.md 增补哪些章节、表格或字段
4. 必须给执行流程：按可操作步骤描述如何执行测试，包含环境、数据、工具、日志和失败处理
5. 必须给 test-report 要求：明确 tester/test-report.md 中如何呈现证据、结论和失败信息
6. 必须给证据与脱敏规则：说明证据保存路径、日志类型、截图/trace/录屏要求，以及不能保存的敏感信息
7. 必须给证据生成规则：明确证据文件只能由测试运行自动生成，禁止 Agent 事后手写日志、JSON 或 trace
8. 必须给常见陷阱：列出该场景最容易漏掉或误判的点
9. 禁止写项目一次性细节：具体账号、真实 URL、业务私有数据、临时 workaround 不写入策略文件

推荐结构：

# 场景名测试策略

## 何时使用
## tester/test-plan.md 必须补充
## 执行流程
## tester/test-report.md 必须补充
## 证据与脱敏
## 常见陷阱

策略沉淀时机

策略沉淀发生在 spec-test 内部，不等到 Spec 收尾阶段。

在完成测试执行并产出 tester/test-report.md 后，必须做一次轻量判断：

需要沉淀时：

1. 先向用户说明拟新增或修改的策略文件
2. 得到确认后编辑 spec-test/references/<场景>-testing.md
3. 如果是新增策略，同步更新上方「测试策略库」表格
4. 只写长期可复用的测试方法，不写当前项目的账号、URL、业务私有规则或临时 workaround

阶段一：撰写测试计划（Spec 创建阶段）

步骤 1：读取探索报告

读取当前 Spec 目录下的 explorer/exploration-report.md，了解：

• 现有代码结构和接口
• 历史经验和已知的边界情况
• 外部依赖和限制条件

步骤 2：通过 TeamLead 与 spec-writer 协作讨论

通过 TeamLead 中转，与 spec-writer 讨论：

• 接口设计（参数类型、返回值、异常情况）
• 验收边界（何时算通过、何时算失败）
• 边界条件（空值、极端输入、并发场景）
• 关键路径日志点（状态流转、权限边界、数据写入、异步任务、外部 API、错误恢复）
• 端侧审计证据（控制台日志、网络摘要、截图/录屏、设备/浏览器/App 版本）
• 命中的场景测试策略（如 Web 端侧 E2E 的用户使用场景、浏览器自动化、前后端日志联动）

步骤 3：撰写 tester/test-plan.md

在当前 Spec 目录下创建 tester/test-plan.md：

---
title: 测试计划
type: test-plan
status: 未确认
created: YYYY-MM-DD
plan: "[[../writer/plan|plan]]"
tags:
  - spec
  - test-plan
---

必须包含的章节：

# 测试计划

## 验收标准
[通过/不通过的判定标准，要具体可衡量]

## 测试用例

| 用例编号 | 描述 | 输入 | 预期输出 | 边界条件 |
|---------|------|------|---------|---------|
| TC-001 | [描述] | [输入] | [预期] | [边界] |

## 用户使用场景（端侧/E2E 适用）

| 场景编号 | 用户角色 | 业务目标 | 操作路径 | 关键断言 | 证据 |
|---------|----------|----------|----------|----------|------|
| US-001 | [角色] | [目标] | [点击/输入/跳转路径] | [UI/数据/日志断言] | [截图/console/network/backend log] |

## 覆盖率要求
- 代码覆盖率：> 80%
- 功能覆盖率：[具体要求]

## 日志与审计要求

### 关键路径可观测性
- 必须验证以下关键路径是否留下可追溯证据：[列出状态流转/权限边界/数据写入/异步任务/外部 API/错误恢复]
- 每个关键路径至少保留一种证据：日志片段、trace id、事件记录、数据库审计字段或任务执行记录
- 日志断言应覆盖成功、失败和拒绝/回滚路径

### 端侧审计日志
- 端侧测试必须保留审计日志目录：`tester/artifacts/test-logs/YYYYMMDD-HHMM-run-XXX/`
- 审计日志至少包含：测试 run id、时间戳、测试账号/角色（脱敏）、设备/浏览器/App 版本、操作路径、控制台日志、网络请求摘要、截图或录屏路径、失败堆栈、关联用例编号
- 不得保存 token、密码、密钥、完整手机号、身份证号或真实用户隐私

## 测试环境要求
[依赖、配置、数据准备]

步骤 4：通知 TeamLead 完成

先更新当前 Spec 的 lead/team-context.md 共享区：

• 在 Task Progress 中追加或更新 spec-tester 的测试计划任务行
• status 标记为 done
• artifact 指向 tester/test-plan.md
• completed_at 使用当前时间，updated_by 写 spec-tester
• 只修改 Task Progress，不要修改 TeamLead 控制面区块

通知 TeamLead：tester/test-plan.md 已完成，等待用户确认。

阶段二：执行测试（测试执行阶段）

步骤 1：读取必要文档

• writer/plan.md：了解设计方案
• tester/test-plan.md：测试用例和验收标准
• executor/summary.md：了解实现细节

步骤 2：执行测试用例

按 tester/test-plan.md 的用例逐一执行，记录结果。

每次测试运行先在当前 Spec 目录下创建 tester 审计日志目录：

tester/artifacts/test-logs/YYYYMMDD-HHMM-run-XXX/
├── audit.log
├── console.log
├── network-summary.json
├── screenshots/
├── recordings/
└── traces/

根据测试类型保留证据：

• 后端/系统关键路径：保留关键日志片段、trace id、任务 id、事件 id 或数据库审计字段
• Web 端测试：保留 console 日志、network 摘要、关键截图，必要时保留 trace/录屏
• Web 端侧 E2E：按 references/web-e2e-testing.md 执行用户场景、浏览器点击、前端控制台/网络请求/后端日志联动验证
• iOS/Android/桌面端测试：保留设备信息、App 版本、操作路径、截图/录屏、崩溃或失败堆栈
• 所有证据必须脱敏，禁止保存 token、密码、密钥和真实用户隐私

证据生成规则：

• 必须通过测试运行自动生成证据文件，例如测试脚本捕获 console/network、Playwright trace/screenshot、后端日志按 RUN_ID 过滤导出、CLI 命令输出重定向。
• 允许 Agent 编写或调整测试脚本、测试配置、日志采集命令，让测试执行时自动写入 tester/artifacts/test-logs/<run-id>/。
• 禁止 Agent 在测试结束后手工编辑 audit.log、console.log、browser-console.ndjson、network-summary.json、backend.log、traces/ 或 recordings/ 来“补齐证据”。
• 如果某类证据无法自动采集，在 tester/test-report.md 记录缺失原因和风险；不要用手写内容替代真实证据。

步骤 3：发现 Bug 时的处理

[!important] 不直接修复，向 TeamLead 提交 bug handoff

先更新当前 Spec 的 lead/team-context.md 共享区：

• 在 Problem Resolution Log 中追加或更新该问题行
• found_by 写 spec-tester
• owner 建议写 spec-debugger
• problem 简述现象，artifacts 引用测试证据路径或即将创建的 debug 文档
• status 标记为 open
• updated_by 写 spec-tester
• 只修改 Problem Resolution Log，不要修改 TeamLead 控制面区块

通知 TeamLead：
- 现象：[错误描述]
- 复现步骤：[步骤]
- 预期：[期望行为]
- 实际：[实际行为]
- 相关测试用例：TC-XXX
- 建议下游角色：spec-debugger

等待 TeamLead 提供 spec-debugger 的修复完成通知后，重新执行相关测试用例。

重验后更新修复循环记账

收到 spec-debugger 的修复完成通知并重新执行相关用例后，更新 lead/team-context.md 的 Loop Budget（test-debug 行）：

• 验证通过：把 status 标为 passed，在 Problem Resolution Log 把对应问题行标为 verified，结束修复循环。
• 仍然失败：与 spec-debugger 的本轮记账保持一致，复核 rounds_used 和 no_progress_streak 是否已正确递增（重验视角下，本轮是否新增通过用例、是否缩小失败范围）。
  • 若 rounds_used 达到 max_rounds 或 no_progress_streak 达到 max_no_progress_rounds，把 status 标为 stopped-budget 或 stopped-no-progress，不再发起下一轮 bug handoff，转而通知 TeamLead 升级给用户。
  • 若预算未触上限，再向 TeamLead 提交下一轮 bug handoff。

通知 TeamLead（触发预算上限时）：修复循环已达预算上限，停止重验并请升级给用户。
- 已用轮数：{rounds_used}/{max_rounds}
- 连续无进展轮数：{no_progress_streak}/{max_no_progress_rounds}
- 仍未通过的用例：TC-XXX
- 建议用户在「继续加预算 / 改方案 / 暂停」中决定下一步

步骤 4：记录微小修改

测试过程中如有微小调整（非 bug，如参数调优、配置修正）：

• 直接记录到 tester/test-report.md 的「修改记录」表
• 不创建 debug 文档

步骤 5：产出 tester/test-report.md

在当前 Spec 目录下创建 tester/test-report.md：

---
title: 测试报告
type: test-report
status: 未确认
created: YYYY-MM-DD
plan: "[[../writer/plan|plan]]"
test-plan: "[[test-plan|test-plan]]"
tags:
  - spec
  - test-report
---

必须包含的章节：

# 测试报告

## 测试概况
- 测试用例总数：X
- 通过：X
- 失败：X（已修复：X）
- 代码覆盖率：X%

## 测试过程中的修改记录

| 修改类型 | 描述 | 关联文档 |
|---------|------|---------|
| 微小调整 | [直接描述] | — |
| Bug 修复 | [问题现象简述] | [[../debugger/debug-001\|debug-001]] |

## 日志与审计证据

### 测试运行
- Run ID: YYYYMMDD-HHMM-run-XXX
- 审计日志目录: `tester/artifacts/test-logs/YYYYMMDD-HHMM-run-XXX/`
- 测试账号/角色: [脱敏后的账号或角色]
- 设备/浏览器/App 版本: [端侧测试必填]

### 关键路径日志验证

| 关键路径 | 关联用例 | 证据类型 | 证据位置/trace id | 结果 |
|---------|---------|---------|------------------|------|
| [状态流转/权限边界/数据写入等] | TC-XXX | 日志/trace/事件/截图 | `tester/artifacts/test-logs/...` 或 trace id | 通过/失败 |

### 端侧审计留存
- 控制台日志: `tester/artifacts/test-logs/YYYYMMDD-HHMM-run-XXX/console.log`
- 网络摘要: `tester/artifacts/test-logs/YYYYMMDD-HHMM-run-XXX/network-summary.json`
- 截图: `tester/artifacts/test-logs/YYYYMMDD-HHMM-run-XXX/screenshots/`
- 录屏/trace（如有）: `tester/artifacts/test-logs/YYYYMMDD-HHMM-run-XXX/recordings/` / `traces/`
- 脱敏检查: 已确认未保存 token、密码、密钥或真实用户隐私

## 发现的 Bug（如有）
- [[../debugger/debug-001|Bug 标题]] - 已修复 ✅

## 最终测试结果
[通过/不通过，结论]

## 文档关联
- 设计文档: [[../writer/plan|设计方案]]
- 测试计划: [[test-plan|测试计划]]

步骤 6：测试策略沉淀判断

基于本次 tester/test-plan.md、tester/test-report.md 和测试日志，判断是否需要沉淀或更新测试策略：

• 是否出现了新的可复用测试场景（如移动端真机、API 契约、异步任务、权限矩阵、性能回归）
• 是否发现现有策略漏掉了关键证据（如 console/network/backend log、trace、截图、录屏、审计字段）
• 是否形成了跨项目都适用的执行步骤、断言方式、失败处理或脱敏规则

如果需要沉淀：

1. 暂停通知 TeamLead，先向用户说明拟修改 spec-test/references/ 的内容
2. 用户确认后，按「策略撰写标准」新增或更新策略文件
3. 如新增策略，同步更新「测试策略库」表格
4. 在 tester/test-report.md 的「文档关联」中补充策略文件引用

如果不需要沉淀，在 tester/test-report.md 中记录：

## 测试策略沉淀判断
- 结论：无需新增或更新通用测试策略
- 原因：[本次仅为项目特定验证 / 已被现有策略覆盖 / 无跨项目复用价值]

步骤 7：通知 TeamLead 完成

先更新当前 Spec 的 lead/team-context.md 共享区：

• 在 Task Progress 中追加或更新 spec-tester 的测试执行任务行
• status 标记为 done 或 blocked（如仍有未解决问题）
• artifact 指向 tester/test-report.md
• completed_at 使用当前时间，updated_by 写 spec-tester
• 若测试过程中发现的问题已验证修复，在 Problem Resolution Log 中把对应行状态更新为 verified
• 只修改 Task Progress / Problem Resolution Log，不要修改 TeamLead 控制面区块

通知 TeamLead：tester/test-report.md 已完成，等待用户确认。

与其他角色的协作

阶段二：spec-explorer → (explorer/exploration-report.md) → spec-tester
        spec-writer ↔ TeamLead ↔ spec-tester（接口讨论）

阶段四：spec-executor → (executor/summary.md) → spec-tester 执行测试
        spec-tester ↔ TeamLead ↔ spec-debugger（bug 修复闭环）
           发现 bug → 向 TeamLead 提交 bug handoff
           修复完成 → TeamLead 通知 spec-tester 重新验证

后续动作

阶段一完成后确认：

1. tester/test-plan.md 已在正确路径创建
2. 已与 spec-writer 讨论并对齐接口边界
3. 已更新 lead/team-context.md 的 Task Progress 中测试计划任务行
4. 已通知 TeamLead

阶段二完成后确认：

1. tester/test-report.md 已创建，包含所有测试结果
2. 所有发现的 bug 都已由 spec-debugger 修复并重新验证
3. 关键路径日志验证已记录到 tester/test-report.md
4. 端侧测试审计日志已保存到当前 Spec 目录的 tester/artifacts/test-logs/<run-id>/
5. 已完成脱敏检查，未保存 token、密码、密钥或真实用户隐私
6. 已完成测试策略沉淀判断；如需新增或更新策略，已获得用户确认并维护 references/ 和策略表
7. 已更新 lead/team-context.md 的 Task Progress 和必要的 Problem Resolution Log
8. 已通知 TeamLead

常见陷阱

• 直接修复 bug 或绕过 TeamLead 联系 spec-debugger（破坏协作闭环）
• tester/test-plan.md 验收标准不够具体（无法判断通过/失败）
• 忘记在 tester/test-report.md 中引用 debug 文档
• 端侧测试只看界面结果，没有保存 console/network/截图等审计证据
• 关键路径没有日志或 trace id，导致失败后无法复盘
• 审计日志包含未脱敏的 token、密码、密钥或真实用户隐私
• 把可复用测试策略只写在 tester/test-report.md，没有沉淀到 spec-test/references/
• 修复循环重验后忘记更新 Loop Budget，或在触发预算上限后仍发起新一轮 bug handoff（应停止并升级给 TeamLead）