---
name: w03-testing-and-diagnostics
description: 测试与诊断工作流，包含单元测试和浏览器测试，测试失败时自动诊断。适用于代码变更后的测试执行与排障。
---

# 测试与诊断规范

> 适用于代码变更后的测试执行与排障，确保结果可靠、补救完整。

---

## ⚠️ 核心强制要求

### 第一步：创建测试任务文档

**测试开始前必须先创建** `agent-task-log/ongoing/TEST_[日期]_[任务].md`

完成后归档至 `agent-task-log/archive/[年月]/`

```markdown
# 测试任务：[任务名称]

## 当前状态
**阶段**：🔄 执行测试
**下一步**：运行单元测试

## 进度

| 阶段 | 状态 |
|------|------|
| 执行测试 | 🔄 进行中 |
| 诊断（如需）| ⬜ 待定 |

## 测试记录
（待填写）
```

### 第二步：执行测试

- **后端变更**（`backend/**`）→ 单元测试
- **前端变更**（`frontend/**`）→ 浏览器测试
- **全栈变更** → 先单元测试，再浏览器测试

### 第三步：更新文档

测试完成后立即更新文档，记录结果

### 基线约束

- 测试完成前不得提交交付结果
- 失败时必须先修复再继续
- 无法执行测试时需说明原因和补测计划

---

## AI Agent 行为要求

### 测试任务开始时

1. **先创建** TEST_*.md 文档
2. 根据变更类型选择测试
3. 执行测试并更新文档
4. 失败时触发诊断流程（最多三轮）

### 诊断流程

每轮：观察 → 推断 → 操作 → 结果

**升级条件**：
- 三轮排查无果
- 高风险或涉及架构/安全决策

### 恢复执行

新对话检查 `agent-task-log/TEST_*.md`，从"当前状态"继续

### 人机协作

AI 无法 100% 自主完成所有测试，部分场景需要人类协助：

**可请求人类协助的情况**：
- 浏览器页面需要手动打开或导航
- 需要人工验证视觉效果
- 涉及复杂的用户交互流程
- AI 工具无法访问的系统资源

**协作方式**：
1. 明确告知用户需要协助的具体操作
2. 用户完成后，AI 继续后续测试步骤
3. 记录协作点到测试文档

**原则**：半自动化测试同样有效，AI 分担大部分工作，人类补充 AI 难以处理的环节。

### 与 W00 协同（自动 + 手动）

- 进入测试前可自动调用 `w00-workflow-checkpoint checkpoint` 记录测试起点与下一步。
- 测试失败并进入诊断时，可自动更新 issue 为 `status:blocked` 并记录 blocker。
- 用户可手动执行 `/w00-workflow-checkpoint` 补记测试节点与读档信息。

---

## 禁止事项

- ❌ 跳过或延迟测试
- ❌ 未记录结果就报告完成
- ❌ 失败后继续提交

---

## 工具脚本

- `scripts/run_test_workflow.py` - 单元测试工作流
- `scripts/run_browser_tests.py` - 浏览器测试工作流
- `scripts/auto_diagnose.py` - 自动诊断

---

## 参考资料

- `references/testing-workflow.md` - 测试工作流详细说明
- `references/browser-testing.md` - 浏览器测试详细说明
- `references/diagnosis-workflow.md` - 诊断流程详细说明