测试用例编写
SkillDev toolsWrite manual test cases (markmap) from docs, bugs or code — code-first: review code for bugs first; extracts machine-readable schema. Not for: requirement-analysis / test-strategy / test-case-review / automation. 从 PRD/API 文档、Bug 或代码写手动用例（markmap）——代码优先：先查代码找 bug 再写，抽 Schema。不用于：需求建模、策略、评审、自动化。
Available today. Use it from your connected AI after setup.
No other account needed.
Connect ahel once, and every AI you use reads what you have installed.
Then ask your AI: use the 测试用例编写 skill
What this skill tells your AI
The instructions your AI receives, as published by fishzjp/qa-skills in skills/test-case-writing/SKILL.md and read by ahel’s review.
从需求模型（或原始输入源）与代码，产出人看得懂、能执行的手动用例文件（markmap），并抽取机器可读的 Test Case Schema 供下游 Skill 消费。
落盘产物：{项目}/测试用例_markmap.md（唯一人工维护源）+ {项目}/测试用例.schema.yaml（由 markmap 单向抽取，规则见 ../core/schema-extraction.md）。
When to Use
- 有代码仓库，需基于实际实现编写用例（代码优先，首选场景）
- 给定需求文档/PRD、技术设计方案、API 文档，需要编写测试用例
- 给定 Bug 报告，需要编写回归测试用例
- 需求变更时，增量更新已有测试用例
When NOT to Use
- 端到端测试整个需求（理解→策略→用例→执行→报告）→ 用
qaskill 编排 - 需要系统性需求建模（目标/范围/规则/异常/依赖/不明确项）→ 用
requirement-analysisskill；本 skill 只做轻量输入研读 - "这个功能应该怎么测"（范围/类型/深度/优先级的策略决策）→ 用
test-strategyskill - 事后独立审查存量或他人写的用例 → 用
test-case-reviewskill；本 skill 只做写时自审（阶段四） - 编写自动化测试代码 → 用
automated-e2e-testing（UI）或api-testing（接口）skill - 代码变更后判断回归范围 → 用
regression-testingskill；本 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 条双侧边界用例（边界前一拍可成功 / 到达后进入另一态）——时限数值已在材料中给定时同样必须双侧（如"30 分钟超时"→第 29 分 59 秒可支付、第 30 分 00 秒被关闭；"7 天自动确认"→满 7×24h 前一秒可手动确认、到达后自动确认）。给定数值不等于已验证，恰在边界时刻的行为是独立用例；
- 负向底数：状态机型输入，非法转换与终态约束各至少 1 条负向用例。
纪律依据：把「完整性」从阶段 4B 的后置审查纪律改为交付前的显式核对项——弱执行环境下后置纪律可能被跳过，逐模块核对拦住「写一个模块就收工」的早停。但模块核对拦住模块坍缩后，弱模型仍会出现维度坍缩——模块全而维度空，故核对必须下探到维度。
输出预算纪律（硬约束）
输出预算有限（32K token 级），仪式与用例争预算——用例优先：
- 用例数封顶：
min(可测点数 × 1.5, 80)条为上限；超出时按 P0 > P1 > P2 收缩，不稀释单条质量（四段式不省略）去凑数量； - 测试数据守约束：用例中的测试数据（唯一名、账号、订单号等）须满足材料声明的字段约束（maxLength/枚举/格式）——生成的数据模板总长按约束上限预留余量，不顶格（实测自伤案例：API 任务唯一名模板 22 字符撞契约 maxLength 20，整条用例因 NAME_INVALID 失败）；参数矩阵组合还须满足跨字段业务规则（如"使用门槛不能低于面额"、"开始时间早于结束时间"）——逐参数独立变化时每格组合回检全部规则，违反规则的格子改取合法值或拆为显式负向用例（实测自伤案例：金额顶格 1000 配低于面额的门槛，被业务规则正确拒绝而用例期望成功）；
- 附录只在代码模式产出，纯文档模式不产 Cx/Dn/改动映射/代码证据清单（无代码可引）；
- 导读压缩：四件套每件 ≤3 行；术语表只收正文实际出现的术语；
- 单条用例超出四段式框架的内容（背景解释、方法论证）一律删除——细节属于澄清记录或附录，不属于用例。
依据：api-testing 的输出预算纪律（parametrize 收敛/行数上限）是全集唯一实测防截断手段；实测曾发生输出被截断只剩一个
{的事故，与澄清仪式开销同源——预算意识必须从 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（边界）：极端输入、低频场景、需特殊环境。性能类诉求不在此列——性能是类型矩阵脚本型轴（轴 1），standard 及以上走专项脚本、light 走 Cx 审查条目，任何档位都不产手动手例。
存在 Risk Map 时按 ../core/risk-model.md 的映射建议执行（Critical → 必有 P0，High → P0/P1，Medium → P1，Low → P2/按需），偏离需说明理由。
阶段四：审查（写时抽查）
降级依据：全检式 4A/4B 在弱模型×输出预算下是伪执行（实测消耗大量核对预算却不改变产出行为）。 覆盖的执行点已迁移到阶段三交付核对（模块核对+维度核对，生成路径内联）， 本阶段只做轻量抽查，不回到原文档逐段比对（该指令是 thinking 预算杀手，已废除）。
4A：模块写完后的抽查（只做两条）
- 抽查主流程：该模块最短正向主路径的用例是否存在（与维度核对第 1 条同一口径，此处只是复查）
- 抽查单一职责：抽 2-3 条用例确认只测一个点、预期唯一
4B：全局抽查（全部模块完成后，只做三条）
- FAQ/非目标抽查：FAQ 每条至少 1 条用例（遗漏高发区）
- 二阶交叉抽查（中型以上项目）：
../core/testing-principles.md第 3 节三项中抽 1 项执行（写入路径×校验 / 失败×重试 / 标识×重复） - 跨模块重复检查：重复用例合并、TC 编号连续
已废除：逐文档溯源全检、coverage.md 19 维全检、多角色四视角全检——这些维度的设计知识 仍在
../core/coverage.md（按需参考，供强模型/大项目加深），但不再是交付前的强制执行项； 强制执行项只有阶段三交付核对的模块核对+维度核对。
审查输出
直接在用例文件中补充遗漏和调整，不产出独立审查报告。只在用例文件末尾（附录之后）按 ../core/case-format.md 第 10 节格式追加「审查记录」。
阶段五：定稿 + Schema 抽取
- 可读性自检：执行
../core/executability.md全部检查项（零上下文新人复述、术语表核对、正文零代码自检、执行性确认、判定时限核查），不是可选参考 - 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 指涉真实性） - 文件命名：
{项目名}/测试用例_markmap.md+{项目名}/测试用例.schema.yaml
Schema 双轨原则
markmap 是给人的交付物与唯一人工维护源；Schema 是机器可读元数据层，由本 skill 从 markmap 单向抽取，作为 Skill 间流转接口（test-case-review / regression-testing / 执行层消费）。不要求人维护两份，Schema 永远可由 markmap 再生；markmap 修改后必须重新抽取。存量 markmap 按同规则抽取即可，不需人工重写。
增量更新流程
需求变更时增量更新已有用例（而非从零重写）：
- 影响分析：确定变更影响哪些模块、哪些用例（直接用例 + 下游依赖 + 状态流转受影响的边 + 数据模型变更影响的查询/校验）。代码模式：基于
git diff盘点改动文件，按附录「改动文件映射」分类定位受影响用例 - 标记受影响用例：按 TC 编号列出，标记
[已变更]、[已废弃]、[需新增]（Schema 的status同步） - 更新用例：新增用追加编号，废弃用
~~删除线~~+[已废弃-原因] - 局部审查：对变更模块执行 4A + 涉及变更的跨模块检查
- 重新抽取 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
Signals
- GitHub stars
- 28
- Forks
- 5
- Last commit
- Sep 2026
Advanced
- Catalog kind
- skill
- Gateway key
test-case-writing- Source
- github.com/fishzjp/qa-skills