xworkmate-app/docs/quality/xworkmate-test-spec.md

XWorkmate 测试规范

适用范围: xworkmate.svc.plus 规范等级: 正式 用途: 统一一次变更的测试规划、执行、验收、归档口径。

1. 规范目标

这份规范定义什么样的测试结果才算可验收、可归档、可复用。它用于回答三个问题：

1. 这次变更要测什么
2. 哪些证据足以证明已经测过
3. 如果自动化不够，人工补测应该怎么写

2. 适用范围

当变更涉及以下任一项时，建议使用本规范：

• UI 与交互行为
• 设置页、网关、凭据、存储、权限
• 路由、运行时、会话、同步链路
• 发布前验证
• 日志任务、回归任务、验收任务

3. 输出物

一次完整的测试工作，至少应产出以下内容：

• 测试验收文档
• 关键命令和结果摘要
• 失败项或风险项说明
• 必要的人工补测项
• 相关实现与测试文件引用

4. 文档落点

按内容性质选择目录：

• docs/releases/：发布、回归、日志任务验收
• docs/reports/：问题定位、专项分析、偏调查型报告
• docs/testing/：模板、指南、可复用写法
• docs/quality/：正式规范、质量标准、验收口径

如果是长期复用的规则，必须优先放到 docs/quality/。

5. 验收标准

一份测试验收记录只有在满足以下条件时，才能算作完整：

• 测试范围明确
• 命令可复现
• 结果可核验
• 失败或跳过有理由
• 人工补测项与风险点明确

如果某项结论来自推断，必须明确标注为推断，不得写成已验证事实。

6. 必填章节

正式验收文档建议包含这些章节：

1. 变更摘要
2. 测试命令与结果
3. 重点验证点覆盖
4. 失败项
5. 高风险回归点
6. 建议人工补测项
7. 相关文件

7. 命令选择原则

优先级从高到低：

1. 与变更最直接相关的 targeted tests
2. flutter analyze
3. 宽范围 flutter test
4. 设备或集成测试
5. 构建、打包、安装验证

不要为了“看起来完整”去跑与变更无关的大测试套件。

8. 风险分级

以下情况应视为高风险：

• 安全、凭据、令牌、TLS、权限、文件上传相关变更
• 运行时路由或会话状态变更
• 真实设备、真实服务、真实账号依赖
• 自动化无法覆盖的时序和并发问题

高风险项必须在结果中明确列出，不可省略。

9. 报告准则

• 只写已执行或直接可验证的内容
• 命令失败时记录首个失败点
• 不要把 skip 写成 pass
• 不要把推断写成事实
• 如果任务来自日志，保留命令与关键摘要

10. 参考报告

示例验收文档：

• docs/releases/2026-03-23-single-agent-test-acceptance.md