mobile-testing

iOS シミュレーターでは通るログインテストが、実機では、想定していなかった位置情報の許可ダイアログが画面に表示されたままになり、いつまでも止まってしまう――このスキルは、こうしたモバイル特有の失敗を防ぎます。ネイティブ、React Native、ハイブリッド、Flutter アプリに対応する実行可能なテストスイートを、アプリの種類に適したフレームワーク、実機とエミュレーターのテスト段階、そしてウェブフレームワークでは対応できないシナリオ（ディープリンク、プッシュ通知、生体認証、オフライン、許可ダイアログ）への標準対応とともに提供します。

---

クイックルート

状況	移動先
アプリの種類に応じたフレームワークの選択	フレームワークの選定
ネイティブ／ハイブリッドの Appium 設定＋セレクター＋ジェスチャー	Appium 3.x → references/appium-patterns.md
React Native のテストスイート	React Native 向け Detox → references/detox-and-maestro.md
手軽なクロスプラットフォーム YAML	クロスプラットフォーム YAML に対応する Maestro → references/detox-and-maestro.md
クラウドデバイスマトリックス（P0/P1/P2）	デバイスファーム → references/device-farm.md
ディープリンク、プッシュ通知、生体認証、オフライン、許可設定	モバイル特有のパターン → references/mobile-patterns.md

---

確認事項

まずプロジェクトルートにある .agents/qa-project-context.md を確認してください。ファイルがある場合はその情報を使い、すでに回答されている質問は省略してください。

1. アプリの種類： ネイティブ iOS／Android、React Native、Flutter、またはハイブリッド（Cordova／Capacitor）のどれですか？ここからフレームワークを選定します（フレームワークの選定を参照）。
2. 実機とエミュレーターのどちらを使いますか？ リリース検証とパフォーマンス確認には実機を、開発の迅速化にはエミュレーター／シミュレーターを使います。多くのチームでは両方が必要です。
3. デバイスファーム： BrowserStack App Automate、Sauce Labs、AWS Device Farm、それともセルフホスト環境ですか？予算と CI との統合方法を基準に決めます。
4. OS の対応範囲： iOS と Android の最低対応バージョンはいくつですか？マトリックスを作る前に、実際のユーザー分布をアナリティクスで確認してください。最新のハードウェアをデフォルトで対象にしないでください。
5. 既存の CI パイプライン： モバイルテストはどこで実行しますか？ローカルマシン、エミュレーターを備えた CI ランナー、またはクラウドデバイスファームですか？
6. アプリの配布方法： テストビルドはどのように配布しますか？TestFlight、Firebase App Distribution、直接配布する APK／IPA のどれですか？これによって、デバイスファームへのバイナリの受け渡し方法が決まります。

---

基本原則

1. リリースには実機、迅速なテストにはエミュレーターを使います。 エミュレーターでは、タッチの遅延、GPS のずれ、カメラ特有の挙動、プッシュ通知のタイミング、バッテリーの動作を再現できません。開発と PR チェックではエミュレーターを使い、実機デバイスファームは夜間テストとリリースパイプラインに限って使用します。

2. ジェスチャーのシミュレーション方法はフレームワークごとに異なります。 Appium の W3C Actions、Detox のデバイス API、プラットフォームネイティブのジェスチャーレコグナイザーでは、スワイプ、ピンチ、長押しの扱いがそれぞれ異なります。フレームワークをまたいでそのまま使えると思い込まないでください。

3. ディープリンクとプッシュ通知はモバイル特有の機能です。 ウェブテストフレームワークでは対応できません。それぞれに専用のパターンがあるため、後回しにせず、第一級のテストシナリオとして扱ってください。

4. 許可ダイアログは前提を崩します。 iOS と Android では、実行時の許可設定の扱いが異なります。カメラ、位置情報、連絡先、通知の許可は、セットアップ時に明示的に処理する必要があります。処理しないと、閉じられないダイアログを待ち続け、テストが停止します。

5. モバイルではネットワーク状況がより重要です。 ユーザーは WiFi、LTE、3G、オフラインの間を切り替えます。問題なく使える WiFi だけでなく、ネットワークが劣化した状態や接続がない状態もテストしてください。

6. プラットフォーム固有の処理には、プラットフォームガードが必要です。 Android で動作するシェルコマンド、セレクター、デバイス API が iOS に存在するとは限りません（逆も同様です）。プラットフォーム固有のコマンドを実行する前に platformName で分岐してください。そうしないと、もう一方のプラットフォームではテストがエラーを出さずに失敗します。

---

フレームワークの選定

アプリの種類	主な選択肢	理由
ネイティブ iOS／Android、ハイブリッド	Appium 3.x	ドライバーベースで、成熟したエコシステムを備え、ネイティブ操作とジェスチャーのカバー範囲が最も広い
React Native	Detox	グレーボックス方式で、RN ブリッジと同期し、フィードバックが最速で、不安定さが最も少ない
クロスプラットフォーム、スキルが異なるメンバーで構成されたチーム	Maestro	宣言型 YAML、ネイティブの AI コマンド、作成時の負担が最も少ない
Flutter	Patrol 4.x	Flutter ネイティブの統合テスト。4.0 でウェブサポート（Playwright 経由）と、より充実したネイティブ操作 API が追加されました

---

Appium 3.x

Appium 3.x（2026 年現在の最新安定版系列）では、2.0 で導入されたドライバーベースのプラグインアーキテクチャが維持されています。サーバーは薄いシェルであり、ドライバーがプラットフォーム固有の自動化を提供します。2.x からのアップグレードでは、主に Node のバージョン更新と依存関係の整理が必要です。ほとんどのケイパビリティは引き続き使用できますが、Appium 3 では長らく非推奨だったコマンドがいくつか削除され、プラグインとドライバーの扱いも変更されたため、削除されたレガシーコマンドについては 3.x の移行ノートを確認してください。

セレクターの優先順位： アクセシビリティ ID > プラットフォーム固有のセレクター（iOS のクラスチェーン／Android の UIAutomator） > XPath（最後の手段。低速で壊れやすい）。

プラットフォーム固有のコマンドには条件分岐を設けてください。 プラットフォーム限定のシェルコマンド、セレクター戦略、デバイス API を使う前に、platformName に基づいて分岐してください。

if (driver.capabilities.platformName === 'Android') {
  // UIAutomator selectors, `mobile: shell` network toggles
} else {
  // iOS class chain / predicate selectors, `mobile: alert`, device-farm network profiles
}

インストール／ドライバーのコマンド、W3C Android／iOS ケイパビリティ、4 種類の要素検索方法、ジェスチャー一式（スクロール、スワイプ、ピンチ、長押し、ダブルタップ）については、references/appium-patterns.md を参照してください。

---

React Native 向け Detox

Detox はグレーボックス方式のフレームワークです。React Native ブリッジと同期し、アニメーション、ネットワークリクエスト、タイマーが落ち着くのを待ってから操作するため、タイミングに起因する不安定さの大半を解消できます。

Detox は新アーキテクチャを含む React Native 0.77～0.84 をサポートしています。デフォルトでは by.id／by.text マッチャーを使用し、壊れやすい厳密なクラス一致のアサーションを緩和する場合にのみ by.type() を使ってください。

生体認証の順序に関するルール： device.matchBiometric() を呼び出す前に、device.setBiometricEnrollment(true) で生体認証を登録してください。事前に登録せずに照合しても何も起こらず、認証フローが先に進みません。

プッシュ通知は sendUserNotification による iOS 専用です。 Android では Detox のプッシュ通知処理は限定的で、sendUserNotification の動作も異なります。iOS と同等の動作を前提とせず、Android のプッシュ通知は FCM／通知シェード経由（Appium のパターン）で操作してください。

.detoxrc.js の設定、ログインフローのテストパターン、デバイス API（生体認証、シェイク、画面の向き、位置情報、ディープリンク、通知）、CI のビルド／テストコマンドについては、references/detox-and-maestro.md を参照してください。

---

Maestro（クロスプラットフォーム YAML）

Maestro CLI 2.5.x（2026 年 4 月）は、クロスプラットフォームのモバイル E2E テストを最も手軽に実行できる選択肢です。宣言型の YAML フロー、ネイティブの AI 支援コマンド（セレクターなしで assertVisible: 'login button' が動作します）を備え、シミュレーター、実機、Maestro Cloud で実行できます。Appium の Java／JS スタックや、React Native 専用の Detox ツールを使いたくないチームに最適です。

# macOS (preferred — lower friction, brew-managed):
brew tap mobile-dev-inc/tap && brew install mobile-dev-inc/tap/maestro
# Or the cross-platform curl one-liner:
curl -Ls "https://get.maestro.mobile.dev" | bash

Maestro を選ぶケース：クロスプラットフォームのテストスイート、スキルが異なるメンバーで構成されたチーム、迅速な反復。選ばないケース：高度なネイティブジェスチャーや生体認証のカバーが必要な場合（Appium／Detox が適しています）、または細かなプログラム制御が必要な場合。

${MAESTRO_TEST_PASSWORD} 環境変数の注入を含む、注釈付きのログインフロー YAML については、references/detox-and-maestro.md を参照してください。

---

デバイスファームとの統合

最新のハードウェアではなく、分析データに基づいて段階的なデバイスマトリックスを構成してください。一般的な割合は、P0 デバイスでテストの 60％、P1 で 30％、P2 で 10％です。テストアプリをファームにアップロードし、ケイパビリティ（app URL／storage:filename）で参照します。

BrowserStack と Sauce Labs のケイパビリティオブジェクト、認証付きアプリアップロード用の curl、GitHub Actions のデバイスマトリックス戦略（iOS と Android の P0／P1／P2）については、references/device-farm.md を参照してください。

---

モバイル固有のテストパターン

これらのシナリオはウェブフレームワークではテストできません。それぞれを第一級のフローとして扱ってください。

• ディープリンク — コールドスタート（アプリを終了してからディープリンク）、認証後のリダイレクト、起動中のアプリ内でのナビゲーション。
• プッシュ通知 — Detox の sendUserNotification（iOS）と、Appium + FCM テストエンドポイント／通知シェードのパターン（Android）。
• オフライン／低速なネットワーク — プラットフォームごとに分岐：Android の mobile: shell による機内モード、デバイスファームのネットワークプロファイル、iOS のコンディショナー／Detox プロキシに関する注意事項。
• 権限ダイアログ — autoGrantPermissions（Android）、明示的な mobile: alert（action: accept／dismiss）と -ios predicate string の処理（iOS）。
• 生体認証 — Detox の setBiometricEnrollment(true) の後に matchBiometric() を実行します（一致確認の前に登録します）。
• アプリのライフサイクル — バックグラウンド／フォアグラウンド、コールドスタート、新規インストールと再開。

プラットフォームごとに分岐する機内モードのスニペットや、iOS と Android の権限処理の違いを含む実行可能なコードについては、references/mobile-patterns.md を参照してください。

---

アンチパターン

すべてのテストをエミュレーターのみで実行する。 エミュレーターでは、タッチの遅延、カメラの動作、GPS のずれ、プッシュ通知のタイミングを再現できません。開発速度を上げるためにエミュレーターを使い、リリース用テストスイートはデバイスファーム経由で実機上で実行してください。

テストでデバイス名をハードコードする。 await driver.$('Samsung Galaxy S24 - Home') はデバイスを変更すると動作しなくなります。アクセシビリティ ID とプラットフォームに依存しないセレクターを使用してください。

プラットフォームチェックのない、プラットフォーム固有のコマンド。 cmd connectivity airplane-mode は新しい Android でしか使えず、iOS ではまったく使えません。プラットフォームを確認せずに実行すると、もう一方のプラットフォームでは何も通知されずに失敗します。まず platformName に応じて分岐してください（Appium 3.x を参照）。

アプリの権限を無視する。 権限が事前に許可されていることを前提とするテストは、初回インストール時や拒否フローのテスト時に失敗します。プラットフォームごとに権限を明示的に処理してください。

生体認証を登録せずに照合する。 事前に setBiometricEnrollment(true) を実行せずに matchBiometric() を呼び出しても、何も起こりません。認証が完了せず、ログイン画面でテストがタイムアウトします。

縦向きでしかテストしない。 多くのアプリは横向きで不具合が発生します。特にタブレットでは、重要なフローを両方の向きでテストしてください。

オフラインのシナリオを省略する。 モバイルユーザーは常に接続が失われる可能性があります。アプリがオフライン状態を適切に処理できない場合は、そのことを実証してください。処理できる場合は、その動作を検証してください。

フレームワークの同期機能の代わりに sleep() を使う。 Detox は自動で待機し、Appium には暗黙的な待機と明示的な待機があります。sleep() による同期は、どちらでも遅く、動作が不安定になります。

アプリのサイズと起動時間を無視する。 コールドスタートに 6 秒かかる 200MB のアプリは、実際の UX 上の問題です。バイナリサイズと起動時間の非機能チェックを含めてください。（起動時／メモリ／バッテリーの詳細なプロファイリングには、performance-testing を使用してください。）

---

検証

セットアップしたフレームワークに応じて、最小限のチェックを実行してください。テストスイートを完了とする前に、各チェックが終了コード 0 で終了し、期待する出力を表示する必要があります。

# Appium: drivers installed and server reachable
appium driver list --installed        # lists uiautomator2 and/or xcuitest
appium --version                       # prints the 3.x version

# Detox: one config builds and a smoke spec passes
detox test --configuration ios.sim.debug --headless   # green run on the iOS simulator

# Maestro: a single flow runs end-to-end
maestro test flows/login.yaml          # prints "Flow Passed"

---

完了条件

• デバイスマトリックスを定義してコミットしている（例：device-matrix.md または CI のマトリックスブロック）。各プラットフォームの実機とエミュレーターを含め、分析データに基づいて P0／P1／P2 に階層化している。
• 単一の CI 設定（マトリックス戦略またはペアのジョブ）から、iOS と Android の両方でテストスイートを実行できる。
• ジェスチャーテスト（スワイプ／スクロール／長押し）とディープリンクのコールドスタートテスト（終了 → ディープリンク → 対象画面をアサート）が、コミット済みのテストファイルとして存在する。それぞれのパスを記載する。
• プッシュ通知のカバレッジは、コミット済みのテストファイルのパス、または追跡対象の延期チケット ID（例：「JIRA-1234：FCM テストエンドポイントが利用可能になるまで延期」）のいずれかが存在する。コードコメントだけでは不十分。
• appium driver list --installed／detox test --configuration ios.sim.debug／maestro test flows/login.yaml（該当するもの）が、ローカルで終了コード 0 となる。
• CI では、すべての PR で各プラットフォームのエミュレーターを少なくとも 1 つ使用してテストを実行する（iOS シミュレーター + Android エミュレーター）。実機デバイスファームでの実行は、夜間実行またはリリースブランチに限定する。

参考ファイル（references/ 内）

• appium-patterns.md — Appium 3.x のインストール、W3C capabilities、要素の位置特定戦略、ジェスチャーのシミュレーション、プラットフォームガードパターン。
• detox-and-maestro.md — Detox の .detoxrc.js 設定、テストパターン、デバイス API（生体認証の順序、プッシュ通知は iOS のみという注記）、CI コマンド。さらに、Maestro のインストール（brew + curl）と YAML フロー。
• device-farm.md — BrowserStack と Sauce Labs の capabilities、認証付きアプリアップロード用 curl、GitHub Actions の P0/P1/P2 デバイスマトリックス。
• mobile-patterns.md — ディープリンク、プッシュ通知、プラットフォームガード付きネットワークシミュレーション、iOS／Android の権限ダイアログ、アプリのライフサイクルに関する実行可能なコード。

関連スキル

• ci-cd-integration — モバイルテスト実行のパイプライン設定、アーティファクト管理、デバイスファーム CI コネクター。
• cross-browser-testing — デバイスマトリックスの設計では、ブラウザマトリックスの手法を応用しています。抽象的なマトリックス戦略についてはそちらを、モバイルでの実行についてはこちらを参照してください。
• performance-testing — モバイルの非機能テストの詳細：アプリの起動時間、メモリ使用量、バッテリー消費。
• visual-testing — モバイルのビューポートキャプチャを含む、スクリーンショット／ピクセル差分による回帰テスト。
• test-data-management — モバイルアプリのシードデータ戦略、API を介したバックエンド状態のセットアップ。
• test-reliability — モバイルのタイミング、デバイス状態、ネットワーク条件に関する実行時の不安定なテストの修復。