test-case-writing

Files (2)

• SKILL.md
• markmap_template.md · templates/

SKILL.md (first lines)

# 测试用例编写

从需求模型（或原始输入源）与代码，产出**人看得懂、能执行**的手动用例文件（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 只负责用例文件的增量修改
- 既无代码仓库、也无任何需求/设计文档可参考 → 无从建模与写用例：先走 `exploratory-testing` 探索建立系统理解，或向用户索取输入材料

## 工作流程

### 阶段〇：主动索取代码仓库（开工第一件事）

启动测试用例编写前，**主动向用户索要被测项目代码仓库**：

- **索取内容**：① 仓库地址（本地路径或远程 URL）；② 被测分支/tag；③ 本次改动范围（PR/MR 链接或 `<base>...<head>` 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 时**，向用户确认一句：

- **有 UI 的功能**（网页后台、App、小程序、H5 页面）→ 测试工程师**独立执行**。操作步骤写具体的 UI 动作（进入哪个页面、填哪个字段、点哪个按钮）；预期结果写页面上能观察到的现象。
- **无 UI 的后端功能**（数据 stage、API 接口、SDK 迁移、定时任务、消息队列消费）→ 测试工程师**无法独立执行**，写成**「测试-开发协作清单」**：操作步骤标「请开发执行」（给开发具体的数据与触发方式）；预期结果标「请开发反馈」（反馈实际值/截图）；验证方式标「开发查库/查日志反馈」。**开工即问**：向用户确认执行模型（"测试能否独立执行？后端功能通常需开发代跑 + 查库反馈，对吗？"）。

无论哪种模型，**用例正文都必须用业务语言**（格式细则见 `../core/case-format.md`，阶段三执行）。

#### 代码探索与全面审查（代码模式专属，有代码时必做）

在文档研读基础上执行 4 步，建立项目地图并发现潜在 bug。这步产出后续用例的「代码依据」与缺陷记录基础。

**步骤 1 — 定位与概览**：确认仓库路径/被测分支/改动范围；读 README、路由表、入口文件、配置文件，建立项目地图。

**步骤 2 — 改动盘点**：`git diff <base>...<head> --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 逐类过筛（本阶段不再维护独立清单）。

**代码模式特有触发**（文档模式无此项）：**文档与代码不一致**——数据结构、字段是否提交、流程顺序、默认值——默认以代码为准（测准声明），列出两边原文并询问"偏离是否确认为非缺陷？"

提问格式与裁决落盘规则统一按 `../core/clarify-pattern.md`：逐条独立成卡、给出建议选项、用户答复记入澄清记录。

**输出**：无需澄清 → 一句话确认"需求已足够清晰"（并入导读，**不单列澄清章节、不产出仪式性清单**——干净材料上的澄清仪式是纯输出预算开销，实测曾致整体净收益为负），直接进入阶段三；有问题 → 列出问题清单，**等待用户回复后再进入阶段三**；后续编写中发现新问题 → 随时补充提问，不硬写。澄清记录对齐需求模型的 `open_questions` 字段（用户裁决具有最终裁决力，见 `../core/evidence.md` 裁决规则）。

### 阶段三：用例编写

**直接输出最终用例文件，不产出任何中间文件（无 outline、无矩阵表格）。** 使用 markmap 格式（Markdown 标题层级 + 列表）。

#### 逐模块推进与交付核对（硬约束）

按模块逐个编写：**每个模块标题下有用例后才能进入下一模块**（不要求先产出完整骨架——直接逐模块写）。**交付前对照输入材料逐模块核对**：输入的每个功能模块（含 FAQ、异常处理、权限/角色、定时任务等易漏段落）在产出中都有非空模块且有用例；空模块必须补齐，或在待澄清清单中显式记录阻塞原因后才能定稿。**多模块输入只完成第一个模块就交付 = 最严重的交付缺陷。**

**维度核对（逐条，与模块核对同级）**——模块齐全但维度缺失同样拦截定稿：

1. **主流程不可省**：每个功能的最短正向主路径（创建/提交/发起这类最简单操作）至少 1 条用例——"太显然"不是省略理由；
2. **时间双侧**：每条时间类规则（时限/有效期/超时/自动触发）至少 1 条双侧边界用例（边界前一拍可成功 / 到达后进入另一态）——**时限数值已在材料中给定时同样必须双侧**（如"30 分钟超时"→第 29 分 59 秒可支付、第 30 分 00 秒被关闭；"7 天自动确认"→满 7×24h 前一秒可手动确认、到达后自动确认）。给定数值不等于已验证，恰在边界时刻的行为是独立用例；
3. **负向底数**：状态机型输入，非法转换与终态约束各至少 1 条负向用例。

From fishzjp/qa-skills, MIT.

More from fishzjp/qa-skills