Android 向け Developer Device Platform Device Run

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

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

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

始める前に

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

  1. Google Cloud プロジェクトを作成済みであること。
  2. クイックスタートに沿って Developer Device Platform を設定します。
  3. ターミナルで gcloud を使用して認証されている。
  4. 一般的な情報については、デバイスランの概要を確認しました。
  5. Android 用のインストゥルメンテーション テストをビルドしているか、スタンドアロンの Android 実行可能ファイル（コンパイル済みの C++ バイナリ、ベンチマーク ランナー、シェル スクリプトなど）を準備している。

ステップ 1. テストまたは実行可能ファイルの実行を構成する

セッションを実行したら、構成オプションを確認します。

インストルメンテーション テストと実行可能ファイルのオプション

  • 複数のデバイス: 複数のデバイスで同じテストまたは実行可能ファイルを実行するには、--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）。

Android 実行可能ファイルのオプション

  • 実行可能引数: --executable-args=ARG,... をカンマ区切りのリストとして使用するか、フラグを繰り返して、コマンドライン引数を実行可能ファイルに渡します。各要素は 1 つの引数になるため、スペース区切りのコマンドラインをカンマ区切りの形式（--executable-args="--input=a.file,--threads=4" など）に書き換えます。カンマを含む引数を渡すには、値の先頭に ^SEP^ を付けて別の区切り文字（--executable-args="^;^--shape=1,224,224,3;--threads=4" など）を指定します。
  • 環境変数: --executable-env-vars=KEY=VALUE,...（例: --executable-env-vars=LD_LIBRARY_PATH=/data/local/tmp/lib）を使用して、デバイス上の実行可能プロセスの環境変数を設定します。
  • 実行可能ファイルのタイムアウト: 実行可能ファイルの実行時間を制限します。 --executable-timeout=10m（有効な範囲は 1m～3h で、デフォルトは 5m です。デバイスの準備とクリーンアップの時間は除きます）。

同期実行と非同期実行

デフォルトでは、送信コマンドはブロッキング（同期）です。テストまたは実行可能ファイルが完了するまで待機し、結果の概要表を出力します。

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

Android インストルメンテーション テスト

対象 :

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

Android 実行可能ファイル

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --async

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

gcloud beta device-run sessions wait SESSION_ID

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

複数のデバイス

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

Android インストルメンテーション テスト

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

Android 実行可能ファイル

gcloud beta device-run sessions submit android-executable \
  --device shiba-34,tokay-36 \
  --executable ./MY_EXECUTABLE

または

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --device tokay-36 \
  --executable ./MY_EXECUTABLE

テストと実行可能ファイルのタイムアウト

テストまたは実行可能ファイルの実行時間を制限します。

Android インストルメンテーション テスト

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

Android 実行可能ファイル

gcloud beta device-run sessions submit android-executable \
  --device shiba-35 \
  --executable ./MY_EXECUTABLE \
  --executable-timeout=10m

有効な範囲は Android 実行の場合は 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

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

ステップ 3. テストまたは実行可能ファイルを実行する

Android インストルメンテーション テスト APK またはスタンドアロンの Android 実行可能ファイルを送信できます。

インストルメンテーション テストの実行

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

  • デバイス: --device を使用してデバイスを指定します。--device shiba-35
  • テスト: --test を使用してテスト APK を指定します。--test /path/to/test.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

Android 実行可能ファイルを実行する

コンパイル済みの C++ バイナリ、LiteRT などのオンデバイス機械学習ベンチマーク ランナー、シェル スクリプトなどのスタンドアロン実行可能ファイルを、APK にパッケージ化せずに Android デバイスで直接実行するには、sessions submit android-executable コマンドを使用します。

Android 実行可能ファイルには、次のフラグが必要です。

  • デバイス: --device を使用してデバイスを指定します。--device shiba-35
  • 実行可能ファイル: --executable を使用して、実行可能ファイルへのローカルパスまたは Cloud Storage パスを指定します。--executable /path/to/my_executable

実行可能ファイルを実行するには、独自のデバイス ID と実行可能ファイルのパスを使用して、次のようなコマンドを実行します。

gcloud beta device-run sessions submit android-executable \
  --device shiba-34 \
  --executable /path/to/my_executable \
  --executable-args="--input=/data/local/tmp/file.name,--threads=4" \
  --other-files-to-push=/path/to/model.tflite=/data/local/tmp/model.tflite \
  --paths-to-pull=/data/local/tmp/output

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

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

継続的インテグレーションと継続的デリバリー（CI/CD）ワークフローに Developer Device Platform のインストルメンテーション テストを組み込む場合は、テストのシャーディングを検討する必要があります。テストのシャーディングによって、一連のインストルメンテーション テストをサブグループ（シャード）に分割し、それぞれ分離して実行できるようにします。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 - スマート シャーディングのシャードあたりの目標実行時間（2 分、10 分、1 時間など）を指定します。有効な範囲は 2 分～ 1 時間です。--sharding-option=smart の場合は必須。

  • --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - ファイル拡張子を除いた、スマート シャーディング レコード ファイルの名前を指定します。--sharding-option=smart の場合に必要です。この YAML ファイルは、smart-sharding/ ディレクトリの --bucket-name で指定された Google Cloudストレージ バケットにあります。ファイルが存在しない場合は自動的に作成されます。存在する場合は、セッションの完了時に内容が更新されます。

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

sessions submit instrumentation コマンドと sessions submit android-executable コマンドの非同期モードと同期モードの両方で、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

セッションはキャンセルされるようにマークされるだけなので、コマンドはすぐに返されます。キャンセルはバックエンドで非同期に行われます。

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

次のステップ

次は、ログを検索して分析します。