Claude Skill

test-case-writing

从需求文档、API 文档、Bug 报告或代码仓库产出可执行的手动测试用例（markmap）时使用——代码优先：索取仓库、先代码审查找潜在 bug 再写用例，并抽取机器可读 Schema。不用于：需求建模（requirement-analysis）、测试策略（test-strategy）、独立审查（test-case-review）、自动化脚本（automated-e2e-testing / api-testing）。

LLM Mart · 0 points · 5 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download fishzjp-qa-skills-skills_test-case-writing-9d93d04.zip · 17 KB

fishzjp/qa-skills 33 6 forks MIT Updated 17d ago

Part of fishzjp/qa-skills — 11 skills

Install

skills CLI npx skills add https://github.com/fishzjp/qa-skills/tree/main/skills/test-case-writing

Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install fishzjp-qa-skills@llmmart

Git git clone https://github.com/fishzjp/qa-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole fishzjp/qa-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

测试用例编写

从需求模型（或原始输入源）与代码，产出人看得懂、能执行的手动用例文件（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 条双侧边界用例（边界前一拍可成功 / 到达后进入另一态）——时限数值已在材料中给定时同样必须双侧（如"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 的映射建议执行，偏离需说明理由。（注：本 skill §3 的两个实测自伤案例与 api-testing 工程约定各存一份同源副本——红线 4 要求各自自包含，修订时须两处同步。）

阶段四：审查（写时抽查）

降级依据：全检式 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

Files (qa-skills)

templates

markmap_template.md 13.5 KB

# Markmap 测试用例模板

> **路径口径**：本模板内 `../core/...` 等相对路径按消费方 SKILL.md 所在目录（`skills/test-case-writing/`）解析书写，不是相对本文件。

根据项目类型从以下模块中选取需要的，拼装为测试用例文件。不需要的模块直接删除。

> **编写说明**：默认使用**详细格式**。有 UI 功能用四段式（前置条件 / 操作步骤 / 预期结果，优先级标注在名称行）；无 UI 后端功能用协作五段式（前置条件 / 操作步骤（请开发执行）/ 预期结果（请开发反馈）/ 验证方式，优先级同样标注在名称行，不单列字段）。每条用例唯一编号 `TC-{模块号}-{序号}` 写在名称前，P0 冒烟用例名称后追加 `（SMOKE-{序号}）` 标注。模板内其余条目以紧凑占位 `- {操作}，{结果}` 书写，**编写时请展开为对应详细格式并补 TC 编号**；同一子模块共享的前置在标题下用 `> 前置：...` 统一声明，单条只写特有前置。
>
> **正文零代码内部（硬约束）**：正文只用业务语言，禁出现 `文件:行`、SDK 符号、错误码常量、函数名；嵌入具体测试数据（真实编号/字段/值），不要占位符。
>
> **零上下文可执行（硬约束）**：文件头部导读四件套（功能简介+角色表 / 环境与账号表 / 术语表 / 图例）；被测页面首次出现写明到达路径；异步预期写判定时限（等多久不发生算失败）；用例名称断言不超出步骤实际验证强度。
>
> **代码模式**：文件顶部加测准声明（见下方范例）；`代码依据: {文件:行}` **不写进正文用例**，统一放文件末尾附录；Cx 缺陷记录、Dn 风险点、文档偏离、改动文件映射全部放附录区（见文末），与正文用 `---` 分隔，标注"开发核查，非测试执行"。

### 详细格式范例

> **测准声明**（代码模式必加，文件顶部）：本文件以 {仓库} {分支} 实际实现为唯一功能基线；需求/设计文档降为背景对照（偏离见附录）。代码级证据（`文件:行` 等）放文件末尾附录，不写进用例正文。

**A. 有 UI 功能 — 四段式**

> 前置：管理员已登录、项目已创建

- **TC-01-01 正常创建项目** [P0]（SMOKE-1）
  - 前置条件: 无额外前置
  - 操作步骤: 1. 进入「项目创建」页 2. 填写名称+描述 3. 点击提交
  - 预期结果: 创建成功，列表出现新项目卡片并回显名称/项目id

**B. 无 UI 后端功能 — 协作五段式**

> 前置：无 UI 界面操作；测试数据见各用例「前置条件」（数据编号示例 fb1f2933...）

- **TC-05-01 写入单个文字字段，读回值一致** [P0]
  - 前置条件: 已准备图片编号 fb1f2933f0e837b719d510a200dff31f
  - 操作步骤（请开发执行）: 1. 用 hbase.set 写入：编号=fb1f2933...，字段 lr_label_top="任务动作"，数据类型=图片 2. 用读取功能读回该字段
  - 预期结果（请开发反馈）: 读回的 lr_label_top 值 = "任务动作"，与写入一致
  - 验证方式: 开发查 HBase 该编号的 lr_label_top 字段，反馈实际值

---

# {项目名} 测试用例

<!-- 导读区四件套（硬性产出，正文模块之前）：以零上下文新人能直接开工为标准 -->

> **功能简介**：{一两句话：这是什么功能，解决什么问题}
>
> **角色**：{角色A} → {用它做什么}；{角色B} → {用它做什么}

**环境与账号**（未知信息不省略，列 TODO 标注找谁拿）：

| 项 | 值 |
|----|----|
| 管理后台入口 | {URL 或「TODO：向 {谁} 索取」} |
| App/客户端 | {测试包获取方式 或 TODO} |
| {角色A} 测试账号 | {账号 或 TODO} |
| {被测页面入口} | {导航路径，如 后台 → 营销中台 → 券工场} |

**术语表**（正文出现的每个内部系统名/英文字段名/状态代号，此处可查）：

| 术语 | 中文名 | 说明 |
|------|--------|------|
| {内部系统名} | {中文名} | {一句话解释，如：风控系统，领取前校验用户风险} |
| {英文字段名} | {中文名} | {含义与界面对应} |

**图例**：P0=冒烟（失败则核心不可用）/ P1=常规（默认级别，未标注即 P1）/ P2=边界低频；`TC-{模块号}-{序号}`=用例唯一编号；`（SMOKE-{序号}）`=冒烟用例序号标注（追加在 P0 用例名称后）；`[需Mock]` 等标签见附录可测试性说明。

> 标准测试数据：{集中声明各用例默认复用的数据}

## 1. 基础配置/创建 <!-- 所有项目 -->

### 1.1 创建
<!-- 详细格式 inline 示范：占位条目编写时按此展开 -->
- **TC-01-01 正常创建（必填字段齐全）** [P0]（SMOKE-1）
  - 前置条件: 无额外前置
  - 操作步骤: 1. 填写全部必填项 2. 点击提交
  - 预期结果: 创建成功并生成记录id
- {创建后默认值}，{默认配置正确}

### 1.2 配置
- {配置选项A}，{配置生效}
- {配置锁定/不可变}，{拒绝变更}
- {配置变更后已有数据的行为}，{符合预期}

### 1.3 编辑/重提路径校验 <!-- 有编辑或重新提交入口的项目，二阶交叉高发区 -->
- {创建时的每条校验规则，在编辑路径重复验证}，{同样拦截}
- {驳回/退回后修改为非法值重新提交}，{同样拦截}
- {标识字段（名称/编号）重复提交}，{唯一性行为明确}

## 2. 数据输入/导入 <!-- 有数据导入的项目 -->

### 2.1 正常格式
- {标准格式导入}，{导入成功} [P0]

### 2.2 异常格式
- {字段缺失}，{报错并提示}
- {字段格式非法}，{行级错误}
- {字段映射/别名}，{映射正确}

### 2.3 有效性校验
- {全部有效}，{全部保留}
- {部分无效}，{过滤后保留有效值}
- {全部无效}，{拒绝/告警}

### 2.4 异步与缓存 <!-- 有异步导入的项目 -->
- {异步任务状态}，{可追踪}
- {缓存一致性}，{导入期间变更不影响已加载缓存}

## 3. 核心业务逻辑 <!-- 所有项目 -->

### 3.1 逻辑分支A
- {条件A}，{走分支A} [P0]

### 3.2 逻辑分支B
- {条件B}，{走分支B} [P0]

### 3.3 逻辑分支C
- {条件C}，{走分支C} [P0]

## 4. 操作/交互 <!-- 有用户操作的项目 -->

### 4.1 正常操作
- {正确条件}，{操作成功} [P0]
- {操作后数据变更}，{符合预期}

### 4.2 异常操作
- {错误条件}，{操作被拒绝}

### 4.3 逆向操作
- {释放/退回/取消}，{状态恢复}
- {完整状态流转}，{每步验证}

### 4.4 并发
- {多用户并发}，{无重复无遗漏}

## 5. 数据处理/转换 <!-- 有数据处理的项目 -->

### 5.1 格式转换
- {输入格式A → 输出格式B}，{转换正确} [P0]

### 5.2 聚合/分发
- {多源数据聚合}，{结果正确}
- {单源数据分发}，{各目标数据正确}

## 6. 搜索/筛选/分页 <!-- 有列表查询的项目 -->

### 6.1 搜索
- {精确搜索}，{结果正确} [P0]
- {模糊搜索}，{结果正确}

### 6.2 筛选与排序
- {多条件筛选}，{结果正确}
- {排序}，{顺序正确}

### 6.3 分页
- {首页/末页/中间页}，{数据正确}
- {每页条数变更}，{分页正确}
- {空结果}，{友好提示}

## 7. 权限与角色 <!-- 多角色系统 -->

### 7.1 角色权限
- {普通用户}，{正常操作} [P0]
- {管理员}，{额外权限验证}
- {无权限用户}，{拦截}

### 7.2 权限变更
- {角色变更后}，{权限即时生效}

## 8. 工作流/审批 <!-- 有流程的项目 -->

### 8.1 正常流程
- {完整审批链}，{流程通过} [P0]

### 8.2 异常流程
- {驳回}，{回到上游}
- {超时}，{超时处理正确}

## 9. 通知/消息 <!-- 有通知功能的项目 -->

- {触发通知}，{通知发送成功} [P0]
- {通知内容}，{模板变量替换正确}
- {发送失败}，{重试机制生效}
- {重复触发}，{消息去重}

## 10. 文件上传/下载 <!-- 有文件操作的项目 -->

- {正常文件上传}，{上传成功} [P0]
- {文件类型限制}，{非法类型拒绝}
- {文件大小限制}，{超大文件拒绝}
- {文件下载}，{内容完整}

## 11. 第三方集成 <!-- 调用外部服务；type_scope 轴 10 include standard+ 时选用，type: functional + [集成] 标签 -->

- {外部 API 正常}，{处理正确} [P0]
- {外部 API 超时}，{降级/重试}
- {外部 API 返回异常数据}，{容错处理}

## 12. 多轮/链式流程 <!-- 有多阶段操作的项目 -->

### 12.1 第一轮
- {第一轮操作}，{结果正确} [P0]

### 12.2 第二轮
- {第二轮操作，携带第一轮数据}，{数据完整} [P0]

### 12.3 多轮(>2)
- {第三轮}，{历史累积正确}

## 13. 标签/分类管理 <!-- 有分类体系的项目 -->

### 13.1 标签 CRUD
- {创建标签}，{创建成功} [P0]
- {修改标签}，{修改成功}
- {删除标签}，{删除成功，关联数据处理正确}

### 13.2 分类层级
- {多级分类}，{层级正确}
- {标签关联}，{关联正确}

## 14. 配置管理 <!-- 有配置项的项目 -->

- {新增配置项}，{配置生效} [P0]
- {修改配置项}，{修改后即时生效}
- {删除配置项}，{关联功能降级或使用默认值}
- {配置生效范围}，{仅影响目标范围}

## 15. 边界与异常 <!-- 所有项目 -->

### 15.1 输入边界
- {空值}，{按规则处理}
- {超大值}，{处理正确}
- {特殊字符}，{报错或转义}

### 15.2 数据一致性
- {级联操作}，{关联数据一致}
- {幂等处理}，{重复操作结果不变}

### 15.3 错误信息
- {错误信息}，{含定位信息，格式符合规范}

## 16. 安全性 <!-- Web/API 项目；type_scope 轴 2 include 且 standard+ 时选用，type: security + [安全] 标签用例（硬默认轴；light 档走 Cx 审查通道），越权功能正确性归模块 7（功能域 permission），域间裁决见 ../core/test-type-matrix.md 第 2 节 -->

- {未认证访问}，{拒绝} [P0]
- {越权访问}，{拒绝} [P0]
- {SQL 注入/XSS}，{拦截或转义}
- {数据隔离}，{租户间数据不可见}
- {接口限流}，{超限拒绝}

## 17. 前端展示 <!-- 有前端界面的项目 -->

- {页面展示}，{内容正确}
- {交互限制}（防连点/防重复），{限制生效}
- {动态 UI}（条件展示/隐藏），{符合规则}

## 18. 兼容性 <!-- 跨平台项目；type_scope 轴 5 include standard+ 时选用，type: compatibility + [兼容] 标签 -->

- {目标浏览器A}，{功能正常}
- {目标浏览器B}，{功能正常}
- {移动端适配}，{布局正确}

## 19. 国际化 <!-- 多语言项目；type_scope 轴 8 include standard+ 时选用，type: functional + [国际化] 标签 -->

- {语言切换}，{文案正确}
- {时区处理}，{时间显示正确}
- {多语言文案}，{无溢出/截断}

## 20. 并发一致性 <!-- 测试策略 type_scope 轴 4（concurrency）include 且 standard 及以上时选用；type: concurrency，名称行加 [并发] 标签 -->

### 20.1 竞争写入
- {同一资源多端并发提交}，{无重复无遗漏无死锁}

### 20.2 先查后写窗口
- {并发触发先查后写路径}，{结果与串行执行一致}

> 性能（轴 1）为**脚本型**轴：不产手动用例——压测模型与执行物走专项脚本或移交（executor 如 k6，见 ../core/test-type-matrix.md 第 12 节消费方式映射），本模板不设性能手动用例模块；可靠（轴 3，type: reliability + [可靠] 标签）的超时/重试/降级用例按需在本模块外另立子模块。

## 21. 数据迁移/升级 <!-- 存量系统迭代；type_scope 轴 9 include standard+ 时选用，type: functional + [迁移] 标签 -->

- {Schema 变更后老数据兼容}，{数据可正常访问}
- {迁移完整性}，{无数据丢失}
- {新旧版本共存}，{行为一致}
- {回滚后数据可用}，{数据完整}

---

## 附录：开发技术核查清单（非测试执行项）<!-- 代码模式按需追加 -->

> 以下供开发/评审核查与溯源，测试工程师不执行。代码级证据（`文件:行`）集中于此，**不写进正文用例**。

### 附录 A：缺陷记录 Cx

> 潜在 bug 记录，每条附证据与处置

- **C1 {现象描述}**
  - 证据: {文件:行}
  - 证据等级: E2（E0–E4，格式见 `../core/evidence.md`）
  - 置信度: medium
  - 处置: 主线验证 / 专项验证 / 待实测确认 / 已证伪 / 后端范围
- **C2 {现象描述}**
  - 证据/等级/置信度/处置: ...

### 附录 B：高风险点 D1-Dn

> 代码审查识别的高风险回归点，每条映射一条正文回归用例

- **D1 {风险描述}** [等级：Critical/High/Medium/Low（Impact × Likelihood 评分，评级规则见 `../core/risk-model.md`）]
  - 证据: {文件:行}
  - 覆盖用例: {正文用例 TC 编号}
  - 通过判据: {明确判据}
- **D2 {风险描述}** [等级：...]
  - 证据/覆盖用例/通过判据: ...

### 附录 C：代码证据清单（可选）

| 用例编号 | 代码位置 |
|---------|---------|
| {TC 编号} | {文件:行} |

### 附录 D：文档偏离对照

| 设计点 | 文档描述 | 实际实现（文件:行） | 偏离类型 |
|--------|---------|-------------------|---------|
| {设计点} | {文档原文} | {实现} | 字段/流程/默认值/... |

### 附录 E：改动文件映射

| 改动文件 | 影响模块 | 回归用例 | 分类 |
|---------|---------|---------|------|
| {文件} | {模块} | {TC 编号} | 🆕新建/✏️修改/🗑️删除/💀死代码 |

### 附录 F：可测试性说明

> 带 [需真机]/[需Mock]/[需专业环境] 标注的用例逐条列出，替代方案须可行动（平台/工具 + 操作入口）

| 用例编号 | 标注 | 替代方案 | 状态 |
|---------|------|---------|------|
| {TC 编号} | [需Mock] | {平台名与操作入口；未知则「TODO：向 {谁} 确认 {什么}」} | 待确认/已落实 |

SKILL.md 22.8 KB

---
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

- 端到端测试整个需求（理解→策略→用例→执行→报告）→ 用 `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 条负向用例。

> 纪律依据：把「完整性」从阶段 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` 的映射建议执行，偏离需说明理由。（注：本 skill §3 的两个实测自伤案例与 api-testing 工程约定各存一份同源副本——红线 4 要求各自自包含，修订时须两处同步。）

### 阶段四：审查（写时抽查）

> 降级依据：全检式 4A/4B 在弱模型×输出预算下是伪执行（实测消耗大量核对预算却不改变产出行为）。
> **覆盖的执行点已迁移到阶段三交付核对（模块核对+维度核对，生成路径内联）**，
> 本阶段只做轻量抽查，不回到原文档逐段比对（该指令是 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`