kazuph/unit-test-tatsujin

Unit Test Tatsujin Skill

• トリガー: 「単体テスト」「ユニットテスト」「テスト方針」「モック」「スタブ」などテスト設計に関する依頼を受けたときに使用する。
• 目的: 上記ポリシーを踏まえ、AIエージェントが価値の高い単体テストを設計・実装するためのガイドとして使う。
• 利用例: テストケース設計、モック/スタブ方針の確認、テスト命名レビューなど。
• 注意: Kiro流儀のタスク進行中は必ず本スキルを展開し、以下の方針全文を参照すること。

方針全文

1. 単体テストの基本定義

• 「単体テスト」とは、次を満たすテストとする：
  • 少量のコード（1つの振る舞い = unit of behavior）を検証していること
  • 実行が高速であること（ミリ秒〜数百ミリ秒レベルを目標）
  • 外部環境から隔離されていること（ネットワーク、DB、ファイル、時刻、乱数などを直接叩かない）

2. 目指すテストの「4本の柱」

1. 退行に対する保護

   • バグや仕様変更で振る舞いが変わったら、テストが確実に失敗すること。

2. リファクタリング耐性

   • 内部実装（メソッド分割・クラス分割・アルゴリズム変更など）を変えても、振る舞いが同じならテストは壊れないこと。
   • 実装の詳細ではなく「入出力と副作用（observable behavior）」だけを検証すること。

3. 迅速なフィードバック

   • 単体テストスイート全体がすぐに回るように、1テストあたりを高速に保つこと。
   • 遅い処理（I/O・外部API）は原則モック／スタブに置き換えること。

4. 保守のしやすさ

   • テストコードは「ビジネスルールの仕様書」として読めること。
   • 複雑なセットアップや条件分岐をテスト側に書きすぎないこと。

上記4つは掛け算で評価する。
どれか1つでも 0 に近いテストは「価値が低いテスト」とみなす。

3. 学派の前提（古典派をデフォルトとする）

• 本リポジトリでは 古典派（Classic）」の考え方をデフォルトとする：

  • 「単体」は、同じ目的を達成するための小さなクラス群のまとまりとして扱ってよい。
  • テストごとに「1クラスだけを絶対に分離する」ことは求めない。
  • ただし、共有依存（DB、メッセージキュー、外部サービスなど）はテストダブルで隔離すること。

• ロンドン派スタイル（全協力オブジェクトをモック化しがちなスタイル）は 例外的に必要なときだけ 用いること。

4. モック／スタブの使い分けと禁止事項

• スタブ（入力側のテストダブル）

  • 役割：テスト対象が必要とする入力データを返すだけの、受動的なダミー。
  • 方針：
    • スタブに対して「何回呼ばれたか」「どの順番で呼ばれたか」を検証しないこと。
    • スタブの呼び出し検証は アンチパターン とみなし、避けること。

• モック（出力側のテストダブル）

  • 役割：テスト対象が外部に向けて行う操作（ログ出力、メール送信、イベント発行など）を検証するためのダミー。
  • 方針：
    • 外部との「やり取り自体」が仕様の一部である場合にのみ、モックで検証すること。
    • 不要な call count / call order チェックは書かないこと。

• 共通方針：

  • テストが実装の細かい手順に強く依存しないようにすること。
  • 可能な限り「最終的な結果（戻り値・状態変化・公開APIの出力）」だけを検証すること。

5. テストの構造（AAAパターン）

各テストメソッドは、必ず次の3フェーズを明示すること：

1. Arrange（準備）

   • SUT（System Under Test）とその依存オブジェクトを準備する。
   • テストデータ・スタブ・モックをここでセットアップする。

2. Act（実行）

   • SUT のメソッド／関数を 1行で 呼び出す。
   • 原則として Act は1つに絞ること。

3. Assert（確認）

   • 戻り値、状態変化、副作用を検証する。
   • 1つのテストで複数の「論理的なシナリオ」を混在させないこと。
   • 複数パターンを検証したい場合は、パラメータ化テストの利用を検討すること。

6. テスト名のルール

• テストメソッド名は、次の形式を基本とする：

  • {対象メソッド名}_{事前条件}_{期待結果}

  例：

  • calculateFee_WithPremiumUser_ReturnsDiscountedFee
  • register_WhenEmailAlreadyExists_ThrowsDuplicateException

• できるだけビジネス用語を用いて、「何の仕様を検証しているか」が第三者に伝わる名前を付けること。

7. AIエージェントへの具体的な禁止事項

AI がテストを生成するとき、次は禁止とする：

• ネットワーク・DB・ファイルシステム・外部APIを 直接叩く単体テスト を書くこと
  （それらは統合テスト・E2E テストの責務とし、本方針の対象外とする）
• 実装の私有メソッドや内部フィールドにアクセスするためだけに可視性を変更すること
• 一度に複数のビジネスルールを検証する「巨大なテスト」を書くこと
• モックの呼び出し回数や順序を、仕様と無関係なレベルで細かく検証すること
• スタブに対して「呼び出されたかどうか」を検証すること

8. AIがテスト作成時に毎回チェックすべきこと

テストを1つ追加／修正するときは、必ず次を自問すること：

1. このテストは「振る舞い」を検証しているか？
   （実装の手順ではなく、外から見える結果だけを見ているか？）

2. 内部実装を変えても、このテストはそのまま通るか？
   （通らない場合、それは「仕様の変化」を捉えているか？）

3. スイート全体を回したとき、フィードバック速度を著しく落としていないか？
   （I/O を本当に叩いていないか？重いループを書いていないか？）

4. このテストは、あとから読む人にとって「仕様書」として役に立つか？
   （テスト名・Arrange のデータ・Assert の内容が意味的にクリアか？）

上記すべてに「はい」と答えられないテストは、生成後に必ず修正すること。

9. 追加実践ガイド（本方針の補強として採用）

• 時刻・乱数・UUID・環境変数は必ず抽象化（例: Clock/IdGenerator/RandomProvider/EnvProvider）して注入し、決定性を担保する。
• プロパティベーステストを純粋関数やパーサ／バリデーションに積極採用し、seed をログに残して再現性を確保する（例: fast-check, quickcheck）。
• 非同期・並行処理はフェイクタイマー／テストスケジューラで制御し、「順序」より「結果」を検証する。
• スナップショットは構造化された JSON 等に限定し、UIや変動が大きい出力のスナップは避ける。
• 共有依存をモックするときは、軽いコントラクトテストで実実装との乖離を検知する。
• フィクスチャはビルダー／Factoryパターンをデフォルトとし、値の意図をテスト名同様に読みやすくする。