flutter-device-testing

Flutter デバイステスト

変更された動作を証明できる最小限のターゲットマトリクスを使用し、何を検証し、何を検証しなかったかを明記してください。ランタイムターゲットと、フローで使用するデータソースは分けて示してください。

実行前に調査する

プロジェクトの SDK、対応プラットフォーム、フレーバー、エントリーポイント、既存のテストツールを確認してください。flutter devices を実行し、仮想ターゲットを起動する必要がある場合は flutter emulators も実行してください。安定した識別子でターゲットを1つ特定し、再利用するのかタスクで作成するのかを記録して、準備が整うまで待ってください。明示的な必要性と許可がない限り、ユーザーのターゲットを消去、リセット、再作成したり、アプリをアンインストールしたり、データを消去したりしないでください。

Flutter が管理する状態には、Flutter CLI と利用可能な Dart および Flutter MCP の機能を優先してください。adb または simctl は、それぞれが実際に提供するプラットフォーム制御にのみ使用してください。Flutter のファインダーでは、権限ダイアログ、通知トレイ、プラットフォームビューなどのネイティブシステム UI を操作できません。そのような操作が必要な場合は、プロジェクトですでに採用されているネイティブ対応のハーネスを使用してください。使い慣れているという理由だけで、Patrol、Maestro、Appium、その他のフレームワークを導入しないでください。

ワークフロー

1. プロジェクトのパッケージやアーキテクチャの選択を変更せずに、依存関係と生成コードの準備が整っていることを確認します。
2. ランタイムの状態を変更する前に、ターゲットの準備状況と、フレーバー固有のアプリケーション ID を確認します。
3. 正しいフレーバー、エントリーポイント、defines、ビルドモードで起動します。コマンド引数や保持される成果物に認証情報を含めないでください。
4. 正確なユーザーフローと、関連するライフサイクルまたはプラットフォームの状態を検証します。状態の注入と、実際のプロンプト、プロバイダー、OS 配信経路の観察を区別してください。
5. テスト対象のビルドに対応した、焦点を絞ったアサーション、スクリーンショット、フィルター済みログを取得します。永続的な自動化が必要な場合は、プロジェクトの統合テストまたはネイティブ UI ハーネスを実行します。
6. タスクで作成したターゲットの上書きを元に戻し、失敗時も含め、タスクが所有する成果物だけを削除します。

信頼性

ビルド、起動コマンド、OS トリガーが成功しただけで、アプリの動作が正しいと判断しないでください。ハードコードされた座標よりセマンティックファインダー、アクセシビリティ識別子、統合 API を優先し、任意のスリープより上限時間を定めた準備完了条件を優先してください。ウォームスタートを主張するには、トリガー前に意図したプロセスと UI の状態が成立していることを示す明示的な事前条件が必要です。ライフサイクルランナーを使用する場合は、すべてのフックに上限時間が適用されていることを確認してください。また、成功、失敗、タイムアウト、コマンドエラーの後に finally 経路から after のクリーンアップが試行されることも確認してください。

ターゲットの種類と安全なラベル、OS／ランタイム、ビルドモード、フレーバー、エントリーポイントまたは関連する defines、正確なフロー、データソース、アサーション、成果物、未検証の境界を報告してください。物理デバイスの生の識別子は、原則として公開しないでください。エミュレーターまたはシミュレーターでの動作は機能面の証拠であり、物理ハードウェアの性能、GPU、カメラ、センサー、OEM、本番環境のプッシュ通知に関する証拠ではありません。ベンチマークの帰属は flutter-performance に回し、より強いハードウェアに関する主張は、代表的な物理デバイスでプロファイルモードまたはリリース相当モードを使用して検証してください。

参考資料

• 共通のターゲット選択、所有権、準備完了状態、安全性、証跡のルールについては、デバイスの検出とエミュレーターをお読みください。
• Flutter と adb を使って Android の仮想ターゲットまたは物理ターゲットを起動・操作する場合は、Android エミュレーターの操作をお読みください。
• 権限、位置情報、スクリーンショット、シミュレートされたプッシュ通知など、Flutter と simctl を使って Simulator を操作する場合は、iOS Simulator の操作をお読みください。
• エージェントがプラットフォームのアクセシビリティツリー（idb、uiautomator）を通じて実行中のアプリを読み取る、または操作する必要がある場合、Flutter の画面でそのツリーが空の場合、あるいは座標やスクリーンショットの繰り返しではなく、安定した Semantics 識別子が必要な場合は、セマンティック UI の検査をお読みください。
• package:integration_test のテストスイート、ディープリンク、または実行中のターゲットでのスモークテストを作成または実行する場合は、統合テストのワークフローをお読みください。
• ディープリンクや通知のタップを、コールド／ウォームスタート、認証、重複配信、データの読み込み遅延、アカウント変更の各ケースで再生する必要がある場合は、ライフサイクルエントリーマトリックスをお読みください。プレースホルダーを解決し、--execute を追加する前に、付属のランナーをドライランで実行して、期待どおりの計画で正常終了することを確認してください。

ソース

• Flutter CLI
• 統合テスト
• Dart と Flutter の MCP サーバー