fishzjp 测试用例编写
从需求模型（或原始输入源）与代码，产出人看得懂、能执行的手动用例文件（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 的映射建议执行，偏离需说明理由。（注：本 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