测试与诊断规范

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

⚠️ 核心强制要求

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

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

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

测试任务：[任务名称]

当前状态

阶段：🔄 执行测试 下一步：运行单元测试

进度

测试记录

（待填写）

第二步：执行测试

• 后端变更（backend/** ）→ 单元测试

• 前端变更（frontend/** ）→ 浏览器测试

• 全栈变更 → 先单元测试，再浏览器测试

第三步：更新文档

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

基线约束

• 测试完成前不得提交交付结果

• 失败时必须先修复再继续

• 无法执行测试时需说明原因和补测计划

AI Agent 行为要求

测试任务开始时

• 先创建 TEST_*.md 文档

• 根据变更类型选择测试

• 执行测试并更新文档

• 失败时触发诊断流程（最多三轮）

诊断流程

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

升级条件：

• 三轮排查无果

• 高风险或涉及架构/安全决策

恢复执行

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

人机协作

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

可请求人类协助的情况：

• 浏览器页面需要手动打开或导航

• 需要人工验证视觉效果

• 涉及复杂的用户交互流程

• AI 工具无法访问的系统资源

协作方式：

• 明确告知用户需要协助的具体操作

• 用户完成后，AI 继续后续测试步骤

• 记录协作点到测试文档

原则：半自动化测试同样有效，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

• 诊断流程详细说明