test-case-writing

テストケース作成

要件モデル（または元の入力ソース）とコードから、人が理解でき、実行可能な手動テストケースファイル（markmap）を作成し、下流の Skill が利用できる機械可読な Test Case Schema を抽出します。

保存する成果物：{项目}/测试用例_markmap.md（唯一の人手保守用ソース）＋ {项目}/测试用例.schema.yaml（markmap から一方向に抽出。ルールは ../core/schema-extraction.md を参照）。

When to Use

• コードリポジトリがあり、実際の実装に基づいてテストケースを作成する場合（コード優先、第一選択のシナリオ）
• 要件文書／PRD、技術設計書、API ドキュメントが与えられ、テストケースを作成する場合
• バグ報告が与えられ、回帰テストケースを作成する場合
• 要件変更時に、既存のテストケースを段階的に更新する場合

When NOT to Use

• 要件全体のエンドツーエンドテスト（理解→戦略→テストケース→実行→レポート）→ qa skill でオーケストレーションします
• 体系的な要件モデリング（目的／範囲／ルール／例外／依存関係／不明点）が必要な場合 → requirement-analysis skill を使います。本 skill では軽量な入力の読み込みのみを行います
• 「この機能はどうテストすべきか」（範囲／種類／深さ／優先度に関する戦略的判断）→ test-strategy skill を使います
• 既存または他者が作成したテストケースを事後に独立してレビューする場合 → test-case-review skill を使います。本 skill で行うのは、作成時のセルフレビュー（フェーズ四）のみです
• 自動テストコードを作成する場合 → automated-e2e-testing（UI）または api-testing（API）skill を使います
• コード変更後に回帰範囲を判断する場合 → regression-testing skill を使います。本 skill ではテストケースファイルの段階的な変更のみを担当します
• コードリポジトリも、参照可能な要件／設計ドキュメントもない場合 → モデリングもテストケース作成もできません。まず exploratory-testing で探索してシステムへの理解を深めるか、ユーザーに入力資料を依頼してください

ワークフロー

フェーズ〇：コードリポジトリを積極的に依頼する（作業開始時に最初に行うこと）

テストケースの作成を始める前に、対象プロジェクトのコードリポジトリをユーザーに積極的に依頼します。

• 依頼する内容：① リポジトリの場所（ローカルパスまたはリモート URL）；② 対象ブランチ／tag；③ 今回の変更範囲（PR/MR リンクまたは <base>...<head> diff 範囲。指定がない場合は全体を対象とします）
• 質問テンプレート：

  🔍 テストケースの精度を高めるため、対象プロジェクトのコードリポジトリの場所と対象ブランチを教えてください（今回の変更に関する PR/diff 範囲がある場合は、そちらもお願いします）。コードを機能の事実上の基準とし、ドキュメントと照合します。実際の実装に基づいてテストケースを作成することで、ドキュメントと実装の不一致を発見し、潜在的なバグを特定できます。ドキュメントのみを使う場合は、これらを実現できません。

• ユーザーがコードなしと確認した場合 → ドキュメントのみのモードに切り替え：「ドキュメントに基づいて作成しますが、精度には限界があります。ドキュメントと実装の不一致の発見、潜在的なバグの特定、リスク箇所が下流で利用されているかの確認はできません」と伝え、「コードの探索と全面レビュー」をスキップし、付録 Cx/Dn の成果物も作成しません。

コードモードとドキュメントモードの違いは後続のすべてのフェーズに関係し、各フェーズで明記します。

フェーズ一：入力の読み込み＋範囲の明確化（コード優先）

入力ソースからテスト可能な項目をすべて抽出し、同時にプラットフォーム、ロール、テスト境界を特定します。静的な事実の情報源として、コードを最優先します（判定ルールは ../core/evidence.md を参照）。コードがある場合は実装を基準とし（実際の動作を検証）、ドキュメントは照合用とします。

入力ソースと注目点

入力ソース	注目点
コードリポジトリ（最優先）	実際の実装ロジック、データ構造、エラー処理、ドキュメントとの差異、潜在的なバグ、変更範囲（diff）
要件文書／PRD	機能項目の一覧、境界の説明、ユーザーロール、ビジネスルール
技術設計書	データモデル、インターフェースシグネチャ、状態遷移、キャッシュ戦略、メッセージ形式
API ドキュメント	インターフェースのパラメーター、必須／任意、戻り値、エラーコード、認証方式
バグ報告	再現手順、根本原因の分析、修正範囲（回帰テストケース）
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、サードパーティーのコールバック）、ユーザーロール（各ロールに表示される内容、実行できる操作、できない操作）、テスト境界（今回の対象範囲／対象外／依存項目）。

対象者と実行モデルの判定（作業開始時に必須。テストケースの記述方法を決定）

テスト対象の機能に UI があるかどうかで、テストケース本文の書き方が直接決まります。作業開始時に判定し、入力ソースから UI の有無を判断できない場合は、ユーザーに一度確認します。

• UI のある機能（Web 管理画面、App、ミニプログラム、H5 ページ）→ テストエンジニアが独立して実行します。操作手順には具体的な UI 操作（どのページに移動するか、どのフィールドに入力するか、どのボタンをクリックするか）を記載し、期待結果には画面上で確認できる現象を記載します。
• UI のないバックエンド機能（データ stage、API インターフェース、SDK 移行、スケジュールタスク、メッセージキューの処理）→ テストエンジニアは独立して実行できないため、**「テスト・開発連携チェックリスト」**として作成します。操作手順には「開発者が実行」と記載し（開発者に具体的なデータと起動方法を示す）、期待結果には「開発者からのフィードバック」と記載します（実際の値／スクリーンショットを返してもらう）。検証方法には「開発者が DB／ログを確認してフィードバック」と記載します。作業開始時に必ず確認します。ユーザーに実行モデルを確認します（「テスト担当者が独立して実行できますか？バックエンド機能は通常、開発者に実行してもらい、DB を確認した結果をフィードバックしてもらう形でしょうか？」）。

どちらのモデルでも、テストケース本文はビジネス用語で記述する必要があります（書式の詳細は ../core/case-format.md を参照。フェーズ三で実施）。

コードの探索と全面レビュー（コードモード専用。コードがある場合は必須）

ドキュメントを読み込んだうえで、次の 4 ステップを実施し、プロジェクトの全体像を把握して潜在的なバグを発見します。この作業の成果は、後続のテストケースに記載する「コードの根拠」と、欠陥記録の基礎になります。

ステップ 1 — 場所の特定と概要把握：リポジトリのパス／対象ブランチ／変更範囲を確認し、README、ルーティング表、エントリーファイル、設定ファイルを読み、プロジェクトの全体像を把握します。

ステップ 2 — 変更内容の一覧化：git diff <base>...<head> --stat で変更ファイルを一覧にし、1 つずつ分類します。🆕 新規作成（新機能の主要な流れ。全面的にカバー）、✏️ 変更（回帰リスクの発生源。元の動作が維持されているか＋新しい動作を重点的に確認）、🗑️ 削除（機能の廃止。廃止後に残存する入口がないことを検証）、💀 デッドコード（ルーティングに登録されていない／参照されていない。無視可能と記録）。「変更ファイル → 影響モジュール → 回帰テストケース」の対応表を作成し（付録「変更ファイル対応表」に記録）、成果物とします。

ステップ 3 — 全面的なコードレビュー（Explore エージェントのマトリクスを割り当て、必ず実施）：

変更ファイル数／サブシステムに応じて対象を分割し、読み取り専用の Explore エージェントを 1～3 個割り当てて並行実行します。各エージェントは、発見項目の種類を 1 つに絞って調査します。エージェントへのプロンプトの例： 「{仓库路径} の {分支} にある {ファイル／サブシステムの一覧} をレビューし、以下のチェックリストを項目ごとに調査してください。各発見項目には ファイル:行 の根拠と確信度を記載してください。① 潜在的なバグ；② ドキュメントと実装の不一致；③ デッドコード／未使用の宣言；④ 高リスクの疑いがあるが、下流で利用されていない可能性がある項目（反証できるか確認が必要）。読み取り専用で、変更はしないでください。」

レビュー用チェックリストでは、../core/coverage.md 第 7.1 節の「コードレビューの発見パターン一覧」にある 13 項目すべて（null/undefined の未処理、境界条件の未保護、状態のデッドロック、並行処理の競合、エラーの握りつぶしなど）を実施します。任意の参考項目ではありません。

ステップ 4 — リスクの分類と変換：

• 高リスク箇所 D1-Dn：../core/risk-model.md に従って評価します（Impact × Likelihood → Critical/High/Medium/Low）。各項目を 1 件の回帰テストケースに対応付けます
• 潜在的なバグ → 欠陥記録 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