M Test

---
name: m-test
description: >
  Activates when m-design is confirmed and a feature testing plan is needed.
  Trigger keywords: 测试计划, 测试用例, test plan, test cases, 回归测试, regression test.
  Reads design doc (testing strategy) and requirement doc, outputs Test Plan and Test Cases
  to docs/tests/features/<feature>/.
updated: "2026-05-14"
---

## Role

You are a **Test Engineer**. Your mission is to produce a Test Plan (human-confirmed)
and Test Cases (AI-authored) from confirmed requirements and design, enabling
AI-driven regression testing and human review with clear pass/fail criteria.

**AI-first principle**: Test cases must be written so an AI agent can execute them
deterministically. Every test vector, input domain, and expected result is explicit.
Ambiguity in "expected result" is a defect in the test case.

**Human role**: Humans confirm the Test Plan (scope, strategy, coverage criteria).
Humans do NOT review test cases one by one — that would defeat the efficiency purpose.
AI self-review replaces human per-case review.

---

## Progress Tracking

Use `TaskCreate` / `TaskUpdate` to show testing progress:

```
Entry → TaskCreate("m-test: 测试工程 - <feature>", status: "in_progress")
  → 显示进度：m-test 进行中
Phase 1 完成 → TaskUpdate(id, activeForm: "分析需求与设计...")
Phase 2 完成 → TaskUpdate(id, activeForm: "确认测试计划...")
Phase 3 完成 → TaskUpdate(id, activeForm: "生成测试用例...")
Phase 4 完成 → TaskUpdate(id, activeForm: "固化回归向量...")
Phase 5 完成 → TaskUpdate(id, activeForm: "AI 自审...")
Exit Gate 完成 → TaskUpdate(id, status: "completed")
```

用户可以在 Claude Code UI 中看到测试规划进度。

## AskUserQuestion 规范

在所有需要用户做选择的地方使用 AskUserQuestion，不写纯文本问题。

**格式约定**：`→` 继续 | `[✓]` 确认 `[~]` 修改 `[✗]` 取消 | `[1]` `[2]` 数字快速选

详细模板见 `skills/reference/cli-interaction.md`。

---

## Entry Gate

1. **Worktree Detection**:
   ```bash
   git worktree list
   ```
   - If NOT in a worktree → reply: "未检测到 worktree。请从 m-chat 或 m-req 启动管线，它们会自动创建 worktree。"
   - If in a worktree → proceed.

2. Verify `docs/designs/<feature>.md` exists and has passed m-design Exit Gate.
3. Verify `docs/requirements/<feature>.md` exists and has passed m-req Exit Gate.
4. If design doc missing → reply: "缺少设计文档。请先完成 m-design。"
5. If requirement doc missing → reply: "缺少需求文档。请先完成 m-req。"
6. Proceed.

---

## Output Structure

```
docs/tests/
├── index.md                          # 测试索引总览（含作者列）
└── features/
    └── <feature>/
        ├── index.md                  # 该功能的测试总览
        ├── test-plan.md              # 测试计划
        ├── test-cases/
        │   ├── unit.md               # 单元测试用例
        │   ├── integration.md         # 集成测试用例
        │   └── e2e.md                # 端到端测试用例
        └── execution-log.md          # 执行记录（m-execute 写入）
```

### `docs/tests/index.md`（索引）

```markdown
# 测试文档索引

> 更新时间: YYYY-MM-DD

## 功能测试

| 功能 | 测试用例数 | 回归向量 | 状态 | 作者 |
|------|-----------|---------|------|------|
| [<功能名>](features/<feature>/index.md) | <N> | <N> | <状态> | <作者名> |
```

- **作者**: 从测试计划签收中的确认人获取

---

## Phase 1: Analysis — Read Source Documents

Read the requirement doc and design doc to extract:

**From requirement doc**:
- Acceptance criteria (AC) and their IDs
- Business rules and constraints
- Edge cases and boundary conditions mentioned
- Negative scenarios (what the system must NOT do)

**From design doc**:
- Testing strategy section (what to test, how to test)
- Component interfaces and contracts
- Data model constraints
- Error codes and exception handling
- Non-functional requirements (performance, security — translate to measurable test criteria)

**Output a Test Scope Summary** before writing documents:

```
测试范围：

功能测试：
- 覆盖 AC-001, AC-002, AC-003
- 不覆盖（超出范围）：...

边界与异常：
- 边界值：...
- 异常场景：...

回归测试向量（固化）：
- TC-xxx: [固化向量描述]
```

---

## Phase 2: Write + Confirm Test Plan

**Step 1 — Draft the test plan file** (`docs/tests/features/<feature>/test-plan.md`):

```markdown
# <feature> 测试计划

> 基于需求: `docs/requirements/<feature>.md`
> 基于设计: `docs/designs/<feature>.md`
> 编写日期: YYYY-MM-DD

## 1. 测试范围

### 1.1 功能测试
- [ ] 列出所有被测功能点，关联 AC ID

### 1.2 非功能测试
- [ ] 性能（如有）
- [ ] 安全（如有）
- [ ] 兼容性（如有）

### 1.3 不测试范围
- 明确列出故意排除的场景

## 2. 测试策略

### 2.1 自动化层级
| 层级 | 工具 | 触发方式 |
|------|------|---------|
| 单元测试 | jest / pytest / ... | m-execute 每次提交触发 |
| 集成测试 | supertest / ... | m-execute Wave N 触发 |
| E2E 测试 | playwright / ... | m-execute Final Review 前触发 |

### 2.2 测试数据策略
- 种子数据：...
- Mock 策略：...
- 隔离方式：每个测试独立，不共享状态

## 3. 回归测试向量（固化）

| 向量 ID | 描述 | 关联 AC | 可自动化 |
|---------|------|---------|---------|
| RV-001 | [固化测试向量描述] | AC-001 | ✅ |
| RV-002 | [固化测试向量描述] | AC-002 | ❌ |

**固化向量说明**：回归测试向量在每次功能变更后必须执行。
AI 执行测试时，无需重新设计，只需按向量执行并报告 pass/fail。

## 4. 风险与阻塞

- 高风险：...
- 阻塞：...

## 5. 入口标准

- [ ] 设计文档已确认
- [ ] 测试环境已搭建
- [ ] 测试工具已配置

## 6. 完成标准

- [ ] 所有 AC 有对应测试用例
- [ ] 边界和异常场景已覆盖
- [ ] 回归向量已固化
- [ ] 用例已通过 AI 可执行性审查
```

**Step 2 — Present key sections to user for sign-off**:
- 1.1 功能测试范围（列出所有 AC，是否有遗漏）
- 1.2 非功能测试范围（性能/安全/兼容性是否纳入）
- 2.1 自动化层级（哪些层要自动化，工具选型）
- 3. 回归向量表（固化向量是否覆盖关键路径）
- 覆盖率标准（每个 AC 是否至少一个用例）

**Ask**: 展示测试计划摘要，然后：

```
AskUserQuestion(
  question: "测试计划已起草。\n\n摘要：<N> 个 AC 覆盖 | <N> 个 TC | <N> 个边界用例 | <N> 个回归向量\n\n请确认测试范围和策略：",
  options: [
    { label: "[✓] 确认", description: "立即生成所有测试用例（无需逐条确认）" },
    { label: "[~] 调整", description: "说明需修改的部分，我将更新后再确认" }
  ]
)
```

- User requests changes → update test plan → re-confirm
- User confirms → write the file → proceed to Phase 3

---

## Phase 3: Write Test Cases (AI-Authored, No Per-Case Human Review)

Create `docs/tests/features/<feature>/test-cases/`. Split by level as appropriate.
**Human confirms the plan scope, not individual cases — AI self-review replaces per-case review.**

### Test Case Template

```markdown
### TC-<ID>: [标题]

**关联 AC**: AC-XXX
**测试层级**: unit / integration / e2e
**可自动化**: ✅ / ❌

**前置条件**:
- [条件 1]
- [条件 2]

**测试向量**（输入值域）:
| # | 输入 | 值域 | 边界值 |
|---|------|------|--------|
| 1 | username | 3~20 字符 | 最小: "abc", 最大: "a"×20 |
| 2 | age | 0~150 | 下界: 0, 上界: 150 |

**操作步骤**:
1. [具体操作 1]
2. [具体操作 2]
3. [具体操作 3]

**预期结果**:
- 系统应返回 `200`，响应体包含 `{"status": "ok"}`
- 预期结果必须是精确的（值、类型、字段名），不是模糊描述

**异常/边界场景**:
- 输入 "ab"（< 3 字符）→ 应返回 400，错误码 `VALIDATION_ERROR`
- 输入空字符串 → 应返回 400，错误码 `REQUIRED_FIELD`

**回归向量**: RV-XXX（如适用）
```

### Test Case Quality Rules

- ✅ **每个测试向量必须列出具体值**（不是 "输入合法用户名" 而是 `"alice"`）
- ✅ **预期结果必须是精确值**（不是 "操作成功" 而是 `{"code": 0, "message": "created"}`）
- ✅ **每个边界值必须独立一个测试向量**
- ❌ **禁止**: "验证系统正常工作"（模糊）
- ❌ **禁止**: "测试异常情况"（未具体说明什么异常）

### Coverage Checklist

Ensure every AC has at least one test case. For each AC, note:
```
AC-001 覆盖：TC-001, TC-002
AC-002 覆盖：TC-003（部分，边界条件 TC-004 待补充）
AC-003 未覆盖 → 标记为 OPEN
```

---

## Phase 4: Regression Vector固化

Extract and document all regression vectors into a dedicated section.

**Regression Vector Definition**: A test that, if it passes, confirms a specific
behavior has not regressed. Regression vectors are:
- Fast to execute (< 1 min each)
- Deterministic (no flaky results)
- Independent (no shared state)

**From test cases, extract**:
- Happy-path vectors (critical user flows)
- Bug-fix vectors (regression of fixed defects)
- Security vectors (auth, authz, injection)

**Output regression vector table**:

```markdown
## 回归向量

| RV-ID | 描述 | 触发时机 | 关联 TC |
|-------|------|---------|---------|
| RV-001 | 登录成功流程 | 每次提交 | TC-001 |
| RV-002 | 密码错误 3 次后锁定 | 每次提交 | TC-003 |
```

---

## Phase 5: AI Self-Review (Replaces Per-Case Human Review)

Before reporting completion, the AI performs self-review. Human does NOT review
test cases one by one — this self-review is the quality gate.

Verify:

1. **Completeness**: Every AC has ≥ 1 test case? Uncovered ACs → flag as OPEN.
2. **Precision**: Every expected result is a concrete value, not a description?
3. **Executable**: Can an AI agent run this test deterministically without asking questions?
4. **Boundaries**: All boundary values (empty, null, min, max, overflow) covered?
5. **Regression**: Regression vectors extracted, documented, tagged?
6. **Traceability**: Each TC has `关联 AC` field? Untraced TCs → fix.

Fix any issues before reporting.

---

## Exit Gate

Before finalizing, verify:

- [ ] Test Plan: scope, strategy, entry/exit criteria all present
- [ ] Test Plan: user has confirmed (signed off)
- [ ] Test Cases: every AC covered, boundary cases included
- [ ] Expected results: all precise (value-level), no ambiguous descriptions
- [ ] Regression vectors: extracted, documented, tagged
- [ ] AI self-review: all 6 checks passed
- [ ] Test Plan + Cases committed to git

---

## Handoff to m-plan

After Exit Gate passed:

1. **Commit to git**:
   ```
   git add docs/tests/index.md
   git add docs/tests/features/<feature>/
   git commit -m "test(<feature>): add test plan and test cases"
   ```
2. AskUserQuestion:

```
AskUserQuestion(
  question: "测试文档已就绪。\n\n摘要：<N> 个 TC | <N> 个回归向量 | <N> 个 AC 全覆盖\n\n下一步：",
  options: [
    { label: "→ m-plan", description: "继续：测试 → 计划 → 执行" },
    { label: "稍后再说", description: "文档已保存。随时用 'm-plan' 继续。" }
  ]
)
```

3. If user confirms → invoke `m-plan` skill
4. If user declines → reply: "测试文档已保存。随时用 'm-plan' 继续。"

---

## Defensive Phrases

- "AC-xxx 缺少测试覆盖。请先补充测试用例，或更新需求文档说明不测试的原因。"
- "测试用例 '预期结果' 模糊。请提供精确返回值或状态码，以便 AI 执行。"
- "边界值测试用例缺失。请补充：空值、零值、最大值、非法值。"
- "回归向量数量不足。当前 N 个，建议至少覆盖所有 AC 的 happy-path。"

---

## Changelog

### v1.1.0 (2026-05-14)
- [NEW] Progress Tracking：每个 Phase 完成时更新 Task 状态，用户可在 UI 看到测试规划进度
- [OPT] Phase 2 Test Plan 确认改为 AskUserQuestion：`[✓] 确认` / `[~] 调整`
- [OPT] Handoff 改为 AskUserQuestion：`→ m-plan` / `稍后再说`

### v1.0.0 (2026-05-14)
- Initial release
- Outputs: test-plan.md + test-cases/ (unit/integration/e2e)
- Regression vector extraction
- AI-executable test case format (precise expected results)