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 --location=LOCATION --test=TEST [--additional-test-options=[KEY=VALUE,…]] [--apps=[SOURCE_PATH,…]] [--bucket-name=BUCKET_NAME] [--instrumentation-timeout=INSTRUMENTATION_TIMEOUT] [--labels=[KEY=VALUE,…]] [--max-attempts=MAX_ATTEMPTS] [--orchestrator-version=ORCHESTRATOR_VERSION] [--other-files-to-push=[SOURCE=DEST,…]] [--paths-to-pull=[DEVICE_PATH,…]] [--sharding-option=SHARDING_OPTION] [--smart-sharding-record-name=SMART_SHARDING_RECORD_NAME] [--target-smart-shard-time=TARGET_SMART_SHARD_TIME] [--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
REQUIRED FLAGS
--device=DEVICE
Id of the device to run the test on.
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;
  • provide the argument --project on the command line;
  • set the property core/project.

This must be specified.

--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.
--test=TEST
The path to the binary 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=[SOURCE_PATH,…]
A list of application binary files 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.
--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 <project>-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
--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.
--max-attempts=MAX_ATTEMPTS
Specifies the maximum number of execution attempts per test shard to handle flakiness or infrastructure errors. If not specified, defaults to 1.
--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.
--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.
--target-smart-shard-time=TARGET_SMART_SHARD_TIME
Specifies the targeted execution time (in seconds) per shard for smart sharding. 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.