android-emulator-automation

Android エミュレーターの自動化

使用するタイミング

• リクエストが Android エミュレーターの自動化、adb によるセマンティック UI 自動化、UIAutomator のダンプとタップに関する場合に、このスキルを使用します。
• 主な目的：セマンティックな ADB と UIAutomator のワークフローを使用して、エージェントから Android アプリを調査、起動、操作します。
• エージェントが APK を起動したり、現在の画面を調査したり、Espresso や Compose の UI テストを書かずに再現性のある操作を実行したりする必要がある場合に、このスキルを使用します。
• 対象範囲が広がる場合は、次のスキルに引き継ぎます。
• android-testing-ui
• android-permissions-activity-results

ワークフロー

1. 操作を試みる前に、Android SDK、adb、対象のデバイスまたはエミュレーター、起動完了を確認します。
2. リクエストの対象が適切なアーティファクトに紐づくよう、パッケージを明示して対象アプリをインストールまたは起動します。
3. 現在の UI 階層をダンプし、生の座標よりも、テキスト、コンテンツの説明、リソース ID などのセマンティックセレクターを優先します。
4. ワークフローを確認できる最小限の操作を実行し、状態の変化が重要な場合は画面を再度ダンプします。
5. 自動化の手順が明らかになったら、長期的なリグレッションテストは UI テストに引き継ぎます。

ガードレール

• セマンティックセレクターをピクセル座標より優先します。座標を使うのは、UI ツリーに必要なメタデータがない場合に限ります。
• 自動化は調査やスモークテストのためのツールとして扱い、再現性のある UI テストの代替にはしません。
• 入力コマンドを実行する前に、デバイスの状態、パッケージ名、起動完了を確認します。
• 破壊的なシェルコマンドやデバイス全体の設定変更を避け、CI で安全に使えるスクリプトにします。

アンチパターン

• テキストやリソース ID が利用できるのに、座標をハードコードする。
• デバイスの起動が完了する前にエミュレーターコマンドを実行する。
• 不安定な単発の自動化を、安定した UI ワークフローの証拠として扱う。
• アプリのインストール、操作、ログの取得を、中間出力のない不透明なスクリプトにまとめる。

例

成功例

• シナリオ：Compose のフィクスチャをビルドし、エミュレーターにインストールして、現在の OrbitTasks 画面をダンプします。
• コマンド：bash skills/android-emulator-automation/scripts/run_examples.sh

エッジケース

• シナリオ：プリインストールされたアプリを起動し、画面座標に頼らず、特定のセマンティックコントロールを対象にします。
• コマンド：python3 skills/android-emulator-automation/scripts/navigator.py --find-text "Blocked" --tap

失敗からの復旧

• シナリオ：セレクターの不具合を追跡する前に、デバイスが検出可能であり、UIAutomator で階層をダンプできることを確認します。
• コマンド：python3 skills/android-emulator-automation/scripts/device_health.py --json

完了チェックリスト

• 対象のパッケージ、デバイスのシリアル番号、現在の画面が明確になっています。
• 座標よりもセマンティックセレクターを優先しました。
• 自動化の手順をローカル開発環境と CI で再現できます。
• ワークフローにリグレッションテストが必要な場合、リクエストを UI テストに引き継ぎます。

公式リファレンス

• https://developer.android.com/studio/run/emulator
• https://developer.android.com/tools/adb
• https://developer.android.com/training/testing/other-components/ui-automator
• https://developer.android.com/studio/test/command-line