本文档定义 Proteus 当前的测试分层、交付要求与验收边界。目标是让每个里程碑都能明确回答：哪些由自动化保障，哪些必须人工确认。
| 项 | 说明 |
|---|---|
| Core-first | 关键正确性优先沉淀到 @proteus/core，降低 UI 变更带来的回归成本 |
| Deterministic-first | 优先自动化验证确定性逻辑、协议和状态变化 |
| 明确边界 | 把自动化测试与人工验收的责任拆开，避免“都以为对方会测” |
| Latest only | 测试规范与项目文档一样，只维护当前有效规则 |
| 层级 | 目标 | 当前载体 | 责任 |
|---|---|---|---|
| L0 静态检查 | 保证工程可编译、可构建、可分析 | type-check、build、lint |
AI |
| L1 单元测试 | 验证纯逻辑、数据结构、命令、工具 | packages/core/src/**/*.test.ts |
AI |
| L2 集成测试 | 验证 editor 主流程与模块组合 | packages/core/src/Editor.integration.test.ts |
AI |
| L3 契约测试 | 验证 snapshot、protocol、query、provider 等稳定边界 | packages/core/src/*persistence*.test.ts 及后续契约测试 |
AI |
| L4 UI 自动化测试 | 验证确定性 UI 行为和产品流程 | apps/web/src/**/*.test.tsx |
AI |
| L5 人工验收 | 验证视觉、文案、交互手感、真实使用判断 | .local/acceptance/*.md 清单 |
维护者 |
| 变更类型 | 最低要求 |
|---|---|
| Core 纯逻辑 | L1 |
| Command / Scene / Selection / Viewport | L1 + L2 |
| Snapshot / 导入导出 / 协议边界 | L1/L3 + 回归场景 |
| Web 确定性状态 | L4 |
| 影响 milestone 对外体验的交互 | L4 + L5 |
| 新增里程碑级功能 | 更新 spec、补测试、补人工验收清单 |
| 项 | 要求 |
|---|---|
| Spec | 中大型功能先有 spec.md / plan.md / tasks.md |
| 自动化测试 | 补到该功能最低要求的层级 |
| 验证结果 | 我必须明确写出 What I verified |
| 人工验收 | 需要人工确认的交互必须输出清单 |
| 风险说明 | 无法自动化覆盖的部分要写 Known gaps |
flowchart LR
A["实现完成"] --> B["L0-L4 自动化验证"]
B --> C["记录 What I verified"]
C --> D["输出人工验收清单"]
D --> E["维护者执行 L5 验收"]
E --> F["记录结果与剩余风险"]
| 标题 | 内容 |
|---|---|
What I verified |
我已经跑完的自动化检查与结果 |
What you need to verify |
你必须手动确认的 3-7 条清单 |
Expected result |
每条人工验收的预期结果 |
Known gaps |
我无法自动化覆盖的剩余风险 |
| 能力 | 现状 |
|---|---|
| Core 测试基础 | 已有完整的 core 单元与集成测试体系 |
| 契约层起点 | M2 已有 snapshot / persistence 契约测试 |
| Web 测试入口 | 从 M2 起建立 apps/web 的最小 UI 自动化测试 |
| 人工验收记录 | 使用 .local/acceptance/*.md 记录清单与执行结果 |
| 缺口 | 处理方向 |
|---|---|
| Web 覆盖较薄 | 先覆盖 M2 的保存、恢复、导入导出、状态展示 |
| 旧功能未按新规则表达 | 从 M2/M3 开始执行，逐步回补 M1 的表达与覆盖 |
| 视觉与手感不可自动化 | 明确由维护者执行 L5 验收，不假装“已经全自动覆盖” |