gcloud alpha device-run sessions submit instrumentation

NAME
gcloud alpha device-run sessions submit instrumentation - submit a Device Run session with an instrumentation job
SYNOPSIS
gcloud alpha device-run sessions submit instrumentation --device=[DEVICE,…] --test=TEST_PATH [--additional-test-options=[KEY=VALUE,…]] [--apps=[APP_PATH,…]] [--async] [--bucket-name=BUCKET_NAME] [--flaky-test-attempts=FLAKY_TEST_ATTEMPTS] [--instrumentation-timeout=INSTRUMENTATION_TIMEOUT] [--labels=[KEY=VALUE,…]] [--locale=LOCALE] [--location=LOCATION] [--orchestrator-version=ORCHESTRATOR_VERSION] [--orientation=ORIENTATION] [--other-files-to-push=[SOURCE=DEST,…]] [--paths-to-pull=[DEVICE_PATH,…]] [--sharding-option=SHARDING_OPTION] [--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME] [--smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION] [--test-runner-class=TEST_RUNNER_CLASS] [--test-targets=[KEY=VALUE,…]] [--uniform-shard-count=UNIFORM_SHARD_COUNT] [--video=VIDEO] [GCLOUD_WIDE_FLAG …]
DESCRIPTION
(ALPHA) Submit a Device Run session with an instrumentation job.
EXAMPLES
To submit an instrumentation session in location us-central1 on a device with ID my-device-id, run: 
gcloud alpha device-run sessions submit instrumentation --location=us-central1 --device=my-device-id --apps=gs://my-bucket/app.apk --test=gs://my-bucket/test.apk --bucket-name=my-bucket

To submit an instrumentation session asynchronously without waiting for it to complete, run: 

gcloud alpha device-run sessions submit instrumentation --location=us-central1 --device=my-device-id --apps=gs://my-bucket/app.apk --test=gs://my-bucket/test.apk --bucket-name=my-bucket --async
REQUIRED FLAGS
--device=[DEVICE,…]
Id of the device type to run the test on. Can be repeated to specify multiple device types. A job will be created for each specified device type.
--test=TEST_PATH
The path to the APK file containing instrumentation tests. Supports both Google Cloud Storage (gs://…) paths and local filesystem paths. Any local file will be uploaded to Google Cloud Storage prior to test execution.
OPTIONAL FLAGS
--additional-test-options=[KEY=VALUE,…]
A dictionary of additional options to pass to the instrumentation test. Formats supported in test_targets are not allowed to be used here.
--apps=[APP_PATH,…]
A list of application binary files (.apk, .aab, or .apks) to install before running the test. The order of the applications in the list determines their installation order on the device. Supports both Google Cloud Storage (gs://…) paths and local filesystem paths. Any local file will be uploaded to Google Cloud Storage prior to test execution.
--async
Return immediately, without waiting for the operation in progress to complete.
--bucket-name=BUCKET_NAME
The name of a Google Cloud Storage bucket to store test artifacts, including local input files, test output files, and smart sharding timing records. If not specified, a default bucket named gs://[PROJECT_ID]-devicerun will be used or created.

The Google Cloud Storage bucket layout will be structured as follows:

  • gs://{bucket-name}/automation/
    • inputs/
      • 2026-05-29_10:13.026220_JZTM/
        • app-debug.apk
        • app-debug-androidTest.apk
    • sessions/
      • my-session-id1/
        • job-000/
          • execution-000/
            • junit.xml
            • …
          • execution-001/
            • junit.xml
            • …
          • merged_junit.xml
      • my-session-id2/
        • …
    • smart-sharding/
      • sharding-record-A.yaml
      • sharding-record-B.yaml
--flaky-test-attempts=FLAKY_TEST_ATTEMPTS
Specifies the maximum number of execution attempts per test shard to handle flakiness or infrastructure errors. If not specified, defaults to 1.
--instrumentation-timeout=INSTRUMENTATION_TIMEOUT
Specifies the maximum duration allowed for the instrumentation test run (e.g., 10m, 20s, 1h). The valid range is 1m to 1h. If not specified, defaults to 5m.
--labels=[KEY=VALUE,…]
A dictionary of user-defined key-value labels to attach to the session.
--locale=LOCALE
Specifies the locale (language and region) to switch the device to before running the test. The format is language-region, e.g., en-US or zh-CN. The typical language value is a two- or three-letter language code as defined in ISO 639. The typical region value is a two-letter ISO 3166 code or a three-digit UN M.49 area code.
Location resource - Location to submit session. This represents a Cloud resource. (NOTE) Some attributes are not given arguments in this group but can be set in other ways.

To set the project attribute:

  • provide the argument --location on the command line with a fully specified name;
    • The default is global with a fully specified name;
      • provide the argument --project on the command line;
        • set the property core/project.
--location=LOCATION
ID of the location or fully qualified identifier for the location.

To set the location attribute:

  • provide the argument --location on the command line;
    • The default is global.
--orchestrator-version=ORCHESTRATOR_VERSION
Specifies the version of the Android Test Orchestrator to use during test execution. If not specified, no orchestrator is used. If set to auto, the system-default orchestrator version is used.
--orientation=ORIENTATION
Specifies the orientation to set the device to before running the test. Accepted values are portrait or landscape. ORIENTATION must be one of: portrait, landscape.
--other-files-to-push=[SOURCE=DEST,…]
A dictionary of additional files to be pushed to the device before running the test. The key is the source path of the file (supports both Google Cloud Storage and local paths; local files will be uploaded to Google Cloud Storage prior to test execution), and the value is the destination path on the device.
--paths-to-pull=[DEVICE_PATH,…]
A list of file or directory paths to pull from the device following test completion.
--sharding-option=SHARDING_OPTION
Specifies the sharding strategy to partition the test execution across multiple device allocations. Accepted values are uniform or smart. SHARDING_OPTION must be one of: uniform, smart.
--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME
Specifies the name of the smart sharding record file, excluding the file extension. Required when --sharding-option=smart. This file is located in the Google Cloud Storage bucket specified by --bucket-name under the smart-sharding/ directory with a .yaml extension. If the file does not exist, it will be created automatically; otherwise, its contents will be updated upon session completion.
--smart-sharding-target-duration=SMART_SHARDING_TARGET_DURATION
Specifies 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.
--test-runner-class=TEST_RUNNER_CLASS
The instrumentation test runner class to use. If not specified, a default runner class will be determined by examining the application's manifest.
--test-targets=[KEY=VALUE,…]
A list of test targets or target filters to run. Each target must be fully qualified with the package name or class name, in one of these formats:
  • package package_name
    • notPackage com.package.to.skip
      • class package_name.class_name
        • class package_name.class_name#method_name
        • notClass com.foo.ClassToSkip
        • notClass com.foo.ClassName#testMethodToSkip
        • annotation com.foo.AnnotationToRun
        • notAnnotation com.foo.AnnotationToSkip
        • size [small|medium|large]

        Formats like testfile or notTestfile won't be supported. If empty, all targets in the module will be run.

--uniform-shard-count=UNIFORM_SHARD_COUNT
Specifies the total number of shards to create for uniform sharding. Required when --sharding-option=uniform.
--video=VIDEO
Specifies when to record video of the device screen during the test run. Accepted values are always or on-failure. VIDEO must be one of: always, on-failure.
GCLOUD WIDE FLAGS
These flags are available to all commands: --access-token-file, --account, --billing-project, --configuration, --flags-file, --flatten, --format, --help, --impersonate-service-account, --log-http, --project, --quiet, --trace-token, --user-output-enabled, --verbosity.

Run $ gcloud help for details.

NOTES
This command is currently in alpha and might change without notice. If this command fails with API permission errors despite specifying the correct project, you might be trying to access an API with an invitation-only early access allowlist.