测试与诊断规范

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

⚠️ 核心强制要求

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

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

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

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

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

## 进度

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

## 测试记录
（待填写）

第二步：执行测试

• 后端变更（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 – 诊断流程详细说明