code-test

name	code-test
description	テストケース設計、回帰テスト追加、テストコードレビュー、テスト戦略の整理を行うときに使う。正常系、異常系、境界値、データ整合性、互換性、性能、flake、モック方針を検討し、変更に対する安心感を高めつつ維持コストを抑える。

testing.md（テスト観点・テスト設計）

目的：変更に対する安心感を最大化しつつ、テストの維持コストを最小化する。 テストは「実装の正しさ」を示すだけでなく、「将来の変更で壊れない」ことを保証する観測手段である。

---

基本姿勢（Core Mindset）

• テストは「何を保証するか」を明確にするためのもの（実装の写しではない）
• 重要なのはカバレッジではなく、壊れやすい領域が観測できているか
• テストは最終的に 開発速度を上げる ために存在する（遅くするなら設計を疑う）

テストの分類（何をどこで担保するか）

Unit（ユニットテスト）

• 小さな関数/ロジックの振る舞いを保証する
• 依存（DB/外部API/ネットワーク）は原則排除
• ドメインルール、境界値、純粋ロジックに強い

Integration（統合テスト）

• I/O を含む複数コンポーネントの連携を保証する
• DB・キュー・キャッシュ・外部APIクライアントなどの接続を含む
• マイグレーションやクエリの妥当性、トランザクション、整合性に強い

E2E（エンドツーエンド）

• ユーザー視点のシナリオを保証する
• 破壊的変更や回帰に強いが、遅い・不安定になりやすい
• 「最小本数」で重要フローのみ担保する

---

テスト観点（何を見るべきか）

1. 正常系（Happy path）

• 想定通りの入力で、期待する結果が得られるか
• 主要な分岐（代表値）が最低限カバーされているか

2. 境界値（Boundary）

• 空、最小、最大（長さ/桁/件数/金額/日付範囲など）
• 上限/下限を超えたときの扱い
• 並び順やページング（0件、1件、境界ページ）

3. 異常系（Failure modes）

• バリデーションエラー
• 認証/認可エラー（権限不足・他人のリソース）
• 外部依存の失敗（タイムアウト、5xx、ネットワーク）
• DB 失敗（制約違反、deadlock、接続断）

4. データ整合性（Data integrity）

• 冪等性（リトライ/重複で二重登録しない）
• トランザクション（部分成功を残さない）
• 競合更新（lost update を防ぐ）

5. 互換性・回帰（Regression）

• 既存の挙動が壊れていないか（特に公開API/契約）
• 破壊的変更の検知（レスポンス構造、ステータスコード、エラー形式）

6. 可観測性（Observability）

• 失敗時に必要な情報が残るか（ログ/メトリクス/トレース）
• エラーが握りつぶされていないか

7. 性能（Performance）※必要に応じて

• N+1 やループ内I/Oなどの構造的劣化がないか
• 大量件数で破綻しないか（簡易負荷・ベンチ・境界テスト）

---

テスト設計（どう書くと壊れにくいか）

1) 「仕様」をテストする（実装詳細をテストしない）

• 内部関数の呼び出し回数・順序に依存しすぎない
• 本質的な入出力（観測可能な結果）で期待値を書く
• リファクタで壊れるテストは設計が弱いサイン

2) Arrange-Act-Assert（AAA）を保つ

• Arrange：前提（入力・状態）
• Act：対象の実行
• Assert：観測と期待値
• 1テストに意図を詰め込みすぎない（1テスト=1つの主張）

3) テーブル駆動（ケース列挙）で分岐を扱う

• 入力 → 期待値を表で並べる
• ケース名を付けて意図を明示する
• 境界値・異常系を漏れなく追加しやすい

4) 不安定さ（Flake）を根絶する

• sleep 依存を避ける（待機はポーリングや同期プリミティブで）
• 時刻依存は注入/固定（clock を差し替える、固定時刻を使う）
• 乱数は固定 seed
• 並列実行の影響（共有DB、グローバル状態）を排除する

5) フィクスチャ（テストデータ）を管理する

• 目的に対して最小のデータ量にする
• データ生成は読みやすく（ビルダー/ファクトリを検討）
• “巨大フィクスチャ” は変更に弱い（必要最小限へ分割）

6) モックの使い所を明確にする

• 失敗モードを再現するためのモックは有効
• 振る舞いを作り込みすぎるモックは「偽の安心」を生む
• 重要な境界（DB、メッセージング、認可）は統合テストで担保するのが基本

7) テストの層をまたぐ重複を意識する

• 重要フロー：E2E で1本
• ルール：Unit で厚く
• 接続/クエリ：Integration で担保
• 同じ内容を全層で重複させると維持コストが増える

---

バグ修正時のテストの考え方（推奨フロー）

• まず再現条件を小さく言語化する
• 再現テスト（回帰テスト）を追加する
• 修正する
• テストが落ちた理由が「仕様の変更」なら、仕様の明文化（docs/ADR）も検討する

---

良いテスト / 悪いテストのサイン

良いテストのサイン

• 失敗時に原因が分かる（assert が具体的）
• リファクタしても壊れにくい
• 仕様の理解が進む（テスト名が仕様になっている）

悪いテストのサイン

• 失敗理由が曖昧（assert が弱い/多すぎる）
• 実装の変更に過敏（内部実装への依存）
• 実行が遅い・不安定（外部依存/時間依存）

---

迷ったときの判断基準

• これは「将来の変更で壊れたら困る仕様」か？
  • Yes → テストを追加する
• これは「実装詳細」か？
  • Yes → テストではなく設計/分割を見直す
• これは「遅くて不安定」になりそうか？
  • Yes → テスト層・対象を再検討する

テストコードを書くときのガイドライン

原則：テスト内にロジックを入れない

• テスト内で if/switch/複雑なfor を増やさない
• 期待値をテスト内で計算しない（関数/式で作らない）
• テスト内で状態遷移・副作用を制御しない（SUT に任せる）

例外は最小限：

• テーブル駆動でケースを回す for（1箇所のみ）
• wantErr でエラーを分岐する if（1箇所のみ）