Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

Android インストルメンテーション用の Developer Device Platform デバイスラン

このガイドでは、gcloud beta device-run CLI を使用して Android インストルメンテーションテストを実行し、 Google Cloud コンソールで結果を確認する方法について説明します。 Google Cloud アカウントとプロジェクトがあることを前提としています。

Firebase Test Lab から Developer Device Platform に移行する場合は、移行ガイド、コマンドとフラグの変換、AI エージェントの移行スキルをご覧ください。

この Google Cloud CLI を使用するには、 Google Cloud プロジェクト ID を指定する必要があります。コマンドの概要については、gcloud beta device-run をご覧ください。

始める前に

以下の手順は、すでに次の処理が行われていることを前提としています。

Google Cloud プロジェクトを作成済みであること。
クイックスタートに沿って Developer Device Platform を設定します。
ターミナルで gcloud を使用して認証されている。
デバイスランの概要で一般的な情報を確認している。
Android 用のインストルメンテーションテストを作成しました。

ステップ 1. テスト実行を構成する

Android インストルメンテーションテストのオプション

複数のデバイス: 複数のデバイスで同じテストを実行するには、--device フラグに複数のデバイス ID をカンマ区切りで指定します（例: --device shiba-34,tokay-36）。または、複数の --device フラグにそれぞれ異なるデバイス ID を指定します（例: --device shiba-34 --device tokay-36）。
デバイスにファイルを push する: --other-files-to-push=SOURCE=DEST,... を使用して、実行前にデバイスに追加のファイル（ML モデルの重み、テスト入力、.so 共有ライブラリなど）を push します。SOURCE は、ローカルパスと Cloud Storage（gs://...）パスの両方をサポートしています。DEST は、デバイス上の宛先パスです。
デバイスからファイルを pull する: 実行が完了したら、--paths-to-pull=DEVICE_PATH,... を使用して、生成されたファイルまたはディレクトリをデバイスから pull します。
カスタム Cloud Storage バケット: --bucket-name= を使用して、既存の Cloud Storage バケット名を指定します（gs:// スキームまたはパスは指定しません）。バケットを指定しない場合、Google Cloud CLI は PROJECT_ID-devicerun という名前のデフォルトバケットを使用または作成します。
フレーキーテストの再試行: フレーキーテストを処理するために、ジョブまたはシャードあたりの最大試行回数を設定します。--flaky-test-attempts=3（デフォルトは 1 回）。
デバイス環境と診断: デバイスの向き（--orientation=portrait または landscape）、言語 / 地域（--locale=en-US）、モック GPS 位置情報（--coordinates=LATITUDE,LONGITUDE）、画面の動画録画（--video=always または on-failure）、dumpsys の収集（--dumpsys=always または on-failure）、bugreport の収集（--bugreport=always または on-failure）を構成します。
ラベル: --labels=KEY=VALUE,... を使用して、ユーザー定義の Key-Value ラベルをセッションにアタッチします。
追加のアプリ: 必要に応じて、--apps=path1,path2,...,path_n フラグを使用して、テストを実行する前にインストールする APK、AAB、または APKS ファイルを 1 つ以上指定できます。指定した順序でアプリがインストールされます。
テストタイムアウト: 実行時間を制限します。--instrumentation-timeout=10m（有効な範囲は 1m～3h、デフォルトは 5m）。

同期実行と非同期実行

デフォルトでは、submit コマンドはブロッキング（同期的）です。テストが完了するまで待機し、結果の概要テーブルを出力します。

セッションを送信し、ファイルを Cloud Storage にアップロードした直後に戻るには、--async フラグを追加します。

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

これにより、セッション ID がすぐに返されます。sessions wait コマンドを使用して、完了を待機できます。

gcloud beta device-run sessions wait SESSION_ID

このコマンドは、ジョブが完了するまでブロックされます。

複数のデバイス

複数のデバイスで同じテストを実行するには、--device フラグに複数のデバイス ID をカンマで区切って指定するか、複数の --device フラグにそれぞれ異なるデバイス ID を指定します。

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

または

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

テストのタイムアウト

テストの実行時間を制限します。

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

有効な範囲は 1m～3h で、デフォルトは 5m です。

ソフトウェアバージョン

利用可能なソフトウェアパッケージと AndroidX Test Orchestrator のバージョンを検出して使用し、テスト実行を構成する前に、それらのライフサイクル、サポートされているバージョン、メタデータを検査します。

まず、利用可能なすべてのソフトウェアパッケージとそのバージョンを一覧表示します。

gcloud beta device-run software-versions list

出力は次のようになります。

ID                                NAME                              SOFTWARE_TYPE               VERSION  STATE   IS_DEFAULT
androidx-test-orchestrator-1-4-1  AndroidX Test Orchestrator 1.4.1  ANDROIDX_TEST_ORCHESTRATOR  1.4.1    ACTIVE  True
androidx-test-orchestrator-1-6-1  AndroidX Test Orchestrator 1.6.1  ANDROIDX_TEST_ORCHESTRATOR  1.6.1    ACTIVE
xcode-16-4                        Xcode 16.4                        XCODE                       16.4     ACTIVE
xcode-26-2                        Xcode 26.2                        XCODE                       26.2     ACTIVE  True

次に、リストから正確なリソース ID を使用して、特定のパッケージを記述します。

gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1

出力は次のようになります。

id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
  state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1

使用可能なソフトウェアバージョンがわかったので、次のように --orchestrator-version フラグを使用してテスト実行で使用できます。

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

Orchestrator を有効にする

Developer Device Platform は Android Test Orchestrator をサポートしています。これにより、アプリのテストをそれぞれの Instrumentation 呼び出し内で行えます。

Orchestrator を使用すると、次のことが可能になります。

共有状態を避ける。各テストは、それぞれ独自の Instrumentation インスタンスで実行されます。そのため、テストでアプリの状態を共有している場合、その共有状態のほとんどは、各テストの後にデバイスの CPU やメモリから削除されます。各テストの後にデバイスの CPU とメモリからすべての共有状態を削除するには、次のように clearPackageData 設定を追加します。--additional-test-options clearPackageData=true
クラッシュを特定する。1 つのテストがクラッシュした場合でも、その Instrumentation インスタンスのみが削除されます。つまり、他のテストは引き続き実行され、完全なテスト結果が提供されます。

Android Test Orchestrator は、Developer Device Platform ではデフォルトでオフになっています。Orchestrator を有効にし、テスト実行時に使用するバージョンを指定するには、次のように、sessions submit instrumentation コマンドの --orchestrator-version=ORCHESTRATOR_VERSION フラグに選択したバージョンを渡します。

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

システムデフォルトの Orchestrator バージョンを使用するには、フラグを auto に設定します。

ステップ 2. デバイスを選択

device-run CLI を使用すると、利用可能な物理デバイスと仮想デバイスで Android テストを実行できます。利用可能なデバイスの全リストを表示するには、インタラクティブなデバイスカタログにアクセスするか、次のコマンドを実行します。

gcloud beta device-run devices list

出力例:

ID        MAKE    NAME     MODEL FORM      OS_VERSION CAPACITY  AVAILABILITY  PRODUCTS
tegu-35   Google  Pixel 9a tegu  PHYSICAL  35         MEDIUM    LOW           Automation, Streaming
tokay-34  Google  Pixel 9  tokay PHYSICAL  34         HIGH      HIGH          Automation, Streaming

このリストをフィルタする方法については、デバイスカタログをご覧ください。実行対象として特定のデバイスを指定するには、submit コマンドで対応する ID（tegu-35 など）を使用します。

ステップ 3. テストを実行する

Android インストルメンテーションテスト APK を送信します。

Android インストルメンテーションテストには、次のフラグが必要です。

デバイス: --device を使用してデバイスを指定します。--device shiba-35
Test: --test: --test /path/to/test.apk を使用してテスト APK を指定します。

インストゥルメンテーションテストを実行するには、独自のデバイス ID とテストパスを使用して、次のような sessions submit instrumentation コマンドを発行します。

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --apps /path/to/app.apk \
  --test /path/to/test.apk

ジョブの結果レポートフォルダは、gs://BUCKET_NAME/automation/sessions/SESSION_ID/ などの Cloud Storage パスにあります。コマンド出力で、https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/ のようなリンクを確認します。

ステップ 4. シャーディングを使用する

Developer Device Platform のインストルメンテーションテストを継続的インテグレーションと継続的デリバリー（CI/CD）のワークフローに含めるには、テストのシャーディングを検討する必要があります。テストのシャーディングによって、一連のインストルメンテーションテストをサブグループ（シャード）に分割し、それぞれ分離して実行できるようにします。Developer Device Platform は自動的に各シャードを複数のデバイスで並行して実行するため、テスト全体を完了するまでの時間が短縮されます。

ステップ 4.1. シャーディングオプションの選択

ジョブのテストケース数が少ない場合や、すべてのテストケースの合計実行時間が長くない場合は、シャーディングを使用する必要はありません。テストケースの数が多い場合や、すべてのテストケースの合計実行時間が長い場合は、シャーディングの使用を検討してください。

Developer Device Platform は、スマートシャーディングと均一シャーディングの両方をサポートしています。テストをシャーディングする方法を決定する際は、次のオプションを検討してください。

すべてのテストケースに同様の時間がかかる場合は、すべてのテストケースを n 個のシャードに分割して、均一なシャーディングを使用します。
異なるテストケースの実行時間が大きく異なる場合は、スマートシャーディングを使用します。Developer Device Platform は、過去のテスト実行時間を使用して異なるシャードを作成し、すべてのシャードを同様の期間で完了しようとします。

均一なシャーディング

均一シャーディングでテストをシャーディングするには、次のように sessions submit instrumentation コマンドに --sharding-option=uniform フラグと --uniform-sharding-count= フラグを含めます。

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
 --device shiba-34,tokay-36 \
    --sharding-option=uniform \
    --uniform-sharding-count=2

Job status: 2 running を示す出力が表示されます。このサービスは、デバイスごとに 1 つずつ、2 つのジョブを作成します。両方のジョブへの入力は同じであるため、サービスは検証を一元化し、1 回だけ実行します。

完了すると、コマンドの最終出力に 2 つのジョブが個別に表示されます。

JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED

スマートシャーディング

スマートシャーディングでテストをシャーディングするには、次のように sessions submit instrumentation コマンドに --sharding-option=smart、--smart-sharding-max-shard-count=、--smart-sharding-target-duration=（分単位または 1 時間）、--smart-sharding-record-name= フラグを含めます。

gcloud beta device-run sessions submit instrumentation \
    --test path/to/test.apk \
    --device shiba-34,shiba-35,tokay-36 \
    --sharding-option=smart \
    --smart-sharding-max-shard-count=3 \
    --smart-sharding-target-duration=5m \
    --smart-sharding-record-name=test.yaml

3 つのジョブが実行されたことを示す最終出力が表示されます。

Session [session-3cd0564a] finished with result [ERROR].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   PASSED
job-001   execution-000   PASSED
job-002   execution-000   PASSED

ここで使用されているスマートシャーディングフラグの概要は次のとおりです。

--smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT - スマートシャーディング用に作成するシャードの最大数を指定します。未設定または 0 に設定すると、システム定義の上限が使用されます。有効な範囲は、実機の場合は 0 ～ 20、仮想デバイスの場合は 0 ～ 200 です。
--smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION - スマートシャーディングのシャードあたりの目標実行時間（2m、10m、1h など）を指定します。有効な範囲は 2 分～ 1 時間です。--sharding-option=smart の場合は必須。
--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - スマートシャーディングレコードファイルの名前を指定します（ファイル拡張子は除く）。--sharding-option=smart の場合に必要です。この YAML ファイルは、smart-sharding/ ディレクトリの --bucket-name で指定された Google CloudStorage バケットにあります。ファイルが存在しない場合は自動的に作成されます。存在する場合は、セッションの完了時に内容が更新されます。

ステップ 5. テスト実行を調べて管理する

sessions submit instrumentation コマンドの非同期モードと同期モードの両方で、sessions describe コマンドを使用して、実行中にジョブステータスをクエリするか、完了後に結果を取得できます。

gcloud beta device-run sessions describe SESSION_ID

出力には、テスト結果の概要と、 Google Cloud コンソールの結果へのリンクが表示されます。次に例を示します。

Session SESSION_ID finished with result [FAILED].
Result files are stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

次のコマンドを使用して、実行中および完了したすべてのセッションを一覧表示します。

gcloud beta device-run sessions list

プロジェクト内のセッションのリストを含む出力が、次のように表示されます。

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE
session-67cd0570                              2026-07-16T08:25:55.474Z  DONE
session-17cc299c                              2026-07-14T14:31:33.649Z  DONE
session-911d0763                              2026-07-09T00:39:02.051Z  DONE
session-4e943fea                              2026-07-15T23:08:32.252Z  DONE
session-0132e458                              2026-08-20T18:33:19.751Z  DONE
session-1077f07b                              2026-07-28T22:35:43.848Z  DONE
session-71b054c6                              2026-07-15T01:15:41.643Z  DONE
session-4f8b2e45                              2026-08-06T23:11:56.161Z  DONE

sessions list コマンドは、すべての標準の Google Cloud CLI フラグオプションをサポートしています。次に例を示します。

gcloud beta device-run sessions list --limit 5

結果は次のようになります。

SESSION_ID                            START_TIME                STATE
session-4825e153                      2026-07-28T16:38:43.155Z  DONE
session-813ca602                      2026-07-28T22:40:32.415Z  DONE
93ec2df2-d5bf-4c36-b7f7-c2a4fb0dc3ce  2026-07-03T05:10:58.015Z  DONE
session-67cd0570                      2026-07-16T08:25:55.474Z  DONE
session-17cc299c                      2026-07-14T14:31:33.649Z  DONE

実行中のすべてのセッションを検索するには、次のコマンドを実行します。

gcloud beta device-run sessions list --filter RUNNING

実行中のセッションがある場合は、次のような結果が表示されます。

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

それ以外の場合は Listed 0 items. が返されます。

実行中のセッションをキャンセルするには、セッション ID を指定して次のコマンドを実行します。

gcloud beta device-run sessions cancel SESSION_ID

セッションはキャンセル対象としてマークされるだけなので、コマンドはすぐに戻ります。キャンセルはバックエンドで非同期に行われます。

セッションがすでに終了している場合は、現在のステータスのみが出力されます。完了したセッションのキャンセルをリクエストしてもエラーにはなりません。

次のステップ

次に、Android 実行可能ファイルを実行するか、ログを検索して分析します。