test-case-writing
Write 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。不用于:需求建模、策略、评审、自动化。
fishzjp · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add fishzjp/qa-skills --skill test-case-writing技能说明
name: test-case-writing slug: test-case-writing displayName: 测试用例设计 version: 0.8.1 description: "Write 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。不用于:需求建模、策略、评审、自动化。"
测试用例编写
从需求模型(或原始输入源)与代码,产出人看得懂、能执行的手动用例文件(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/枚举/格式)——生成的数据模板总长按约束上限