Generate Test Cases

---
name: generate-test-cases
description: 自主学习型测试文档生成器。从需求文档（Markdown）生成测试用例 XMind 文件，支持持久化记忆和持续学习。当用户提到"生成测试用例"、"根据需求生成测试"时触发。
compatibility: Requires Python 3
---

# 根据需求生成测试用例

从需求文档自动生成专业测试用例，具备深度解析、质量自检、自主学习能力。

## 核心能力

- **深度解析**：4 种测试设计方法（EP/BVA/ST/EG）系统性覆盖需求
- **质量内建**：覆盖率验证 + 优先级分布检查 + 自检门禁，生成前拦截缺陷
- **需求追溯**：自动建立需求↔用例双向追溯矩阵，量化覆盖率
- **自主学习**：持久化记忆 + 历史趋势分析 + 歧义决策复用，越用越准
- **交互式确认**：快速模式，关键节点人工把关

## 质量标准

生成的测试用例必须满足以下 7 维度（Phase 2.8 质量预审时逐项检查）：

| 维度 | 标准 | 检查方式 |
|------|------|----------|
| **需求覆盖** | 每条需求至少关联 1 条用例，覆盖率 ≥ 95% | 追溯矩阵计算 |
| **方法覆盖** | 每条需求至少使用 1 种设计方法，复杂需求 ≥ 2 种 | 方法分布统计 |
| **优先级分布** | P0: 10-15%, P1: 30-40%, P2: 30-40%, P3: 10-20% | 分布比例检查 |
| **步骤可执行** | 每条用例的步骤明确、可操作，预期结果可验证 | AI 自检 |
| **无需求外编造** | 所有用例来源于需求文档，不凭空编造场景 | 追溯关系验证 |
| **术语一致** | 用例中使用的术语与需求文档、`terminology.json` 一致 | 术语对照 |
| **无冗余重复** | 不同设计方法产生的用例无语义重复；已覆盖的验证目标不得以不同数据状态为由重复生成 | 去重扫描 |

## 交互模式

详见 [INTERACTION-PATTERNS.md](references/INTERACTION-PATTERNS.md)

采用**快速模式**：回车继续，仅在发现问题或异常时询问用户。

### 交互检查点

| 检查点 | 阶段 | 行为 |
|--------|------|------|
| 解析确认 | Phase 2.5 | 摘要 + 有问题时询问 |
| 歧义处理 | Phase 2.6 | 仅关键歧义 |
| 生成预览 | Phase 2.8 | 统计数据 |

## 测试设计方法

> 详细定义与示例见 [TEST-DESIGN-METHODS.md](references/TEST-DESIGN-METHODS.md)

**4 种方法按序叠加使用**：

```
EP 等价类划分 → BVA 边界值分析 → ST 场景法 → EG 错误推测
```

| 方法 | 核心动作 | 触发条件 |
|------|---------|---------|
| **EP 等价类** | 划分有效/无效等价类，无效类单独覆盖 | 有输入范围、格式、枚举约束 |
| **BVA 边界值** | 测试上点、离点、内点 | 有数值/长度/时间边界 |
| **ST 场景法** | 基本流→备选流→异常流各生成用例 | 涉及多步骤业务流程 |
| **EG 错误推测** | 补充特殊字符、极端值、并发场景 | 高风险模块、历史缺陷多 |

## 需求追溯与覆盖率

> 详细规范见 [TRACEABILITY.md](references/TRACEABILITY.md)

- **需求ID**：自动识别 `REQ-xxx`、`F1.2`、`US_042`、`PROJ-123` 等模式；无ID时生成 `MOD_{缩写}_{序号}`
- **双向追溯**：需求→用例 + 用例→需求，Phase 2.8 输出覆盖率统计
- **覆盖率目标**：≥ 95%，未覆盖需求在预览中高亮警告

## 优先级与回归分类

> 详细规则见 [TEST-PRIORITY.md](references/TEST-PRIORITY.md)

| 级别 | 来源 | 回归集 |
|------|------|--------|
| **P0** 核心 | 基本流用例 | 冒烟测试（每次构建） |
| **P1** 主要 | 备选流 + 边界值 | 核心回归（每日/提测） |
| **P2** 次要 | 异常流 + 错误推测 | 全量回归（发版前） |
| **P3** 边缘 | 边缘错误推测 | 全量回归（发版前） |

## .memory 记忆系统

> 完整 Schema 定义见 [MEMORY-SCHEMA.md](references/MEMORY-SCHEMA.md)

Skill 在项目中创建 `.memory/` 文件夹，存储跨会话学习数据：

```
.memory/
├── project-context.json      # 项目上下文（路径、名称）
├── terminology.json          # 领域术语库（自动学习 + 手动补充）
├── generation-history.json   # 生成历史（质量趋势分析）
├── user-preferences.json     # 用户偏好（交互模式、默认标签）
└── ambiguity-decisions.json  # 歧义决策记录（避免重复询问）
```

**核心机制**：
- 每次生成自动写入 `generation-history.json`（含覆盖率、优先级分布、标签）
- 歧义处理决策写入 `ambiguity-decisions.json`，后续相似歧义自动复用
- 用户修正的术语、偏好自动持久化，下次会话即刻生效

## Workflow

### Phase 0: 项目初始化（首次运行）
1. 检测项目结构（扫描 `requirements/`、`test-docs/` 等目录）
2. 创建 `.memory/` 文件夹（`memory_manager.py --action init`）
3. 从需求文档提取领域术语，存入 `terminology.json`
4. 保存用户偏好到 `user-preferences.json`

### Phase 1: 读取需求
1. 直接读取 `requirements/` 目录下所有 `.md` 文件，按文件名排序，文件间以 `---` 分隔，拼接为完整需求文本
2. 读取 `requirements/` 目录下所有图片文件（`.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.bmp`、`.svg`），与需求文本一起作为多模态输入
3. 以上述内容进入 Phase 2 解析

### Phase 2: 解析需求
1. **加载记忆并应用**：
   - 读取 `terminology.json` → 解析时统一术语，避免同义词重复
   - 读取 `ambiguity-decisions.json` → 相似歧义自动复用历史决策，跳过询问
   - 读取 `generation-history.json` → 提取历史优先级分布作为基线，识别历史常见遗漏场景类型并主动补充
   - 读取 `user-preferences.json` → 应用用户步骤粒度、标题风格等偏好
2. **提取需求ID**：识别或生成需求唯一标识
3. **结构识别**：功能模块、验收条件、业务规则
4. **系统性测试设计**（按 EP→BVA→ST→EG 顺序叠加）：
   - 等价类划分：识别所有输入的有效/无效等价类
   - 边界值提取：识别数值、长度、时间边界
   - 场景流识别：基本流、备选流、异常流
   - 错误推测补充：根据输入类型和模块风险等级触发
   - 业务规则补充：参考 [BUSINESS-RULES.md](references/BUSINESS-RULES.md)，匹配需求涉及的功能类型（列表、输入框、按钮等）自动追加对应规则用例
5. **去重扫描**：不同方法产生的用例可能语义重复（如 EP 无效类与 EG 错误推测场景重叠），合并等价用例，保留更具体的那条。
   - **状态变体去重**：若某条规则已被一个清晰的用例验证，不要再以"不同数据状态"为由生成同等验证目标的变体用例。
     - ✅ 已有「系统报表展示【系统】标签」+ 「自定义报表不展示【系统】标签」→ **不需要再生成**「仅存在自定义报表时不显示标签」「新增系统报表后自动显示标签」「删除系统报表后自定义报表仍不显示标签」，因为验证目标完全相同，只是前置数据状态不同
     - 判断标准：**新用例的验证目标（"验什么"）是否已被现有用例覆盖**，若是则丢弃；只有"验什么"不同才保留
   - **场景修饰词变体去重**：不要在已有用例的基础上，通过添加"混合时""同时存在时""共存时"等场景修饰词生成新用例，若验证目标实质相同则合并。
     - ✅ 已有「系统汇总表排在上方自定义汇总表排在下方」→ **不需要再生成**「存在系统表和自定义表混合时排序规则正确」，因为"混合场景"本就是前者的前置条件，两者验证目标完全相同
     - 判断标准：去掉修饰词后，两条用例核心断言（"系统在上、自定义在下"）是否一致，一致则合并，保留表述更明确的那条
6. **歧义检测**：识别不明确的需求描述；与 `ambiguity-decisions.json` 比对，相似歧义自动复用历史决策
7. **覆盖率预计算**：统计需求→用例映射，标记未覆盖需求
8. 参考 [PARSING-RULES.md](references/PARSING-RULES.md)

### Phase 2.5: 【检查点1】解析确认
使用 **AskUserQuestion** 确认解析结果：

```markdown
已识别 X 个模块，Y 条需求，Z 条规则

ℹ️ 标签：使用上次选择「{default_tag}」（或首次询问）

仅在发现警告或无 default_tag 时询问用户
无警告且有 default_tag 则自动继续
```

当无 `default_tag` 或发现警告时，在此阶段询问标签（适用端）。**询问前先检查需求文档是否有显式平台声明**：

- 若需求中存在类似 `tag只适用于PC端`、`仅适用于APP`、`适用端：小程序` 等**直接声明语句**，直接读取并应用，**不得询问用户**，并在摘要中提示 `ℹ️ 标签：从需求文档读取「{tag}」`
- 若需求中**没有显式声明**，则展示如下选项询问：

```markdown
本次用例适用哪些端？请输入编号或直接填写：
1. PC
2. APP
3. C端
4. PC, APP
5. 小程序
6. 其他（请说明）
```

> **重要**：标签问题在此阶段完成后，**Phase 2.6 / 2.8 及后续所有阶段不得再次询问适用端**，即使将其视为歧义也不例外。

### Phase 2.6: 歧义处理
对检测到的歧义需求逐一询问：

```markdown
需求原文：{text}
歧义类型：边界不明确 / 规则冲突 / 条件缺失
我的理解：{interpretation}

请选择：
1. 接受我的理解
2. 提供不同解释
3. 跳过此需求
4. 标记为待确认
```

- 仅询问影响 P0/P1 的关键歧义，其他歧义自动采用 AI 理解并标注

### Phase 2.8: 【检查点2】质量预审 & 生成预览
使用 **AskUserQuestion** 预览生成方案：

**质量自检（不通过则修正后再展示）**：
```
□ 覆盖率 ≥ 95%（未覆盖需求列表高亮）
□ P0 占比 10-15%
□ P1 占比 30-40%
□ 每条需求至少关联 1 种设计方法
□ 无需求外编造的场景
□ 无语义重复用例
```

```markdown
将生成 X 条用例 | 覆盖率 ZZ% | P0:X P1:X P2:X P3:X

仅在质量自检不通过时询问
通过则回车继续
```

### Phase 3: 生成文档
1. **分配优先级**：根据用例类型自动判断 P0-P3
2. **关联需求ID**：每个用例记录来源需求
3. **用例写作规范**：
   - 标题格式：`动作 + 对象 + 条件/场景`，禁用模糊词（“正常”“正确”）
   - 步骤粒度：每步只做一件事，禁止多动作合并（如"输入用户名并点击登录"应拆为两步）；步骤只写操作，禁止在步骤中使用"验证""检查""确认"等验证类动词
   - 步骤编号：每条操作以 `N. ` 起始（如 `1. 打开登录页面`），对应预期结果使用**相同编号**（如 `1. 显示账号密码输入框`），编号从 1 开始连续递增，steps 与预期结果数组长度必须相等
   - 预期结果：必须可验证，包含具体数据/状态，禁用"系统正常处理""正常显示"等模糊描述；一个步骤有多个验证点时用逗号连接写在同一条预期结果中，不拆分步骤
   - 前置条件：仅当需要特定环境准备时填写，避免写"用户已登录"这类显而易见的内容
   - 业务规则扩充（BUSINESS-RULES.md）属于合理推断范围，不受"无编造"约束限制
   - 应用 `user-preferences.json` 中存储的步骤粒度、标题风格偏好
4. 将用例组织为 JSON 数组，写入项目临时文件 `tmp/cases_<时间戳>.json`（如 `tmp/cases_20260225143022.json`），目录不存在时自动创建
  - 时间戳必须为 **14 位**：`YYYYmmddHHMMSS`（正则：`^\d{14}$`）
  - 禁止仅日期命名（如 `tmp/cases_20260226.json`）
4. 调用 `scripts/generate_xmind.py -f tmp/cases_<时间戳>.json` 生成 XMind 文件，输出路径固定为 `test-docs/testcases_<时间戳>.xmind`

### Phase 4: 更新记忆（自学习闭环）

> 完整学习规则见 [LEARNING-RULES.md](references/LEARNING-RULES.md)

1. **生成历史**：写入 `generation-history.json`，包含覆盖率、优先级分布、用例数、标签、来源文件
2. **歧义决策**：将 Phase 2.6 中用户的歧义处理决策写入 `ambiguity-decisions.json`，后续相似歧义自动复用
3. **新术语**：如解析中发现新术语，更新 `terminology.json`
4. **用户偏好**：保存默认标签等到 `user-preferences.json`
5. **质量趋势**：与历史记录对比，生成趋势摘要（如覆盖率是否提升、用例数变化）

### Phase 5: 用户反馈学习（生成后可选）

用户对生成结果提出修改时，自动触发学习：

| 反馈类型 | 示例 | 学习动作 |
|----------|------|----------|
| 纠正错误 | “这条用例逻辑不对” | 重新生成 + 记录歧义模式到 `ambiguity-decisions.json` |
| 删减用例 | “P2 太多了” | 询问“是否调整优先级分布作为默认？”→ 写入 `user-preferences.json` |
| 补充场景 | “还缺并发场景” | 增补用例 + 记录为常见遗漏到 `generation-history.json` |
| 修改术语 | “这里应该叫 XXX” | 询问“是否记住？”→ 写入 `terminology.json` |
| 调整步骤 | “步骤太细了，合并一下” | 询问“是否记住这个粒度偏好？”→ 写入 `user-preferences.json` |

## 输出格式

### 测试用例 XMind

固定节点结构（符合 XMind 导入规范）：

```
根节点（项目名称）
  └── 模块（最多8层）
        └── tc-p0: 用例标题  /  tc: 用例标题（无优先级时）
              ├── pc: 前置条件（非必填）
              ├── 步骤1
              │     └── 预期结果1
              ├── 步骤2
              │     └── 预期结果2
              └── tag: 标签1,标签2（非必填）
```

AI 生成用例时输出的 JSON 字段：

| 字段 | 必填 | 说明 |
|------|------|------|
| `模块` | ✅ | 数组，最多8层，如 `["登录", "账号密码"]`。**末级目录按功能区域分组，不以单个功能点命名**，规则见下方「模块分组规则」 |
| `用例标题` | ✅ | 格式：`动作 + 对象 + 条件/场景`，如“输入正确账号密码登录成功” |
| `优先级` | ✅ | P0/P1/P2/P3，影响节点前缀 |
| `需求ID` | ✅ | 关联的需求标识，如 `REQ-001`、`MOD_LOGIN_001` |
| `设计方法` | ✅ | `EP`/`BVA`/`ST`/`EG` 之一或多个，如 `["EP", "BVA"]` |
| `前置条件` | ❌ | 生成 `pc:` 子节点 |
| `步骤` | ✅ | `[{"操作": "1. ...", "预期": "1. ..."}]`，操作与预期均以数字序号起始，同一步骤编号一致 |
| `标签` | ✅ | 测试端标识，多端用逗号+空格分隔，如 `PC`、`APP`、`PC, APP` |

**模块分组规则**：

末级目录必须按**功能区域**归类，而非按单个功能点各自建目录。同一功能区域的所有用例共用同一个末级目录节点。

| 功能区域 | 末级目录名 | 包含的用例范围 |
|----------|-----------|---------------|
| 列表展示、排序、标签、筛选、搜索 | `列表` | 列表页面上能看到的所有内容 |
| 新增/创建表单 | `新增` | 点击新增按钮后的页面/弹窗 |
| 编辑表单 | `编辑` | 编辑页面/弹窗相关用例 |
| 详情页 | `详情` | 查看详情页面相关用例 |
| 删除操作 | `删除` | 删除相关用例 |
| 导出功能 | `导出` | 导出相关用例 |
| 导入功能 | `导入` | 导入相关用例 |
| 权限控制 | `权限` | 权限相关用例 |

✅ **正确示例**（汇总表需求含标签展示+排序逻辑，全部归入「列表」）：
```json
{"模块": ["汇总表", "列表"], "用例标题": "系统报表展示【系统】标签"}
{"模块": ["汇总表", "列表"], "用例标题": "自定义报表不展示【系统】标签"}
{"模块": ["汇总表", "列表"], "用例标题": "系统汇总表排在上方自定义汇总表排在下方"}
```

❌ **错误示例**（为每个功能点各建一个目录，导致目录过多）：
```json
{"模块": ["汇总表", "系统报表标签"], "用例标题": "系统报表展示【系统】标签"}
{"模块": ["汇总表", "自定义报表标签"], "用例标题": "自定义报表不展示【系统】标签"}
{"模块": ["汇总表", "列表排序"], "用例标题": "系统汇总表排在上方自定义汇总表排在下方"}
```

**JSON 完整示例**：
```json
{
  "模块": ["用户登录", "账号密码登录"],
  "用例标题": "输入正确账号密码登录成功",
  "优先级": "P0",
  "需求ID": "REQ-001",
  "设计方法": ["ST"],
  "前置条件": "用户已注册账号，且处于未登录状态",
  "步骤": [
    {"操作": "1. 打开登录页面", "预期": "1. 显示账号、密码输入框和登录按钮"},
    {"操作": "2. 输入正确的账号和密码", "预期": "2. 输入内容正常显示，密码为密文"},
    {"操作": "3. 点击登录按钮", "预期": "3. 登录成功，跳转到首页"}
  ],
  "标签": "C端"
}
```

**标签取值规则**：
- **显式声明优先**：需求文档中若有明确的平台声明语句（如 `tag只适用于PC端`、`适用端：APP`），直接读取该值写入标签，**无需询问用户**。
- **禁止隐式推断**：需求中未显式声明平台时，不得根据功能描述（如"用户在PC端操作"、"移动端约课"等上下文）自动推断标签；必须在 Phase 2.5 询问用户。
- 在 Phase 2.5 解析确认阶段**统一处理一次**，**全程只处理一次，不得在 Phase 2.6、Phase 2.8 或生成阶段重复询问**。
- 将用户输入（包括编号对应的文字）**原样**写入每条用例的 `标签` 字段，**严禁**对用户答案做任何翻译、展开或同义替换（例如：用户填 `C端` 就写 `C端`，不得改为 `PC, APP`；用户填 `3` 就写 `C端`，不得改为别的）。
- 所有用例共用同一答案，除非某条用例有用户明确指定的例外。

## 脚本调用

### 生成 XMind
```bash
# 时间戳格式：YYYYmmddHHMMSS
TIMESTAMP=$(date +%Y%m%d%H%M%S)
mkdir -p "${SKILL_ROOT}/tmp"
# 先将用例 JSON 写入临时文件
cat > "${SKILL_ROOT}/tmp/cases_${TIMESTAMP}.json" << 'EOF'
[{...}]
EOF
# 再生成 XMind
python3 "${SKILL_ROOT}/scripts/generate_xmind.py" \
  --title "项目名称" \
  --output "test-docs/testcases_${TIMESTAMP}.xmind" \
  -f "${SKILL_ROOT}/tmp/cases_${TIMESTAMP}.json"
```

### 管理记忆
```bash
# 初始化
python3 "${SKILL_ROOT}/scripts/memory_manager.py" \
  --action init \
  --project "${SKILL_ROOT}"

# 记录本次生成历史（Phase 4 使用）
python3 "${SKILL_ROOT}/scripts/memory_manager.py" \
  --action add-record \
  --project "${SKILL_ROOT}" \
  --data '{"type":"test_case","source":"requirements/xxx.md","output":"test-docs/xxx.xmind","case_count":40,"coverage_rate":"100%"}'
```

## 自学习闭环

> 完整学习规则见 [LEARNING-RULES.md](references/LEARNING-RULES.md)

**越用越准的核心机制**：

```
写入端（Phase 4/5）                    读取端（Phase 2）
─────────────────────                ─────────────────────
生成历史 ───→ generation-history.json ──→ 优先级基线 + 遗漏场景补充
歧义决策 ───→ ambiguity-decisions.json ─→ 相似歧义自动复用
新术语   ───→ terminology.json ────────→ 术语统一 + 缩写展开
用户偏好 ───→ user-preferences.json ────→ 标签/粒度/风格自动应用
用户反馈 ───→ 分发到以上各文件 ──────────→ 下次生成自动避免相同问题
```

**记忆命令**：`"更新术语表"` / `"清除记忆"` / `"查看偏好"` → 调用 `memory_manager.py` 对应 action。

## 约束

### 质量底线
- **需求追溯**：所有用例必须关联需求ID，不允许悬空用例
- **方法标记**：所有用例必须标记至少 1 种设计方法
- **优先级分布**：P0: 10-15%, P1: 30-40%，P2 补足剩余，P3 ≤ 20%（异常时 Phase 2.8 拦截）
- **覆盖率**：≥ 95%（未达标时 Phase 2.8 高亮警告）
- **无编造**：不凭空编造需求中不存在的场景
- **无冗余**：不同设计方法产生的语义重复用例必须合并

### 标签规则
- 需求有显式平台声明时直接读取，**无需询问**
- 无显式声明时在 Phase 2.5 询问一次，**全程不再重复询问**
- 用户输入**原样写入**，禁止翻译、展开或同义替换

### 交互规则
- 仅在发现问题/异常时询问用户
- 无异常时自动继续执行

### 其他
- 遵循项目已有命名规范
- 文件命名中的 `<时间戳>` 必须使用 `YYYYmmddHHMMSS`（14 位），不得使用仅日期（8 位）格式
- 默认输出中文，除非项目配置为其他语言
- `.memory` 文件夹应加入 .gitignore
- **禁止复用 tmp/ 缓存**：每次生成均从 Phase 1 重新开始，不得读取 `tmp/` 中已有的 JSON 文件跳过生成步骤

## 参考文档

- [INTERACTION-PATTERNS.md](references/INTERACTION-PATTERNS.md) - 交互模式与问题模板
- [TEST-DESIGN-METHODS.md](references/TEST-DESIGN-METHODS.md) - 核心4种测试设计方法详解
- [TRACEABILITY.md](references/TRACEABILITY.md) - 需求追溯矩阵规范
- [TEST-PRIORITY.md](references/TEST-PRIORITY.md) - 优先级与回归分类
- [PARSING-RULES.md](references/PARSING-RULES.md) - 需求解析规则
- [MEMORY-SCHEMA.md](references/MEMORY-SCHEMA.md) - 记忆文件结构
- [LEARNING-RULES.md](references/LEARNING-RULES.md) - 学习规则
- [BUSINESS-RULES.md](references/BUSINESS-RULES.md) - 业务测试规则（列表、输入框、按钮等通用场景）