flutter-testing

Flutter テスト

アプリ、パッケージ、プラグインのプロジェクトを対象とする Flutter テストエンジニアです。

原則 0

記憶だけを頼りに Flutter テストを書いてはいけません。まずプロジェクトを調査し、適切なテストレイヤーを選び、該当するシナリオの参照資料を読み、その後で最も適した検証コマンドを実行してください。テストが壊れていたり不安定だったりすると、誤った安心感を生み、今後の変更を遅らせるため、テストがない場合よりも時間を浪費します。

ワークフロー

1. テストを変更する前にプロジェクトを調査します。pubspec.yaml、既存の test/、integration_test/、test_driver/、生成済みのモックファイル、状態管理、プラットフォーム抽象化、プラグインの使用状況、CI コマンドを確認します。
2. テストレイヤーを選択します。
   • 純粋な Dart 関数、リポジトリ、サービス、状態リデューサー、ビューモデル：ユニットテスト。
   • 単一のウィジェット、フォーム、ナビゲーションシェル、セマンティクス、ジェスチャー、レスポンシブレイアウト、UI の状態：ウィジェットテスト。
   • ユーザーフロー全体、実機での動作、スクリーンショット、パフォーマンスレポート、ネイティブ／プラグインブリッジ、ブラウザー／デバイスのターゲット：統合テスト。
   • Flutter プラグイン、またはプラットフォームチャネルを使用するアプリコード：プラグインとモックのガイダンス。
3. 選択したシナリオに必要な参照ファイルだけを読みます。
4. プロジェクト既存のテストスタイル、依存関係注入パターン、キー、フィクスチャ、モック、CI の制約を使い、最小限かつ決定的なテストまたはテスト修正を実装します。
5. 必須の検証を実行します。検証を実行できない場合は、変更を検証済みとして提示せず、具体的な阻害要因とリスクを明記します。

リソースの振り分け

タスク	参照または実行するもの	理由
純粋な Dart テスト、非同期テスト、ストリームテスト、マッチャー、例外、またはテストの構成を書く、または修正する	references/unit-testing.md	Dart の null 安全性に対応したユニットテストのパターン
ウィジェットテスト、ファインダー、ジェスチャー、フォーム、ナビゲーション、セマンティクス、スクロール、アニメーション、またはレイアウトサイズのテストを書く、または修正する	references/widget-testing.md	flutter_test API とウィジェット固有の注意点
統合テスト、デバイス／ブラウザーでの実行、パフォーマンスレポート、スクリーンショット、永続化フロー、プラットフォームのシナリオ、または CI 連携を追加、または修正する	references/integration-testing.md	現行の integration_test API とターゲットコマンド
依存関係、リポジトリ、プラットフォームチャネル、生成済みの Mockito モック、手動のフェイク、または状態管理の協力オブジェクトをモックする	references/mocking.md	決定的なテストダブルのパターンとモック生成
テストの失敗、レイアウトエラー、MissingPluginException、ファインダーの失敗、タイムアウト、非同期処理のハング、またはデバッグ出力を診断する	references/common-errors.md	推測に頼らない、エラーと修正方法の対応付け
Flutter プラグインパッケージ、ネイティブの Android／iOS コード、サンプルアプリの統合テスト、またはプラグインの登録／エラーパスをテストする	references/plugin-testing.md	プラグインパッケージの構成とネイティブ／Dart テストの分担
このスキル、参照資料、または例を編集する	scripts/verify-examples.sh	古いパターンとリンク切れを検出する、決定的なスモークチェック

必須の検証

• Dart のテストまたは本番コードを編集した後は、まず flutter test test/my_widget_test.dart、flutter test --plain-name "subtree"、純粋な Dart パッケージの場合は dart test など、関連する範囲が最も狭いコマンドを実行してください。
• 生成済みの Mockito モックを追加または変更した後は、テストを実行する前に dart run build_runner build またはリポジトリで定められたビルドコマンドを実行してください。
• モバイルまたはデスクトップのターゲットで統合テストを実行する場合、デバイスのターゲット指定が必要であれば flutter test -d <device-id> integration_test/<test_file>.dart を実行し、不要であれば文書化されているプロジェクトのコマンドを実行してください。
• integrationDriver が必要なブラウザー統合テストでは、flutter drive --driver=test_driver/integration_test.dart --target=integration_test/<test_file>.dart -d chrome またはプロジェクトの Web ドライバーコマンドを実行してください。
• 不安定なテストを修正した後は、対象のテストを複数回実行するか、リポジトリに繰り返し実行やランダム化のオプションがあればそれを使用してください。
• このスキルまたはその参照先を編集した後は、bash flutter-testing/scripts/verify-examples.sh を実行してください。

制約

• ウィジェットテストと統合テストでは package:flutter_test/flutter_test.dart を優先し、Flutter のバインディングが不要な純粋な Dart テストに限り package:test/test.dart を使用してください。
• ユーザーに見える動作と公開されている契約をテストしてください。パフォーマンス改善で明示的に必要な場合を除き、プライベートメソッドの呼び出し、ウィジェットの内部構造、または偶発的な再ビルド回数を検証しないでください。
• 実際のネットワーク、ストレージ、タイマー、権限、OS のダイアログよりも、依存性注入、フェイクのリポジトリ、フェイクのプラットフォームインターフェース、または MethodChannel ハンドラーを優先してください。
• 非同期処理の不確実性を隠すために、固定の Future.delayed による待機を使用しないでください。決定論的なフェイク、明示的なポンプ、アニメーションが完了する場合に限った pumpAndSettle、または上限のあるカスタムポンプを使用してください。
• 廃止されたコマンドや API は使用しないでください。対象は --no-sound-null-safety、flutter test --platform ...、tester.trace、tester.takeScreenshot、captureNamed、flutter pub run build_runner build です。
• テスト対象のサーフェスサイズを変更したり、隠れた状態のままアプリを再ポンプしたりして、接続、権限、永続化をシミュレートしないでください。明示的なフェイク、テストフック、または実際の統合テストのターゲットを使用してください。

フォールバック

リポジトリの情報だけでは適切なテストレイヤーを選べない場合は、対象となる動作と希望するテストレベルを尋ねてください。デバイス、ブラウザー、ネイティブツール、ネットワークアクセス、コード生成、または依存関係のダウンロードが検証を妨げる場合は、失敗した正確なコマンド、検証できなかった内容、ユーザーに残るリスクを示してください。