anian0/test-suite-maintainer

<SUBAGENT-STOP> 如果你是作为子代理被派发执行特定任务，跳过此 skill。 </SUBAGENT-STOP>

测试套件维护

这个 skill 的目标不是补写开发阶段的单元测试，也不是用 mock 数据重复验证局部逻辑。它用于功能完成开发、已转测、并部署到可验证环境之后，维护和执行面向上线准入的完整流程测试。

测试通过代表：功能在真实部署环境、真实配置、真实或准真实业务数据、真实服务链路下满足需求和设计约束，可以作为上线判断依据之一。

核心原则

1. 以已转测和已部署为前提

   • 默认功能代码已经完成开发并进入测试阶段。
   • 默认相关服务、数据库、配置、权限、外部依赖或测试替身环境已经准备好。
   • 如果环境未准备好，先输出环境缺口清单，不要退回去设计单元测试。

2. 验证完整业务流程

   • 优先覆盖用户真实操作路径、接口链路、数据落库、状态流转、权限边界、异常恢复和跨模块协作。
   • 不以函数级断言、mock 数据、孤立 fixture 作为主要验收手段。
   • 必要时可以使用脚本自动执行流程，但脚本必须调用真实接口、真实页面或真实服务入口。

3. 每个功能模块独立维护

   • 每个功能模块必须有独立目录。
   • 测试方案、测试脚本、执行报告和测试数据说明都放在该模块目录下。
   • 不使用一个全局 test-plan.md 混放多个功能模块的方案。

4. 先设计方案，确认后再写脚本

   • 根据需求文档、设计文档、接口文档、部署说明和用户补充信息，先完成测试方案。
   • 方案必须经用户确认后，才创建或修改测试脚本。
   • 如果用户修改方案，脚本必须按确认后的方案实现。

5. 上线阻断标准清晰

   • 核心主流程失败、数据状态错误、权限错误、真实依赖不可用、关键异常流程不符合预期，均视为上线阻断。
   • 不能用“单元测试已通过”替代完整流程验收。

推荐目录结构

测试套件维护在项目的 workplace/test/ 目录下。每个功能模块一个独立目录：

workplace/test/
├── test-manifest.yaml
├── modules/
│   ├── auth/
│   │   ├── test-plan.md
│   │   ├── scripts/
│   │   │   ├── login_flow.py
│   │   │   └── register_flow.py
│   │   ├── data.md
│   │   └── reports/
│   │       └── 2026-04-20.md
│   ├── payment/
│   │   ├── test-plan.md
│   │   ├── scripts/
│   │   │   ├── checkout_flow.py
│   │   │   └── refund_flow.py
│   │   ├── data.md
│   │   └── reports/
│   │       └── 2026-04-20.md
│   └── ...
└── shared/
    ├── env.example.md
    ├── helpers/
    └── reports/

目录职责：

• modules/<module>/test-plan.md: 模块级完整流程测试方案。脚本生成前必须先有此文件并经确认。
• modules/<module>/scripts/: 根据确认后的方案编写的自动化或半自动化测试脚本。
• modules/<module>/data.md: 真实测试数据准备、账号、订单、配置、清理方式和数据风险说明。
• modules/<module>/reports/: 每次执行后的验收报告。
• shared/: 跨模块共用的环境说明、帮助函数和全量报告。
• test-manifest.yaml: 全量模块清单和上线验收状态索引，不替代模块测试方案。

test-manifest.yaml 格式

test-manifest.yaml 用于索引模块和上线验收状态，不再承载所有测试用例细节。

version: "2.0"
project:
  name: "项目名称"
  test_root: "workplace/test"
  target_environment: "staging"

modules:
  auth:
    description: "用户认证模块"
    priority: high
    requirement_docs:
      - "docs/requirements/auth.md"
    design_docs:
      - "docs/design/auth.md"
    module_dir: "workplace/test/modules/auth"
    plan: "workplace/test/modules/auth/test-plan.md"
    scripts:
      - "workplace/test/modules/auth/scripts/login_flow.py"
      - "workplace/test/modules/auth/scripts/register_flow.py"
    status: active
    plan_status: confirmed
    last_run: "2026-04-20"
    last_result: pass
    blockers: []

  payment:
    description: "支付处理模块"
    priority: high
    requirement_docs:
      - "docs/requirements/payment.md"
    design_docs:
      - "docs/design/payment.md"
    module_dir: "workplace/test/modules/payment"
    plan: "workplace/test/modules/payment/test-plan.md"
    scripts:
      - "workplace/test/modules/payment/scripts/checkout_flow.py"
      - "workplace/test/modules/payment/scripts/refund_flow.py"
    status: active
    plan_status: draft
    last_run: null
    last_result: pending
    blockers:
      - "测试支付网关账号未配置"

字段说明：

• priority: high / medium / low，上线前优先执行高优先级模块。
• status: active / skip / pending，控制是否纳入执行。
• plan_status: draft / confirmed，只有 confirmed 才能生成或修改脚本。
• last_result: pass / fail / blocked / pending。
• blockers: 记录影响上线验收的问题。

模块测试方案格式

每个模块的 test-plan.md 必须以真实流程验收为中心。

# 用户认证模块测试方案

**模块**: auth
**方案状态**: draft
**目标环境**: staging
**设计依据**:
- docs/requirements/auth.md
- docs/design/auth.md
**创建日期**: 2026-04-20

## 验收目标

- 验证用户注册、登录、会话保持、退出登录在真实部署环境下完整可用。
- 验证用户数据正确写入数据库，并能被后续流程读取。
- 验证关键异常路径不会产生错误状态。

## 环境前提

| 项目 | 要求 | 状态 |
| --- | --- | --- |
| 前端服务 | staging 前端已部署 | 待确认 |
| 后端服务 | staging API 已部署 | 待确认 |
| 数据库 | 可写入测试用户数据 | 待确认 |
| 外部依赖 | 邮件或验证码服务测试通道可用 | 待确认 |

## 测试数据

| 数据项 | 来源 | 用途 | 清理方式 |
| --- | --- | --- | --- |
| 测试用户账号 | 真实创建 | 注册和登录流程 | 测试后删除或标记 |

## 验收场景

| 场景ID | 场景名称 | 优先级 | 类型 | 预期结果 |
| --- | --- | --- | --- | --- |
| auth-flow-001 | 新用户注册后登录 | high | e2e | 用户可注册、登录成功、数据库状态正确 |
| auth-flow-002 | 错误密码登录失败 | high | e2e | 返回明确错误，登录态不创建 |

## 场景流程

### auth-flow-001 新用户注册后登录

1. 使用真实前端页面或真实注册接口提交新用户信息。
2. 验证响应成功，并记录用户 ID。
3. 查询数据库或后台接口确认用户已创建，状态正确。
4. 使用该用户执行登录。
5. 验证登录态、返回用户信息和页面跳转符合设计。
6. 执行退出登录。
7. 清理测试用户或按数据策略标记。

### auth-flow-002 错误密码登录失败

1. 准备一个已存在测试用户。
2. 使用错误密码调用真实登录入口。
3. 验证登录失败响应符合设计。
4. 验证不会创建有效登录态。
5. 验证用户状态未被错误修改。

## 脚本计划

| 脚本路径 | 覆盖场景 | 执行方式 |
| --- | --- | --- |
| scripts/login_flow.py | auth-flow-001, auth-flow-002 | 调用 staging 真实 API |

## 上线阻断标准

- 注册或登录主流程失败。
- 用户数据写入错误或状态不一致。
- 错误密码产生有效登录态。
- 测试环境关键依赖不可用且无法替代验证。

方案规则：

1. 每个模块一个 test-plan.md。
2. 方案必须引用需求和设计依据；如果缺少文档，要明确写出依据缺口。
3. 每个验收场景必须包含环境前提、真实数据、执行步骤、预期结果和清理方式。
4. 方案只写测试逻辑和验收标准，不写代码。
5. 方案状态为 draft 时不能写脚本；用户确认后改为 confirmed。

工作流程

场景一：初始化模块测试套件

适用于用户要求为某个功能模块建立上线验收测试。

1. 识别功能模块名称和边界。
2. 查找需求文档、设计文档、接口文档和部署说明。
3. 创建 workplace/test/modules/<module>/ 目录。
4. 编写 test-plan.md，状态为 draft。
5. 编写或更新 data.md，说明真实测试数据准备和清理方式。
6. 更新 test-manifest.yaml，登记模块、方案路径和 plan_status: draft。
7. 暂停并要求用户确认测试方案。
8. 用户确认后，将 plan_status 改为 confirmed，再创建脚本。

场景二：根据已确认方案创建测试脚本

适用于用户已经确认模块测试方案。

1. 读取 modules/<module>/test-plan.md。
2. 确认方案状态为 confirmed，或用户在当前对话中明确确认。
3. 根据“脚本计划”创建 scripts/ 下的脚本。
4. 脚本必须忠实实现方案中的场景流程和断言。
5. 脚本默认调用真实入口，不 mock 自身业务链路。
6. 更新 test-manifest.yaml 的脚本路径。
7. 如可执行，运行脚本并生成模块报告。

场景三：更新已有模块测试方案

适用于需求或设计变更后更新上线验收测试。

1. 读取模块当前 test-plan.md 和相关文档变更。
2. 标出新增、修改、删除的验收场景。
3. 更新模块 test-plan.md，状态改为 draft。
4. 同步更新 data.md 中的数据准备和清理策略。
5. 更新 test-manifest.yaml 的 plan_status: draft。
6. 暂停并要求用户确认方案。
7. 用户确认后再更新脚本。

场景四：执行上线前完整流程验收

适用于“上线前测试”“跑全量验收”“真实流程验证”。

1. 读取 test-manifest.yaml。
2. 筛选 status: active 且 plan_status: confirmed 的模块。
3. 按 priority: high > medium > low 排序。
4. 检查每个模块的环境前提和测试数据是否就绪。
5. 执行模块 scripts/ 下的脚本，或按方案进行半自动化验证。
6. 记录每个场景的实际结果、证据、数据记录和问题。
7. 生成模块报告到 modules/<module>/reports/<date>.md。
8. 生成全量报告到 shared/reports/<date>-full.md。
9. 更新 test-manifest.yaml 的 last_run、last_result 和 blockers。

验收结论：

• 所有 high 模块通过，且无上线阻断问题：可以进入上线评审。
• 任一 high 模块失败：不建议上线。
• 任一 high 模块 blocked：必须先补齐环境、数据或依赖后重测。

场景五：查看覆盖和上线风险

1. 汇总 test-manifest.yaml 中所有模块状态。
2. 列出没有测试方案的模块。
3. 列出 plan_status != confirmed 的模块。
4. 列出 last_result 为 fail 或 blocked 的模块。
5. 列出只有脚本但缺少方案确认的模块。
6. 给出上线风险判断。

测试脚本编写要求

脚本可以使用 Python、Playwright、pytest、Vitest、curl 或项目已有工具链。选择依据是能否稳定执行真实流程，而不是框架偏好。

脚本必须满足：

• 从环境变量或配置文件读取目标环境地址、账号和密钥，不硬编码敏感信息。
• 调用真实页面、真实接口或真实服务入口。
• 对业务结果、数据状态和关键副作用做断言。
• 记录足够的失败信息，方便定位问题。
• 包含测试数据清理或隔离策略。
• 不使用 mock 数据替代真实业务链路。

可以接受的测试替身：

• 第三方支付、短信、邮件等外部服务可使用官方 sandbox 或测试通道。
• 法规、费用或生产风险较高的外部动作可使用预发专用替身。
• 替身必须在 data.md 和报告中明确说明。

不应使用：

• 只调用内部函数的单元测试作为上线验收。
• 与真实部署环境无关的纯 fixture 测试。
• 大量 mock 自身业务模块后仍宣称完整流程通过。

报告格式

模块报告示例：

# 用户认证模块验收报告

**模块**: auth
**执行时间**: 2026-04-20 14:30
**目标环境**: staging
**结论**: pass

## 执行统计

| 指标 | 数值 |
| --- | --- |
| 场景总数 | 2 |
| 通过 | 2 |
| 失败 | 0 |
| 阻塞 | 0 |

## 场景结果

| 场景ID | 场景名称 | 结果 | 证据 |
| --- | --- | --- | --- |
| auth-flow-001 | 新用户注册后登录 | pass | user_id=12345 |
| auth-flow-002 | 错误密码登录失败 | pass | response=401 |

## 数据处理

- 测试用户已删除。
- 登录会话已失效。

## 问题和风险

- 无。

全量报告必须包含：

• 各模块结论。
• high 优先级模块是否全部通过。
• 失败和阻塞项。
• 上线建议。

最佳实践

1. 先方案后脚本：任何新增或变更都先更新模块 test-plan.md，确认后再改脚本。
2. 模块隔离：不要把多个功能的方案堆在一个全局文件里。
3. 真实链路优先：上线验收关注真实环境端到端结果。
4. 数据可追踪：测试数据来源、用途和清理方式必须写清楚。
5. 阻断项明确：失败、阻塞、可接受风险要分开记录。
6. 脚本忠实于方案：脚本逻辑变更前先更新方案。
7. 不要倒退到开发测试：单元测试和 mock 测试属于开发阶段质量保障，不是此 skill 的主要产出。