flutter-testing

テスト戦略

• テストピラミッド: ユニットテストとウィジェットテストを多めに、統合テストは少なめに。ユニットテストが最も速く、最も低コストです。
• ミラーテストルール: ロジックとウィジェットのカバレッジは 100%。テストのないコードはありません。
• ミラー構成: テストファイルは lib/ ディレクトリ構造を厳密にミラーし、_test.dart で終わる必要があります。
• カバレッジ目標: domain 層と bloc 層のロジックカバレッジ 100% を目標とします。
• テストの独立性: 各テストは独立している必要があります。テスト間で可変状態を共有しないでください。

テストの種類の概要

種類	対象範囲	速度	スキル
ユニット	単一の関数/クラス	高速	dart-testing
ウィジェット	単一の UI コンポーネント	中速	flutter-add-widget-test
統合	アプリ全体 / ユーザーフロー	低速	flutter-add-integration-test

パターンベースのテスト

これら 3 つのパターンは、繰り返しになるテストのセットアップを削減し、すべての視覚的状態をカバーし、ウィジェットの動作を一貫したものに保ちます。これらはパッケージではなく、規約です。

ゴールデンバリアントテスト

ウィジェットが複数の視覚的状態（primary、disabled、hover、error）を持つ場合、Map<String, Widget Function()> を使った単一の構造化された group() ですべてのバリアントをテストします:

• variants マップを定義します。キーは状態名、値はウィジェットビルダーです。
• 各バリアントは必ず分離してレンダリングする必要があります（バリアントごとに新しい pumpWidget 呼び出し）。
• 決定論的なゴールデンファイルの命名を使用します: goldens/<component>.<variant>.png。
• 不安定なピクセル差分を避けるため、tester.view.physicalSize を介して一貫した surfaceSize を設定します。
• 使用すべき場合: デザインシステムのコンポーネント、異なるモードやタイプを持つウィジェット。
• 使用すべきでない場合: 統合テストやアニメーションフレームの検証。

状態マトリクステスト

すべてのステートフルウィジェットは、考えられるすべての UI 状態に対してテストする必要があります。状態マトリクスを使用して、セットアップと検証を分離します:

• ウィジェットがレンダリングできるすべての状態（loading、error、data、empty）を持つ states マップを定義します。
• switch 式を使って状態ごとに正しいレンダリングをアサートする、単一の verify(stateName) コールバックを記述します。
• このパターンは「ハッピーパス」だけをテストしてしまうよくある間違いを防ぎます。
• 使用すべき場合: 複雑な状態機械を持つウィジェット（例: BLoC 駆動の画面）。
• 使用すべきでない場合: 検証ロジックが状態ごとに大きく異なる場合は、個別のテストを記述してください。

インタラクションコントラクトテスト

再利用可能なウィジェットには暗黙の動作ルールがあります。これらを明示的で再利用可能なコントラクトとして定義します:

• よく使うコントラクト用のヘルパー関数を test/utils/ に作成します:
  • verifyTappable(tester, finder, mockCallback): タップでコールバックが正確に 1 回発火します。
  • verifyDisabledNotTappable(tester, finder, mockCallback): 無効時にタップしてもコールバックが発火しません。
  • verifyValidatesOnBlur(tester, finder): フォーカスが外れたときに検証がトリガーされます。
• 同じ動作を共有するすべてのウィジェットにコントラクトを一貫して適用します。
• 使用すべき場合: リファクタリングを経ても維持されるべき厳密に定義された動作ルールを持つウィジェット。
• 使用すべきでない場合: 単一のウィジェット固有の一度きりのロジック。

テストの命名と構造

• テストの命名: テストグループ名には文字列補間を使用します: group('ClassName', ではなく group('$ClassName',。これにより一貫性が確保され、より良いツールサポートが可能になります。
• テストのグループ化: group() を使用して、機能、クラス、状態ごとにテストを整理し、レポートをより明確にします。
• 説明的な名前: テスト名は、何をなぜテストするのかを明確に記述する必要があります。

よくあるテストエラー

• A RenderFlex overflowed...: テストではウィジェットを Expanded でラップするか、寸法を制約します
• Vertical viewport was given unbounded height: テストでは ListView を固定高さの SizedBox でラップします
• setState called during build: 状態変更をフレーム後のコールバックに遅延させます
• No MediaQuery widget ancestor: テストウィジェットを必ず MaterialApp でラップします

テストの実行（クイックリファレンス）

• flutter test: すべてのユニットテストとウィジェットテストを実行します
• flutter test test/path/to/file_test.dart: 特定のテストファイルを実行します
• flutter test integration_test/: 統合テストを実行します
• flutter test --coverage: カバレッジレポート付きで実行します
• dart test: 純粋な Dart ユニットテスト