# XWorkmate 测试规范

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

## 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/reports/2026-03-23-single-agent-test-acceptance.md`

长期维护文档：

- `docs/testing/core-integration-auto-test-plan.md`
- `docs/cases/core-integration-manual-cases.md`