---
name: test-strategy-six-layers
description: 三层测试策略参考文档，被 test-backend 和 test-frontend 共同引用。
---

# 测试总控（精简）

## 项目概览入口
- 项目定位、技术栈与目录入口请阅读：`references/project-overview.md`

## 触发条件
- 用户提出测试需求但未说明后端/前端或类型不明确。

## 测试策略（三层全覆盖，页面驱动）

### 核心原则：测试范围从前端页面倒推，不从 API 文档正推

```
❌ 旧方式: 07-api.md (136端点) → 全部测试 → 浪费在无人使用的 API 上
✅ 新方式: 前端页面 → 页面调用了哪些 API → 这些 API 必须 100% 覆盖
```

### 执行顺序（严格按序，前一层未通过则后一层无意义）

| 层 | 测什么 | 怎么测 | 分流到 |
|----|--------|--------|--------|
| **L0** | **前端页面清点 + API 清单** | 扫描可达页面、提取 API 调用、标记孤立页面和死 API | 脚本/手动 |
| L0a | 请求契约（前端请求字段 ↔ 后端 DTO） | 静态脚本 | `contract-check.ts` |
| L0b | 响应契约（后端返回值 ↔ 前端 interface） | 静态脚本 | `contract-check.ts` |
| L0c | 响应快照对比（后端实际返回 ↔ 前端 interface） | 启动后端，curl 每个端点，提取返回 JSON 字段结构，自动与前端 interface 对比 | `response-snapshot-check.ts` |
| L1 | 后端 API 业务逻辑（**仅 L0 清单中的 API**） | 集成测试（HTTP→真实数据库） | `test-backend` |
| L1c | 种子 / 生产脱敏快照数据质量（禁止直连生产 DB） | 数据校验脚本 | `data-quality-check.ts` |
| L2 | 前后端连通 + 交互逻辑 | Playwright MCP 走业务流程 | `test-frontend` |
| L3 | 视觉/体验/边界 | 手动查看页面 | 用户本人（不需要 skill） |

### L0 前端页面清点（新增，最高优先级）

**这一步定义了整个测试的范围边界。**

1. **扫描所有 page.tsx**：列出模块下所有页面文件
2. **识别可达页面**：有导航菜单入口 or 有 `router.push` 跳转链接的页面
3. **标记孤立页面**：有 page.tsx 但无任何入口 → 提示用户确认是否删除
4. **提取 API 调用清单**：从每个可达页面的 `import { ... } from '@/services/api/xxx'` 中提取所有 API 函数
5. **映射到 HTTP 端点**：将 API 函数映射到实际的 HTTP 方法+路径
6. **生成"必须测试"清单**：这个清单就是 L0a/L0b/L1 的测试范围
7. **标记死 API**：在 07-api.md 中标注为 In-scope 但前端未使用的 API → 建议降级为 Out-of-scope

**输出物**：
- 可达页面清单（含每页调用的 API 数量）
- 孤立页面列表（建议删除）
- 必须测试的 API 函数清单（前端正在使用的）
- 死 API 列表（07-api.md 标注 In-scope 但无前端调用的）

**覆盖率口径**：
- 100% 覆盖 = L0 清单中的所有 API 都有对应的集成测试
- 不在 L0 清单中的 API 不计入覆盖率

### L0c 响应快照对比

**解决的问题**：L0a/L0b 静态分析无法覆盖 Controller 直接 return service 结果的端点（约占 60%），导致响应字段不匹配问题全部漏检。

**端点来源（自动，禁止手动维护）**：
- 脚本从 `frontend/src/services/api/performance.ts` 自动提取所有 `apiClient.get(...)` 调用
- 提取 URL 模板、函数名、查询参数
- **不维护硬编码端点列表**——新增 API 后无需修改脚本
- 覆盖率 = 成功请求的端点数 / 自动提取的 GET 端点总数

**执行方式**：
1. 确保后端服务运行（localhost:3001）
2. 脚本自动登录获取 token
3. 自动从前端代码提取所有 GET 端点
4. 对每个端点发真实请求，提取返回 JSON 的字段路径
5. 与前端 interface 的字段名自动对比（如有配置）
6. 输出不匹配列表

**覆盖能力**：能一次性发现所有 A 类（字段名不匹配）和 B 类（后端缺少字段）问题。

**禁止手动维护端点列表的原因**：手动维护会导致新增 API 被遗漏（第三轮测试中 analytics 报表 API 就是因此漏检）。

## 分流规则（必须）

1. **用户说"全部测一遍"/"完整测试"** → L0 → L0a/L0b → L1 → L1c → L2（按顺序）
2. **用户说"测一下后端"/"测 API"/"跑集成测试"** → `test-backend`（L1，范围仍以 L0 清单为准）
3. **用户说"测一下页面"/"前后端连起来测"/"走一遍流程"** → `test-frontend`（L2）
4. **用户说"帮我验证一下"（未指定）** → L0 → L0a/L0b → L1 → L1c → L2
5. **用户说"检查契约"/"字段对不对"** → L0a + L0b
6. **用户说"检查数据"/"种子数据对不对"** → L1c
7. **用户说"有哪些页面"/"页面覆盖"** → L0

## 后端单元测试定位（必须）

- 后端单元测试不是当前项目的默认测试路径。
- 现有单元测试按历史遗留资产处理，不作为 AI 的默认新增或默认维护要求。
- 仅当逻辑满足以下条件时，才考虑新增或保留单元测试：
  - 复杂纯计算逻辑
  - 明确独立于数据库和外部服务
  - 用集成测试表达会明显过重且定位收益低
- 普通 CRUD、Controller、强依赖 Prisma 的 Service，默认走 L1 集成测试，不再引导 AI 优先补单元测试。

## 前置规则（必须）
- 若本次涉及需求改动，先确认已按影响面更新 `docs/modules/{module}/` 对应文档（01-10，按需），再开始测试执行。

## 通用规范入口
- `references/best-practices.md`
- `references/document-sync-checklist.md`
- `./testing-standards.md`
- `testing/README.md`
- 模块级测试文档：`09-test-scenarios.md` 定义范围与预期，`10-e2e-test-spec.md` 定义详细执行规范

## 测试报告要求（必须）
- **L0 清单**：可达页面数、API 函数数、孤立页面、死 API
- 覆盖度说明：覆盖范围 = L0 清单中的 API 数，覆盖率 = 已测 API / L0 清单 API
- 契约一致性：输入/输出与文档契约一致性检查结果
- 流程说明：测试流程的输入、输出、使用的 API/页面、执行步骤与结果摘要
- 用例明细：输入、使用的 API/页面清单、输出、结果

## 数据安全规则（必须）

**集成测试清理策略**：
- 只清理 performance schema 的业务数据（周期、KPI、评估等）
- **禁止清理**：用户表、角色表、权限表、组织表、部门表、360 模板、等级配置
- 测试创建的模板/配置通过名称中的时间戳标识，清理时用正则 `name ~ '[0-9]{10}'` 匹配
- `shouldCleanup()` 在 `NODE_ENV=development` 时必须返回 `false`

### L1c 补充校验项

- **权限矩阵校验**：从 Controller 提取 `@RequirePermissions`，从种子数据提取角色权限，交叉验证每个角色对每个端点的访问权限是否符合业务预期
- **模板嵌套结构校验**：JSONB 字段（如 360 模板 dimensions）的内部结构完整性
- **测试账号业务数据完整性**：所有测试账号在活跃周期中是否有 KPI 分配

## 契约检查规则（必须）

- **Warning 不算通过**：L0a/L0b 报告中的"字段差异（兼容）"必须逐条人工确认，未确认的视为"待验证"
- **响应字段必须实测**：不能只依赖静态正则分析，L0c 实际请求对比是必须步骤
- **嵌套结构必须覆盖**：数组元素内的字段（如 `items[].employee.displayName`）必须纳入对比范围
- **禁止手动维护检查范围**：L0c 端点列表、null-safety 方法列表等必须从代码自动提取，不硬编码。手动维护必然遗漏新增内容

### L1 集成测试补充断言要求

- **计算结果正确性**：加权分、进度百分比、人数统计等必须有数值断言（如自评 80 分 × 权重 50% = 加权分 40）
- **多组织隔离**：带 organizationId 查询时只返回该组织数据，不能泄漏其他组织
- **状态机全流转**：不只测单步转换，测完整链路（如 360: 添加评估人 → 提交反馈 → 自动 COMPLETED）
- **Decimal 类型安全**：Prisma Decimal 字段在前端使用前必须 Number() 转换

## 自动化报告
- 后端集成测试可使用 `test-backend` 脚本生成报告初稿（见 `.agents/skills/test-backend/SKILL.md`）。