---
name: test-case-writing
slug: test-case-writing
displayName: 测试用例设计
version: 0.6.0
description: 从需求文档、API 文档、Bug 报告或代码仓库产出可执行的手动测试用例（markmap）时使用——代码优先：索取仓库、先代码审查找潜在 bug 再写用例，并抽取机器可读 Schema。不用于：需求建模（requirement-analysis）、测试策略（test-strategy）、独立审查（test-case-review）、自动化脚本（automated-e2e-testing / api-testing）。
---
# 测试用例编写
从需求模型（或原始输入源）与代码，产出**人看得懂、能执行**的手动用例文件（markmap），并抽取机器可读的 Test Case Schema 供下游 Skill 消费。
**落盘产物**：`{项目}/测试用例_markmap.md`（唯一人工维护源）+ `{项目}/测试用例.schema.yaml`（由 markmap 单向抽取，规则见 `../core/schema-extraction.md`）。
## When to Use
- **有代码仓库**，需基于实际实现编写用例（代码优先，首选场景）
- 给定需求文档/PRD、技术设计方案、API 文档，需要编写测试用例
- 给定 Bug 报告，需要编写回归测试用例
- 需求变更时，增量更新已有测试用例
## When NOT to Use
- 端到端测试整个需求（理解→策略→用例→执行→报告）→ 用 `qa` skill 编排
- 需要系统性需求建模（目标/范围/规则/异常/依赖/不明确项）→ 用 `requirement-analysis` skill；本 skill 只做轻量输入研读
- "这个功能应该怎么测"（范围/类型/深度/优先级的策略决策）→ 用 `test-strategy` skill
- **事后独立审查**存量或他人写的用例 → 用 `test-case-review` skill；本 skill 只做写时自审（阶段四）
- 编写自动化测试代码 → 用 `automated-e2e-testing`（UI）或 `api-testing`（接口）skill
- 代码变更后判断回归范围 → 用 `regression-testing` skill；本 skill 只负责用例文件的增量修改
- 既无代码仓库、也无任何需求/设计文档可参考 → 无法开工
## 工作流程
### 阶段〇：主动索取代码仓库（开工第一件事）
启动测试用例编写前，**主动向用户索要被测项目代码仓库**：
- **索取内容**：① 仓库地址（本地路径或远程 URL）；② 被测分支/tag；③ 本次改动范围（PR/MR 链接或 `...` diff 范围，无则默认全量）
- **提问模板**：
> 🔍 为提升用例准确性，请提供被测项目代码仓库地址与被测分支（若有本次改动的 PR/diff 范围也请给出）。代码将作为功能事实基线，文档作为对照——基于实际实现编写的用例能发现文档与实现的不一致、定位潜在 bug，纯文档模式则无法做到。
- **用户确认无代码 → 降级纯文档模式**：提示「将基于文档编写，准确性受限：无法发现文档与实现的不一致、无法定位潜在 bug、无法核实风险点是否有下游消费」，跳过「代码探索与全面审查」与附录 Cx/Dn 产出。
> 代码模式与文档模式的差异贯穿后续所有阶段，每个阶段都会标注。
### 阶段一：输入研读 + 范围界定（代码优先）
从输入源中提取所有可测试点，同时识别平台、角色和测试边界。**代码是静态事实的最高来源**（裁决规则见 `../core/evidence.md`）——有代码时以实现为准（测准声明），文档降为对照。
#### 输入源与关注重点
| 输入源 | 重点关注 |
|--------|---------|
| **代码仓库（最高优先级）** | 实际实现逻辑、数据结构、错误处理、与文档偏差、潜在 bug、改动范围（diff） |
| 需求文档/PRD | 功能点列表、边界说明、用户角色、业务规则 |
| 技术设计方案 | 数据模型、接口签名、状态流转、缓存策略、消息格式 |
| API 文档 | 接口参数、必填/选填、返回值、错误码、鉴权方式 |
| Bug 报告 | 复现步骤、根因分析、修复范围（回归用例） |
| FAQ/会议纪要 | 隐含需求、设计决策、边界限制 |
**关键提醒**：FAQ 中的每个问答都是潜在的边界用例；"非目标"声明中的限制需要对应的验证用例。
**已有上游产物时直接消费**：存在 `需求模型.md`（requirement-analysis 产出）则以其为结构化输入，澄清记录直接引用，不再重复建模；存在 `测试策略.md`（test-strategy 产出）则按其范围/深度/优先级要求执行，Risk Map 中的风险编号（R1、R2…）作为 `risk_ref` 挂到对应用例。存在 type_scope（类型域决策）时按 `../core/test-type-matrix.md` 第 12 节消费方式映射执行：**用例型**轴（业务安全/可靠/并发/兼容，standard 及以上）产对应类型用例——type 用 security / reliability / concurrency / compatibility，名称行加 `[并发]` 等标签（i18n/迁移/契约轴用 type: functional + 标签）；**脚本型**轴（性能/视觉，standard 及以上；无障碍任意档位产 axe 扫描任务与违规清单）不产手动用例，导读区标注"执行物走专项脚本"并留给执行策略裁决；**审查型**（light 档）发现并入附录 Cx 审查清单；exclude 轴不产出。
#### 识别范围
在读输入源时同步记录：**平台/端**（管理后台、用户端、后端 API、第三方回调）、**用户角色**（每个角色能看到什么、能做什么、不能做什么）、**测试边界**（本期范围 vs 不测的 vs 依赖项）。
#### 受众与执行模型判定（开工必做，决定用例写法）
被测功能有无 UI，直接决定用例正文怎么写。开工时先判定，必要时向用户确认一句：
- **有 UI 的功能**（网页后台、App、小程序、H5 页面）→ 测试工程师**独立执行**。操作步骤写具体的 UI 动作（进入哪个页面、填哪个字段、点哪个按钮）；预期结果写页面上能观察到的现象。
- **无 UI 的后端功能**（数据 stage、API 接口、SDK 迁移、定时任务、消息队列消费）→ 测试工程师**无法独立执行**，写成**「测试-开发协作清单」**：操作步骤标「请开发执行」（给开发具体的数据与触发方式）；预期结果标「请开发反馈」（反馈实际值/截图）；验证方式标「开发查库/查日志反馈」。**开工即问**：向用户确认执行模型（"测试能否独立执行？后端功能通常需开发代跑 + 查库反馈，对吗？"）。
无论哪种模型，**用例正文都必须用业务语言**（格式细则见 `../core/case-format.md`，阶段三执行）。
#### 代码探索与全面审查（代码模式专属，有代码时必做）
在文档研读基础上执行 4 步，建立项目地图并发现潜在 bug。这步产出后续用例的「代码依据」与缺陷记录基础。
**步骤 1 — 定位与概览**：确认仓库路径/被测分支/改动范围；读 README、路由表、入口文件、配置文件，建立项目地图。
**步骤 2 — 改动盘点**：`git diff ... --stat` 列改动文件，逐个分类：🆕 新建（新功能主线，全面覆盖）、✏️ 修改（回归风险源，重点覆盖原行为是否保持 + 新行为）、🗑️ 删除（功能下线，验证下线后无残留入口）、💀 死代码（未挂载路由/未被引用，标记可忽略）。产出「改动文件 → 影响模块 → 回归用例」映射（记入附录「改动文件映射」）。
**步骤 3 — 全面代码审查（派 Explore 代理矩阵，始终执行）**：
> 按改动文件数/子系统切分，派 1–3 个只读 Explore 代理并行；每个代理聚焦一类发现。代理 prompt 框架示例：
> 「审查 `{仓库路径}` `{分支}` 的 {文件/子系统列表}，针对以下清单逐项查找，每条发现附 `文件:行` 证据并标注确信度：① 潜在 bug；② 文档与实现不一致；③ 死代码/死声明；④ 疑似高风险但可能无下游消费（需核实是否证伪）。只读，不修改。」
审查清单**执行 `../core/coverage.md` 第 7.1 节「代码审查发现模式清单」全部 13 项**（null/undefined 未兜底、边界未防护、状态死锁、并发竞态、错误静默吞掉等），不是可选参考。
**步骤 4 — 风险分级 + 转化**：
- **高风险点 D1-Dn**：按 `../core/risk-model.md` 评级（Impact × Likelihood → Critical/High/Medium/Low），每条映射一条回归用例
- **潜在 bug → 缺陷记录 Cx**：编号 + 现象 + 证据（E0–E4 等级 + `文件:行`，格式见 `../core/evidence.md`）+ 处置（主线验证 / 专项验证 / 待实测确认 / 已证伪 / 后端范围）
- **文档偏离**：记入附录「文档偏离对照」；**死代码**：标注可忽略，不写用例
#### 输入源缺失时的降级策略
- 只有 PRD 无设计文档 → 不检查"PRD 与技术设计不一致"，审查阶段跳过"技术实现细节"维度
- 只有 API 文档 → 以接口参数和错误码为主要输入源，重点覆盖输入校验和错误处理（方法见 `../core/methods/data-driven.md`）
- 只有 Bug 报告 → 聚焦回归测试，围绕 Bug 涉及的功能区域展开
### 阶段二：需求澄清
文档研读完成后，**必须先检查是否存在模糊、不完整或矛盾之处**，不得自行假设。
**触发与扫描的单一权威源在 `../core/clarify-pattern.md`（此时加载）**：基础触发按其「何时必须问」，深度扫描按其「需求歧义九类漏网模式」A–I 逐类过筛（2026-08-23 R2 收敛：本阶段不再维护独立清单）。
**代码模式特有触发**（文档模式无此项）：**文档与代码不一致**——数据结构、字段是否提交、流程顺序、默认值——默认以代码为准（测准声明），列出两边原文并询问"偏离是否确认为非缺陷？"
提问格式与裁决落盘规则统一按 `../core/clarify-pattern.md`：逐条独立成卡、给出建议选项、用户答复记入澄清记录。
**输出**：无需澄清 → 一句话确认"需求已足够清晰"（并入导读，**不单列澄清章节、不产出仪式性清单**——干净材料上的澄清仪式是纯输出预算开销，2026-08-23 修复：评测实测该仪式开销曾致净收益 −13.5pp），直接进入阶段三；有问题 → 列出问题清单，**等待用户回复后再进入阶段三**；后续编写中发现新问题 → 随时补充提问，不硬写。澄清记录对齐需求模型的 `open_questions` 字段（用户裁决具有最终裁决力，见 `../core/evidence.md` 裁决规则）。
### 阶段三：用例编写
**直接输出最终用例文件，不产出任何中间文件（无 outline、无矩阵表格）。** 使用 markmap 格式（Markdown 标题层级 + 列表）。
#### 逐模块推进与交付核对（硬约束）
按模块逐个编写：**每个模块标题下有用例后才能进入下一模块**（不要求先产出完整骨架——直接逐模块写）。**交付前对照输入材料逐模块核对**：输入的每个功能模块（含 FAQ、异常处理、权限/角色、定时任务等易漏段落）在产出中都有非空模块且有用例；空模块必须补齐，或在待澄清清单中显式记录阻塞原因后才能定稿。**多模块输入只完成第一个模块就交付 = 最严重的交付缺陷。**
**维度核对（逐条，与模块核对同级；2026-08-23 迭代修复后引入并复验）**——模块齐全但维度缺失同样拦截定稿：
1. **主流程不可省**：每个功能的最短正向主路径（创建/提交/发起这类最简单操作）至少 1 条用例——"太显然"不是省略理由；
2. **时间双侧**：每条时间类规则（时限/有效期/超时/自动触发）至少 1 条双侧边界用例（边界前一拍可成功 / 到达后进入另一态）——**时限数值已在材料中给定时同样必须双侧**（如"30 分钟超时"→第 29 分 59 秒可支付、第 30 分 00 秒被关闭；"7 天自动确认"→满 7×24h 前一秒可手动确认、到达后自动确认）。给定数值不等于已验证，恰在边界时刻的行为是独立用例；
3. **负向底数**：状态机型输入，非法转换与终态约束各至少 1 条负向用例。
> 纪律依据：把「完整性」从阶段 4B 的后置审查纪律改为交付前的显式核对项——弱执行环境下后置纪律可能被跳过，逐模块核对拦住「写一个模块就收工」的早停。修复依据（2026-08-23 评测轮逐点分析）：模块核对拦住了模块坍缩，但弱模型出现**维度坍缩**——两任务主流程用例丢 2/2、边界维度零增益（44%→44%、11%→0%）——模块全而维度空，故核对必须下探到维度。
#### 输出预算纪律（硬约束，2026-08-23 R3）
输出预算有限（32K token 级），**仪式与用例争预算——用例优先**：
- **用例数封顶**：`min(可测点数 × 1.5, 80)` 条为上限；超出时按 P0 > P1 > P2 收缩，不稀释单条质量（四段式不省略）去凑数量；
- **测试数据守约束**：用例中的测试数据（唯一名、账号、订单号等）须满足材料声明的字段约束（maxLength/枚举/格式）——生成的数据模板总长按约束上限预留余量，不顶格（实测自伤案例：API 任务唯一名模板 22 字符撞契约 maxLength 20，整条用例因 NAME_INVALID 失败）；参数矩阵组合还须满足**跨字段业务规则**（如"使用门槛不能低于面额"、"开始时间早于结束时间"）——逐参数独立变化时每格组合回检全部规则，违反规则的格子改取合法值或拆为显式负向用例（实测自伤案例：金额顶格 1000 配低于面额的门槛，被业务规则正确拒绝而用例期望成功）；
- **附录只在代码模式产出**，纯文档模式不产 Cx/Dn/改动映射/代码证据清单（无代码可引）；
- **导读压缩**：四件套每件 ≤3 行；术语表只收正文实际出现的术语；
- 单条用例超出四段式框架的内容（背景解释、方法论证）一律删除——细节属于澄清记录或附录，不属于用例。
> 依据：api-testing 的输出预算纪律（parametrize 收敛/行数上限）是全集唯一实测防截断手段；实测截断事故（32K 输出只剩 `{`）与澄清仪式开销（净收益 −13.5pp）同源——预算意识必须从 api-testing 推广到本 skill。
#### 设计方法选择（此时加载 `../core/testing-principles.md`）
按功能特征选方法，不强制状态机：明显状态流转 → State Machine；输入输出型 → 等价类+边界值；权限系统 → Role×Action×Resource；API → 参数矩阵；复杂业务流程 → Workflow；数据转换 → Input→Transform→Output；历史 Bug 较多 → 回归聚焦。
#### 组织方式与格式（此时执行两项硬约束文件，不是可选参考）
- **组织**：按状态流转和操作生命周期组织模块（方法执行 `../core/methods/state-machine.md`：提取状态机 → 按状态节点分模块 → 每条边一个用例 + 非法转换/竞态/逆向边 → 横切关注点独立模块）。无状态流转的功能按 `../core/methods/boundary.md` / `../core/methods/data-driven.md` / `../core/methods/permission.md` 对应方法组织，按输入源特征加载。
- **格式**：**执行 `../core/case-format.md` 全部格式硬约束**——文件头部导读四件套、正文零代码内部、TC 编号（`TC-{模块号}-{序号}`，P0 加 `（SMOKE-n）`）、四段式/协作五段式、前置去冗余、嵌入具体数据（禁占位符）、页面可达性、异步判定时限、断言范围 ≤ 验证强度、可测试性标注、测准声明（代码模式）、附录区规范（Cx/Dn/代码证据清单/文档偏离/改动文件映射，与正文物理隔离）。拼装起点模板见 `templates/markmap_template.md`。
#### 优先级规则（严格执行）
在用例名称行标注 `[P0]`/`[P1]`/`[P2]`，不标注时默认 P1。
**P0（冒烟）**— 满足以下**全部**条件：主流程的核心路径；失败则整个功能不可用；**P0 自检**（逐条执行）：如果这条用例失败，用户能否完成核心操作？答案为"否"才是 P0。
**P1（常规）**：正常功能验证 + 常见异常处理。**P2（边界）**：极端输入、低频场景、性能指标、需特殊环境。
存在 Risk Map 时按 `../core/risk-model.md` 的映射建议执行（Critical → 必有 P0，High → P0/P1，Medium → P1，Low → P2/按需），偏离需说明理由。
### 阶段四：审查（写时抽查，2026-08-23 R1 降级：全检 → 抽查）
> 降级依据：全检式 4A/4B 在弱模型×输出预算下是伪执行（实测 exec 0.5、维度零增益——核对付了
> 预算没换到行为）。**覆盖的执行点已迁移到阶段三交付核对（模块核对+维度核对，生成路径内联）**，
> 本阶段只做轻量抽查，不回到原文档逐段比对（该指令是 thinking 预算杀手，已废除）。
#### 4A：模块写完后的抽查（只做两条）
1. **抽查主流程**：该模块最短正向主路径的用例是否存在（与维度核对第 1 条同一口径，此处只是复查）
2. **抽查单一职责**：抽 2-3 条用例确认只测一个点、预期唯一
#### 4B：全局抽查（全部模块完成后，只做三条）
1. **FAQ/非目标抽查**：FAQ 每条至少 1 条用例（遗漏高发区）
2. **二阶交叉抽查**（中型以上项目）：`../core/testing-principles.md` 第 3 节三项中抽 1 项执行（写入路径×校验 / 失败×重试 / 标识×重复）
3. **跨模块重复检查**：重复用例合并、TC 编号连续
> **已废除**：逐文档溯源全检、coverage.md 19 维全检、多角色四视角全检——这些维度的**设计知识**
> 仍在 `../core/coverage.md`（按需参考，供强模型/大项目加深），但不再是交付前的强制执行项；
> 强制执行项只有阶段三交付核对的模块核对+维度核对。
#### 审查输出
**直接在用例文件中补充遗漏和调整**，不产出独立审查报告。只在用例文件末尾（附录之后）按 `../core/case-format.md` 第 10 节格式追加「审查记录」。
### 阶段五：定稿 + Schema 抽取
1. **可读性自检**：**执行 `../core/executability.md` 全部检查项**（零上下文新人复述、术语表核对、正文零代码自检、执行性确认、判定时限核查），不是可选参考
2. **Schema 抽取**：从 markmap 单向抽取 `测试用例.schema.yaml`——字段定义、抽取规则与 YAML 转义纪律统一在 `../core/schema-extraction.md`（此时加载）；抽取后运行 `../core/scripts/validate_schema.py 测试用例_markmap.md 测试用例.schema.yaml --strategy {策略路径}/测试策略.md` 校验（YAML 合法性 + TC 编号一致性 + 占位符检查 + **风险覆盖门禁**：Risk Map 中全部 Critical/High 风险须被 ≥1 条用例的 risk_ref 反向覆盖，零覆盖即门禁失败；上游无策略文件则省略该参数。有代码仓库可叠加 `--repo-root` 抽查 code_refs 指涉真实性）
3. 文件命名：`{项目名}/测试用例_markmap.md` + `{项目名}/测试用例.schema.yaml`
## Schema 双轨原则
markmap 是给人的交付物与**唯一人工维护源**；Schema 是机器可读元数据层，由本 skill 从 markmap **单向抽取**，作为 Skill 间流转接口（`test-case-review` / `regression-testing` / 执行层消费）。**不要求人维护两份**，Schema 永远可由 markmap 再生；markmap 修改后必须重新抽取。存量 markmap 按同规则抽取即可，不需人工重写。
## 增量更新流程
需求变更时增量更新已有用例（而非从零重写）：
1. **影响分析**：确定变更影响哪些模块、哪些用例（直接用例 + 下游依赖 + 状态流转受影响的边 + 数据模型变更影响的查询/校验）。代码模式：基于 `git diff` 盘点改动文件，按附录「改动文件映射」分类定位受影响用例
2. **标记受影响用例**：按 TC 编号列出，标记 `[已变更]`、`[已废弃]`、`[需新增]`（Schema 的 `status` 同步）
3. **更新用例**：新增用追加编号，废弃用 `~~删除线~~` + `[已废弃-原因]`
4. **局部审查**：对变更模块执行 4A + 涉及变更的跨模块检查
5. **重新抽取 Schema**（并运行 `../core/scripts/validate_schema.py` 校验），输出变更报告（格式见 `../core/case-format.md` 第 10 节）
## Common Mistakes
| 错误 | 后果 | 正确做法 |
|------|------|---------|
| 不做需求澄清直接写用例 | 用例基于错误假设，浪费返工 | 发现模糊立即提问 |
| 有代码却不读代码，只靠文档 | 用例基于错误假设（文档常与实现不符） | 有代码必读代码，以实现为准（测准声明） |
| 产出不可执行的用例（占位符/虚构入口/无时限异步） | 死用例占空间，执行者无法开工 | 执行 `../core/executability.md` 全部硬标准 |
| 用例正文堆代码内部（`文件:行`/SDK 符号/错误码常量） | 测试工程师看不懂、无法执行 | 正文纯业务语言，代码证据隔离到附录（`../core/case-format.md`） |
| 无 UI 后端功能照搬 UI 用例写"操作步骤" | 测试无法独立执行，步骤悬空 | 开工判执行模型；无 UI 写协作五段式 |
| 缺导读区（术语/环境账号/图例） | 没接触过项目的人第一步就卡住 | 导读四件套，未知信息列 TODO 标注找谁拿 |
| 校验用例只挂创建路径 | 编辑/重提路径绕过校验的 bug 漏测（高发） | 二阶交叉检查：写入路径 × 校验规则逐格核对 |
| 异步用例无判定时限 | 通过/失败由执行者自定 | 预期结果写明时限，无依据则列澄清问题 |
| 轻信文档/口头描述，风险点未核实代码 | 写入伪用例（如已证伪的"门控死锁"） | 每个风险点核实下游消费，评级按 `../core/risk-model.md` 挂证据 |
| 只测功能不查潜在 bug | 遗漏缺陷验证，bug 上线才暴露 | 全面代码审查（`../core/coverage.md` 7.1 模式清单），潜在 bug 转 Cx |
| P0 泛滥或缺失 | 冒烟测试失去筛选意义 | 逐条执行 P0 自检问题 |
| 忽略 FAQ/非目标声明 | 遗漏边界用例 | FAQ 每条至少 1 条用例 |
## 与其他 skill 配合
- **上游**：`qa`（端到端编排）→ `requirement-analysis`（需求模型）→ `test-strategy`（策略 + Risk Map）→ 本 skill。上游产物存在则直接消费；不存在则内联轻量版本（够用即可）
- **下游**：`test-case-review`（事后独立审查）→ `automated-e2e-testing` / `api-testing`（消费用例与 Schema 执行）→ `regression-testing`（消费 `code_refs` / `risk_ref` 做影响面分析）
- 共享的方法论与格式标准在 `core/`（设计方法 `core/methods/`、覆盖检查表、用例格式、Schema 抽取规则）；本 skill 私有资产仅 `templates/markmap_template.md`（拼装起点）
- 本 skill 产出**手动测试用例 + Schema**；审查发现的**疑似**缺陷记 Cx（待验证），已确认 Bug 的根因分析归 `bug-analysis`