Developer Device Platform Device Run

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This guide describes how to run an Android instrumentation test using the gcloud beta device-run CLI and find your results in Google Cloud console. It assumes you have a Google Cloud account and project.

To use this Google Cloud CLI, you will need to provide your Google Cloud project ID.

Before you begin

These steps assume that you have already created a Google Cloud project, completed the setup steps in the Developer Device Platform Quickstart guide, and authenticated with gcloud in the terminal.

In addition, you will need to have an Android instrumentation test ready to run. See Build instrumented tests for guidance.

Further, you should have identified the device IDs you want to run your workloads on. See Device Catalog for instructions.

Tip: Append --help to any gcloud command to see detailed usage information.

Run a test

Now that you know the IDs of the devices available for testing your app, you can specify devices using the gcloud beta device-run sessions submit instrumentation command and the --device flag to run instrumentation tests.

Tip: To view all available flags, execute gcloud beta device-run sessions submit instrumentation --help.

To run your test, issue a command resembling the following but with your own device IDs and test path:

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

The job's result report folder can be found at a Cloud Storage path such as gs://<your_project_id>/automation/sessions/session-id/. See the test output for the link, resembling: https://console.cloud.google.com/storage/browser/your_project_id/automation/sessions/session-id/.

Configure the test run

Now that you've run a test, explore some configuration options:

• To run the same tests across multiple devices, provide the --device flag multiple times, such as --device shiba-34 --device tokay-36.
• You can optionally specify one or more APKs to install prior to running your tests using the --apps=path1,path2,...,path_n flag. The order you specify is the order in which these apps are installed.
• You must specify your test APK with the --test flag.
• When you specify a local path with the --apps or --test flags, the Google Cloud CLI CLI automatically copies it to your Cloud Storage bucket under gs://my-project-id/automation/inputs/date_time_four_chars_suffix/ each time you execute the command.
• Because uploading large APKs can be time-consuming, you can directly reference your APKs using their Cloud Storage gs:// paths to save upload time.

Tip: To view all available options for the submit instrumentation command, run gcloud beta device-run sessions submit instrumentation --help.

The sessions submit instrumentation command blocks on session results by default, meaning it will wait for the test run to finish and output results resembling:

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

To run the command asynchronously, include the --async flag. This allows the command to exit immediately after uploading files to Cloud Storage and printing the Operation ID and Session ID. You can use the operations wait command and Operation ID to wait for the execution. It will block until the job is completed:

gcloud beta device-run operations wait your_operation_id

Use sharding

To include Developer Device Platform in a Continuous Integration and Continuous Delivery (CI/CD) workflow, you should consider sharding your tests. Test sharding divides a set of tests into sub-groups (shards) that run separately in isolation. Developer Device Platform automatically runs each shard in parallel using multiple devices, and completes the entire set of tests in less time.

Caution: Sharding tests may cost more. Although test sharding reduces the time it takes for all your tests to run, the overhead of starting your app on each shard may increase individual device times.

Sharding options

If your jobs have only a small numbers of test cases, or the total execution time of all test cases is not long, it is not necessary to use sharding. If you have a large number of test cases, or the total execution time of all their test cases is long, consider using sharding.

Developer Device Platform supports both smart and uniform sharding. When deciding how to shard your tests, consider the following options:

• If all test cases will take a similar amount of time, use uniform sharding by dividing all test cases into n shards.

• When the execution time of different test cases varies greatly, use smart sharding. Developer Device Platform uses historical test execution time to create different shards and attempts to complete all shards in a similar duration.

Uniform sharding

To shard your tests with uniform sharding, include the --sharding-option=uniform and --uniform-sharding-count= flags in the sessions submit instrumentation command like so:

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

You should see output indicating Job status: 2 running. The service creates two jobs, one for each device. Because the inputs to both jobs are identical, the service centralizes validation, performing them only once.

Your will see the two jobs listed separately in the final output of the command when complete:

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

Smart sharding

To shard your tests with smart sharding, include the --sharding-option=smart, --smart-sharding-max-shard-count=, --smart-sharding-target-duration= (in minutes or 1h), and --smart-sharding-record-name= flags in the sessions submit instrumentation command like so:

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

You should see final output indicating three jobs ran:

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

Here is a summary of the smart sharding flags used here:

• --smart-sharding-max-shard-count=SMART_SHARDING_MAX_SHARD_COUNT - Specify the maximum number of shards to create for smart sharding. If unset or set to 0, system-defined max limits are used. The valid range is 0 to 20 for physical devices and 0 to 200 for virtual devices.--smart-sharding-max-shard-count: Specifies the maximum number of shards to create. The number of devices specified in the --device flag must be less than or equal to this value.

• --smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION - Specify the targeted execution time (e.g., 2m, 10m, 1h) per shard for smart sharding. The valid range is 2m to 1h. Required when --sharding-option=smart.

• --smart-sharding-record-name=SMART_SHARDING_RECORD_NAME - Specify the name of the smart sharding record file, excluding the file extension. Required when --sharding-option=smart. This YAML file is located in the Google Cloud Storage bucket specified by --bucket-name under the smart-sharding/ directory. If the file does not exist, it will be created automatically; otherwise, its contents will be updated upon session completion.

Explore and manage your test run

For both async and sync mode of the sessions submit instrumentation command, you can use the sessions describe command to query the job status during the execution, or get the result after it is completed:

gcloud beta device-run sessions describe <session_id>

The output summarizes test results and links to the results in Google Cloud console. For example:

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

Use the following command to list out all your running and completed sessions:

gcloud beta device-run sessions list

Receive output containing the list of sessions in your project, resembling:

SESSION_ID                                    START_TIME                STATE
session-4825e153                              2026-07-28T16:38:43.155Z  DONE
session-813ca602                              2026-07-28T22:40:32.415Z  DONE

To cancel a running session, run this command with your session ID:

gcloud beta device-run sessions cancel your_session_id

What's next

Next up, find and analyze logs.