| name | x-designing-testcases |
| description | UC表を入力として振る舞いの検証ケースを設計し、テストコードを生成するスキルです。 「テスト計画を立てたい」「テストケースを設計したい」「どんなテストを書くべきか」 「テストを書いて」「.test.ts を作って」「e2eだけで十分？」 「このコンポーネントのテスト何を書けばいい？」「テストが多すぎる気がする」のように使います。 3層検証（自動テスト / Agentic Verification / 手動検証）の割当てを行い、 テスト種別ごとに章分けしたテスト計画を作成、テスト対象の特性に応じた reference で テストコードを生成します。テストファイルには VERIFY コメントで3層の検証情報を埋め込みます。 ユースケース設計は別スキル`x-designing-usecases`で扱います。
|
| allowed-tools | ["Bash","Read","Write","Edit","Glob","Grep","TaskCreate","TaskUpdate","TaskList"] |
designing-testcases
UC表を入力として、3層検証の割当てとテストコードを実装します。テストファイル内にVERIFYコメントでAgentic検証・手動検証の情報を埋め込み、テストファイル自体を3層検証のSSoTにします。
責務とスコープ
対象は振る舞いの検証ケースです（コードが期待通りに動くかをアサーションするもの）。
対象外は以下の通りです。これらは品質ゲートであって振る舞いテストではなく、テストを書く過程で自然に検知されます。
- 型エラー →
tsc / IDE / コードレビュー
- スキーマ整合 → contractツールの設定
- バンドル妥当性 → ビルド設定 / size-limit / lint
- 静的なa11y違反（color-contrast、button-name、aria属性の存在等）→ axe / markuplint等のリンター
核となる方針
3層検証
テスト計画は3層で構成します。詳細はreferences/verification-methods.mdを読んでください。
| 層 | 主な目的 | 実行頻度 | 担い手 |
|---|
| 自動テスト | 退行検知 | CI で常時 | テストランナー |
| Agentic Verification | 仕様確定 / 不具合再現 / 実環境の実値確認 | 開発中・必要時 | Claude Code 等のエージェント |
| 手動検証 | UX判断 / 新規体験の評価 / 最終受け入れ | リリース前 | 人間 |
自動テストをベースに、Agentic と 手動をテストファイル内に埋め込む
自動テストが書ければCIで実行されます。Agentic Verificationと手動検証は、対応する自動テストの直上にVERIFY:agentic/VERIFY:manualコメントで併記します。これにより、次のようになります。
- 自動テスト = CIでランナーが実行します
VERIFY:agentic = エージェントがgrepして自律実行しますVERIFY:manual = エージェントがgrepしてユーザーにチェックリストを提示します
テストファイル全体に効く情報はVERIFY:metaとしてファイル先頭に記述します。UCファイルが残らないプロジェクトでも、このテストファイルが3層検証のSSoTになります。
VERIFYコメントの仕様はreferences/verify-comment-spec.mdを読んでください。
テスト計画はテスト種別ごとに章分けする
UC側は系統（E/D/O）で整理されていますが、テスト計画では系統を解体し、テスト種別ごとに章を分けます。1機能のテストは複数の系統UCから観点を統合する必要があるためです。
タスク登録（実行開始時に必ず実施）
フローを開始する前に、全ステップをTaskCreateで登録します。各ステップを開始するときTaskUpdateでin_progressへ、完了したときcompletedへ更新します。
| # | subject | blockedBy |
|---|
| 1 | タスク判定 | — |
| 2 | タスクB: テスト計画の生成 | 1 |
| 3 | タスクC: テストコードの実装 | 2 |
タスク判定
| 入力 | タスク |
|---|
| 系統確定UC表のみ | タスクB → タスクC |
| タスクB形式のテスト計画があり（4列テーブル）、実装に進む | タスクC のみ |
| 既存テストがあり、観点の足し引きをしたい | 既存テストのレビュー（タスクBの逆方向） → 差分のみタスクC |
| UC表なし（コードのみ・要件説明のみ） | プロジェクト内の要件定義・仕様ドキュメントを探す → 見つかればx-designing-usecasesでUC表を作るよう案内 → 見つからなければ「x-designing-usecasesでUC表を先に作ってから渡してください」と返す |
タスクCへの入力として期待するテスト計画は、タスクBが生成する4列テーブル（検証項目・由来UC・テスト種別・状況軸）と同じ形式です。この形式を満たさない計画が渡された場合は、不足している列を確認してから進みます。
UC表のスキーマはx-designing-usecases/references/templates.mdを参照してください。
タスクB: テスト計画の生成
ステップ
- 入力スキーマの確認 — 各UCが系統・観察可能な期待結果・適用される状況軸を持っているか確認します。
- 観点の抽出 — 各UCから検証すべき項目を抽出します。複数UCで重複する観点は1項目に統合します。
- テスト種別の決定 — 各観点について、
references/verification-methods.mdから主たるテスト種別を決めます。
- 3層検証の割当て — 各観点について、自動 / Agentic / 手動の3列を埋めます。1観点に複数層を割り当ててよいです。
- 集約 — 状況軸の検証は下位のテスト種別に1回集約します（例: 5xxはunitで網羅し、e2eは1パターンのみ）。
- 重複確認 — 同じ機能の異なる系統UCが両方ある場合、重複に見える項目でも省略しません（観察対象が違うため両方必要）。
- テスト計画の展開 — 下記テンプレートにしたがって出力します。
テスト計画テンプレート
## テスト計画: [機能名]
### unit テスト
| 検証項目 | 由来UC | 状況軸 | 自動 | Agentic | 手動 |
|---|---|---|---|---|---|
| [項目] | [UC-X-XXX] | [cond.xxx] | [テスト種別の方針] | [手段] | [手順] |
### e2e テスト
| 検証項目 | 由来UC | 状況軸 | 自動 | Agentic | 手動 |
| ...
### visual テスト
| ...
### a11y テスト
| ...
### integration テスト
| ...
### 補足: 自動テスト化する条件を満たすAgentic項目
- [理由と根拠]
該当するテスト種別がない章は省略します。
完了条件
完了条件を満たしたらテスト計画をユーザーに提示し、承認を得てからタスクCへ進みます。
タスクC: テストコードの実装
テスト計画の各項目について、以下の順で進めます。
Step 1: テスト対象の特性判別
各検証項目について、references/test-target-classification.mdを読み、対象がどの特性カテゴリに該当するかを判別します。
| 特性カテゴリ | 主な置き場所 | 次に読む reference |
|---|
| 業務ルールを持つ純粋関数 | domain/ | domain-test-patterns.md |
| 汎用ユーティリティ関数 | utils/ | utils-test-patterns.md |
| React hooks | hooks/ | hooks-test-patterns.md |
| React コンポーネント | components/ | component-test-patterns.md |
| ユーザージャーニー（e2e） | features/ | e2e-test-patterns.md |
| 視覚的な状態の差 | Story 単位 | visual-test-patterns.md |
| キーボード操作 / フォーカス / 動的 aria | Component 単位 | a11y-test-patterns.md |
| サーバー側の状態変化を伴う統合 | integration/ | integration-test-patterns.md |
Step 2: テンプレート選択と生成
Step 1で判別した特性カテゴリに対応するreferenceを読み、その中のパターン判別ロジックにしたがってテストコードを生成します。
Step 3: VERIFY コメントの埋め込み
テスト計画のAgentic列 / 手動列に項目があれば、対応するit()/describe()の直上にVERIFY:agentic/VERIFY:manualコメントを追加します。仕様はreferences/verify-comment-spec.mdを読んでください。
ファイル先頭にはVERIFY:metaを必ず追加します。UCファイルが消えてもテストファイルから機能の文脈が復元できるようにするためです。
Step 4: 配置と実行
- 生成したテストコードを対象ファイルと同じディレクトリに配置します（命名規則は各pattern referenceに従います）
- 1行目にテスト実行コマンドをコメントで記載します
- 実行して通ることを確認します
Step 5: 設計改善の提案
テストを書く過程で気づいた設計上の問題は提案にとどめ、修正はユーザー判断に委ねます。チェック項目は各pattern referenceの末尾を参照してください。
完了条件
共通の落とし穴
| 落とし穴 | 対処 |
|---|
| テスト計画を系統別の章で出力する | 系統はUC側の整理軸です。テスト計画はテスト種別で章分けし、由来UC列で系統を間接的に表現します。 |
| Agentic Verificationを退行検知に使う | 仕様確定・探索が本領です。退行検知が必要なものは自動テストへの昇格を検討してください（verification-methods.md参照）。 |
| 1つのe2eテストで複数の状況軸を同時に検証する | 失敗時の切り分けが困難です。1テスト1検証項目が原則です。 |
| 系統Eのテストで実装詳細（内部state、DOM構造の細部）にアサーションする | 観察対象はUIから見える振る舞いに限定します。 |
| 型で防げる異常シナリオを runtime テストに書く | 型レベルで防げるなら型に寄せます。tsd/expect-typeも振る舞いテストの対象外です。 |
| VERIFY:meta を書かない | UC ファイルが消えるとテストの文脈が失われます。SSoT として必ず書いてください。 |
| 静的a11y違反をテストに書く | axe / markuplint 等のリンターで担保します。テストには動的な振る舞い（キーボード操作、フォーカス管理）だけを書きます。 |
