テスト設計ガイドライン（一般向け）
目的とスコープ
- 対象機能の振る舞いを公開インターフェース経由で検証し、内部実装に依存しない堅牢なテストとする
- 外部依存（ネットワーク、ストレージ、設定、認証）はすべてスタブ/モックで置換し、再現性と速度を最優先
原則
- 公開API優先: 非公開の実装詳細（private）に依存しない
- 反射禁止: private呼び出しや実装隠蔽の破り込みを行わない
- シナリオ駆動: 代表的なユースケースと境界条件で網羅し、過剰な組み合わせ爆発は避ける
- 安定比較: 比較対象は意味のある最小限に正規化（非本質データは比較しない）
外部依存とテストデータ
- 外部クライアントや設定値はモック/フェイクで注入する
- 版管理や履歴があるデータは「最新」「直前」「削除マーカー」等の最小構成で時系列を再現する
- バイト列やレスポンスストリームは、サイズ情報やメタデータを持つ擬似オブジェクトで表現する
比較の正規化
- 比較対象を用途に応じて正規化する（例: 主キー・名称・フラグのみ）
- テキスト本文・画像データ・サイズ・インデックス等の非本質フィールドは原則比較から外す
- 並び順の意味がある場合は順序も含めて検証する
コンテンツ種別の扱い
- 画像: 表示用データURIやBase64は同一性のみに利用し、重い本文は比較しない
- バイナリ: ヌルバイト検知やサイズ上限で「バイナリ扱い」へフォールバックする経路を検証
- テキスト: 文字コード検出→行分割→差分生成の流れを代表ケースで通す（検出器のヒューリスティック全網羅は求めない）
サイズ上限とストリーミング
- サイズ閾値超過時は本文読取を回避し、フォールバック動作を検証
- ストリームの長さやヘッダ情報で事前判定できる経路を再現し、不要なI/Oを避ける
履歴・状態フラグ
- 「履歴不在」や「履歴が一方のみ」などの状態フラグは、入力構成で自然に誘発させて検証
- フィルタ条件（対象外判定）と例外時のフォールバック（履歴不在・バイナリDTO）を区別してカバー
階層リソース（ディレクトリ/グループ vs ファイル/葉）
- 階層キーは末尾区切りなどの約束で判定し、グループ指定時は配下リソースへ展開
- メタ情報のみが必要な経路（例: 種別判定や登録区分算出）は本文取得を行わない最小実行にする
アルゴリズムのカバレッジ
- 差分や探索ロジックなどの分岐は、入力の「長さ・一致/不一致・奇偶・差分量」を操作して代表パスを通す
- 内部最適化や補助関数（剰余調整など）は、公開APIを通して間接的に到達可能な範囲で検証する
例外シミュレーション
- 読取/解析/変換の各段で例外を発生させ、フォールバック経路（履歴不在・バイナリ扱い等）を確認
- 例外源はコンストラクションモックやスタブ関数で局所的に与え、過度な副作用を避ける
テスト構成と命名
- 1テスト1意図を徹底し、期待される振る舞いを自然言語で明確に記述
- 前準備（Arrange）・実行（Act）・検証（Assert）を簡潔に分離
- ヘルパはテスト内に自己完結的に置き、外部の隠れ依存を作らない
避けるべきこと
- private実装への依存（反射・内部状態の直接参照）
- 重い本文やメディアの生比較（正規化なし）
- 実ネットワーク/実ストレージへの依存、長時間I/O
- 多数の断片的アサーションによる脆いテスト（本質に絞る）
代表シナリオ例（抽象）
- グループキー指定で配下展開（メタのみ/本文ありの両経路）
- 版一覧が空・削除混在・最新のみ/旧のみの境界
- サイズ閾値超過・バイナリ検出・画像同一性
- 等価テキスト・微差分・大差分・行数の非対称
- 最新/旧版の片側での読取失敗とフォールバック
メンテナンス指針
- 仕様変更時は「意図を表すテスト名」と「最小の期待」から見直す
- 新たな分岐は入力の組合せで到達可能かをまず検討（APIの拡張より先にテストデータ設計）
- 実行速度と独立性を定期的にモニタし、遅延要因（不要I/O・重比較）を排除する
以上の規約に従うことで、速度・再現性・保守性に優れたテスト群を維持しつつ、実装詳細に縛られない堅牢な品質保証を実現します。