このガイドでは、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. デバイスを選択する
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）を送信コマンドで指定します。
ステップ 2. インストルメンテーション テストを実行する
Android テストでは以下のフラグが必要です。
- デバイス:
--deviceを使用してデバイスを指定します。--device shiba-35 - テスト:
--testを使用してテスト APK を指定します。--test /path/to/test.apk
テストを実行するには、次の例に似たコマンドを発行します。ただし、デバイス ID とテストパスはご自身のものを使用してください。
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/ など）を確認します。
ステップ 3. テスト実行を構成する
テストを実行したら、構成オプションを確認します。
- 複数のデバイス: 複数のデバイスで同じテストを実行するには、
--deviceフラグに、カンマで区切られた複数のデバイス ID（--device shiba-34,tokay-36など）を指定するか、それぞれ異なるデバイス ID（--device shiba-34 --device tokay-36など）を指定する複数の--deviceフラグを指定します。 - 追加のアプリ:
--apps=path1,path2,...,path_nフラグを使用して、テストの実行前にインストールする APK を 1 つ以上指定することもできます。指定した順序でアプリがインストールされます。 - テストのタイムアウト: 実行時間を制限します。
--instrumentation-timeout=10m（有効な範囲は1m～1hで、デフォルトは5mです）。 - カスタム Cloud Storage バケット:
--bucket-name=フラグを使用して Cloud Storage バケットを指定しない場合、Google Cloud CLI はPROJECT_ID-devicerunという名前のデフォルト バケットを使用します。 - フレーキー テストの再試行: フレーキー テストを再実行する最大試行回数を設定します。
--flaky-test-attempts=3（デフォルトは 1 回）。
Orchestrator を有効にする
Developer Device Platform は Android Test Orchestrator をサポートしています。これにより、アプリのテストをそれぞれの Instrumentation 呼び出し内で行えます。
Orchestrator を使用すると、次のことができます。
共有状態を回避します。各テストは、独自の
Instrumentationインスタンスで実行されます。そのため、テストでアプリの状態を共有している場合、その共有状態のほとんどは各テストの後にデバイスの CPU またはメモリから削除されます。各テストの終了後にデバイスの CPU とメモリからすべての共有状態を削除するには、次のようにclearPackageData設定を含めます。--additional-test-options clearPackageData=trueクラッシュを分離する。1 つのテストがクラッシュしても、その
Instrumentationインスタンスのみが削除されます。つまり、他のテストは引き続き実行され、完全なテスト結果が提供されます。
デベロッパー デバイス プラットフォームでは、Android Test Orchestrator はデフォルトでオフになっています。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 に設定します。
ステップ 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 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
セッションはキャンセルされるようにマークされるだけなので、コマンドはすぐに返されます。キャンセルはバックエンドで非同期に行われます。
セッションがすでに終了している場合は、現在のステータスのみが出力されます。終了したセッションのキャンセルをリクエストしてもエラーにはなりません。
次のステップ
次は、ログを検索して分析します。