Developer Device Platform Device Run for Android

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. See gcloud beta device-run for a summary of commands.

Before you begin

These steps assume that you have already:

1. Created a Google Cloud project.
2. Set up Developer Device Platform following the Quickstart.
3. Authenticated with gcloud in the terminal.
4. Reviewed the Device Run overview for general information.
5. Built an instrumented test for Android.

Step 1. Choose devices

Using the device-run CLI, Android tests can be executed across available physical and virtual devices. To view the complete list of available devices visit either the interactive Device Catalog or run:

gcloud beta device-run devices list

Example output:

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

See the Device Catalog to learn how to filter this list. To target a specific device for your test execution, use its corresponding ID (ex. tegu-35) in the submit command.

Step 2. Run your Instrumentation test

Note these flags are required for Android tests:

• Device: Specify a device using --device: --device shiba-35
• Test: Specify the test APK using --test: --test /path/to/test.apk

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://BUCKET_NAME/automation/sessions/SESSION_ID/. See the test output for the link, resembling: https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/SESSION_ID/.

Step 3. Configure your test run

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

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

• Multiple devices: To run the same tests across multiple devices, provide the --device flag with multiple device IDs separated by commas, such as --device shiba-34,tokay-36, or with multiple --device flags, each specifying a distinct device ID (e.g. --device shiba-34 --device tokay-36).
• Additional apps: 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.
• Test timeout: Limit the execution duration: --instrumentation-timeout=10m (Valid range is 1m to 1h and defaults to 5m).
• Custom Cloud Storage bucket: If you don't specify a Cloud Storage bucket using the --bucket-name= flag, the Google Cloud CLI will use a default bucket named PROJECT_ID-devicerun.
• Flaky test retries: Set the maximum number of attempts to rerun flaky tests: --flaky-test-attempts=3 (Defaults to 1 attempt).

Step 4. 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.

Step 4.1. Choosing sharding option

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.

Note: The number of shards is configurable, so when Developer Device Platform runs many shards in parallel, test runs could be bottlenecked at the availability of devices. For this reason, we recommend the number of devices specified in the --device flag be less than or equal to the number of shards.

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,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,shiba-35,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-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.

Step 5. 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/BUCKET_NAME/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 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
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

The sessions list command supports all standard Google Cloud CLI flag options. For example:

gcloud beta device-run sessions list --limit 5

Which results in results resembling:

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

Or to find all running sessions, run:

gcloud beta device-run sessions list --filter RUNNING

Assuming you have running sessions, you will see results resembling:

SESSION_ID        START_TIME  STATE
session-d7ff8b81              RUNNING

Else, you will receive Listed 0 items.

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

gcloud beta device-run sessions cancel SESSION_ID

The command returns immediately, as the session is only marked to be cancelled. Cancellation happens asynchronously in the backend.

If the session is already finished, only the current status is printed. Requesting cancellation for a finished session is not an error.

What's next

Next up, find and analyze logs.