Developer Device Platform Device Run

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

この Google Cloud CLI を使用するには、 Google Cloud プロジェクト ID を指定する必要があります。

始める前に

以下の手順では、 Google Cloud プロジェクトを作成済みで、デベロッパー デバイス プラットフォーム クイックスタート ガイドの設定手順を完了し、ターミナルで gcloud を使用して認証していることを前提としています。

また、実行する Android インストルメンテーション テストを用意しておく必要があります。 ガイダンスについては、インストルメンテーション テストを作成するをご覧ください。

さらに、ワークロードを実行するデバイス ID を特定しておく必要があります。手順については、デバイス カタログをご覧ください。

テストを実行する

アプリのテストに使用できるデバイスの ID がわかったら、 gcloud beta device-run sessions submit instrumentation コマンドと --device フラグを使用してデバイスを指定し、インストルメンテーション テストを実行できます。

テストを実行するには、次のようなコマンドを発行します。ただし、デバイス ID とテストパスはご自身のものに置き換えてください。

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

ジョブの結果レポート フォルダは、 gs://<your_project_id>/automation/sessions/session-id/ などの Cloud Storage パスにあります。リンクについては、テスト出力（https://console.cloud.google.com/storage/browser/your_project_id/automation/sessions/session-id/ など）をご覧ください。

テスト実行を構成する

テストを実行したら、次の構成オプションを確認します。

  • 複数のデバイスで同じテストを実行するには、--device フラグ を複数回指定します（--device shiba-34 --device tokay-36 など）。
  • 必要に応じて、--apps=path1,path2,...,path_n フラグを使用して、テストの実行前にインストールする APK を 1 つ以上指定できます。指定した順序でアプリがインストールされます。
  • --test フラグを使用してテスト APK を指定する必要があります。
  • --apps フラグまたは --test フラグでローカルパスを指定すると、コマンドを実行するたびに、Google Cloud CLI CLI によって gs://my-project-id/automation/inputs/date_time_four_chars_suffix/ の Cloud Storage バケットに自動的にコピーされます。
  • サイズの大きい APK のアップロードには時間がかかるため、Cloud Storage の gs:// パスを使用して APK を直接参照すると、アップロード時間を短縮できます。

sessions submit instrumentation コマンドは、デフォルトでセッション結果をブロックします。つまり、テスト実行が完了するまで待機し、次のような結果を出力します。

Using the default Cloud Storage bucket [gs://<my-project-id>] for input and result files. Will create the bucket if it does not exist.
Uploading [app.apk].
Uploading [test.apk].

Initiated long-running operation [operation-number] to create session.
Creating session [session-id] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/<my-project-id>/automation/sessions/session-id/].
Waiting for session [session-id] to complete....done.

Session [session-id] finished with result [FAILED].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   all             FAILED: 2 test cases failed, 5 passed

コマンドを非同期で実行するには、--async フラグを含めます。これにより、ファイルを Cloud Storage にアップロードしてオペレーション ID とセッション ID を出力した後、コマンドをすぐに終了できます。オペレーションの完了を待つには、operations wait コマンドとオペレーション ID を使用します。ジョブが完了するまでブロックされます。

gcloud beta device-run operations wait your_operation_id

シャーディングを使用する

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

シャーディング オプション

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

デベロッパー デバイス プラットフォームは、スマート シャーディングと均一シャーディングの両方をサポートしています。テストをシャーディングする方法を決定する際は、次のオプションを検討してください。

  • すべてのテストケースに同じくらいの時間がかかる場合は、すべてのテストケースを n 個のシャードに分割して、均一シャーディングを使用します。

  • テストケースによって実行時間が大きく異なる場合は、スマート シャーディングを使用します。デベロッパー デバイス プラットフォームは、過去のテスト実行時間を使用してさまざまなシャードを作成し、すべてのシャードを同様の時間で完了しようとします。

均一シャーディング

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

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

Job status: 2 running を示す出力が表示されます。サービスは、デバイスごとに 1 つのジョブを作成します。両方のジョブへの入力は同じであるため、サービスは検証を一元化し、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 \
    --device shiba-35 \
    --device 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-max-shard-count: 作成するシャードの最大数を指定します。--device フラグで指定するデバイスの数は、この値以下にする必要があります。

  • --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 ファイルは、 Google Cloud ディレクトリの下の smart-sharding/ --bucket-name で指定された Storage バケットにあります。ファイルが存在しない場合は自動的に作成されます。それ以外の場合は、セッションの完了時に内容が更新されます。

テスト実行を探索して管理する

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/your_project_id-devicerun/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

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

gcloud beta device-run sessions cancel your_session_id

次のステップ

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