Developer Device Platform Device Run Overview

Welcome to Developer Device Platform Device Run, which allows you to run tests on physical and virtual Android devices and physical iOS devices in the cloud. This page describes commonalities between running Android and iOS tests. See Device Run for Android and Device Run for iOS for platform-specific steps.

To use this Google Cloud CLI, you will need to provide your Google Cloud project ID. For a summary of commands, see: gcloud beta device-run

Note these flags are required:

  • Device: Specify a device using --device: --device shiba-35 or --device iphonese3-18-4
  • Test: Specify the test APK or IPA using --test: --test /path/to/test.apk or --test /path/to/test.ipa

The following configuration options are common to both Android and iOS tests.

Input and output Cloud Storage paths

  • Custom Cloud Storage bucket: You can specify a custom Cloud Storage bucket for inputs and outputs: --bucket-name=my-custom-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.
  • Input files: When you specify a local path with the --test, --additional-apps, or --xctestrun-file flags, the Google Cloud CLI automatically copies it to your Cloud Storage bucket under gs://BUCKET_NAME/automation/inputs/DATE_TIME_FOUR_CHARS_SUFFIX/ each time you execute the command., where BUCKET_NAME defaults to PROJECT_ID-devicerun.
  • Cloud paths: Because uploading large files can be time-consuming, you can directly reference them using their Cloud Storage gs:// paths to save upload time.
  • Result files: Output artifacts are uploaded to your Cloud Storage bucket under gs://BUCKET_NAME/automation/sessions/session-[SESSION_ID]/.

Synchronous and asynchronous runs

By default, the submit command is blocking (synchronous). It will wait for the test to complete and print a summary table of the results.

To submit the session and return immediately after uploading files to Cloud Storage, add the --async flag:

Android

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --async

iOS

gcloud beta device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --async

This returns a session ID immediately. You can then wait for it using the sessions wait command:

gcloud beta device-run sessions wait SESSION_ID

The command will block until the job is completed.

Multiple devices

To run the same tests across multiple devices, provide the --device flag with multiple device IDs separated by commas or with multiple --device flags, each specifying a distinct device ID.

Android

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34,tokay-36 \
  --test ./ANDROID_TESTS.apk

Or:

gcloud beta device-run sessions submit instrumentation \
  --device shiba-34 \
  --device tokay-36 \
  --test ./ANDROID_TESTS.apk

iOS

gcloud beta device-run sessions submit xctest \
  --device iphonese3-18-4,iphonese3-26-3 \
  --test ./IOS_TESTS.zip

Or:

gcloud beta device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --device iphonese3-26-3 \
  --test ./IOS_TESTS.zip

Test timeout

Limit the execution duration of your test:

Android

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --instrumentation-timeout=10m

iOS

gcloud beta device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xctest-timeout=10m

The valid range is 1m to 1h and defaults to 5m.

Software versions

Discover and use available software packages and versions of AndroidX Test Orchestrator and Apple Xcode, and inspect their lifecycles, supported versions, and metadata before configuring test runs.

First, list all available software packages and their versions:

gcloud beta device-run software-versions list

Receiving output resembling:

ID                                NAME                              SOFTWARE_TYPE               VERSION  STATE   IS_DEFAULT
androidx-test-orchestrator-1-4-1  AndroidX Test Orchestrator 1.4.1  ANDROIDX_TEST_ORCHESTRATOR  1.4.1    ACTIVE  True
androidx-test-orchestrator-1-6-1  AndroidX Test Orchestrator 1.6.1  ANDROIDX_TEST_ORCHESTRATOR  1.6.1    ACTIVE
xcode-16-4                        Xcode 16.4                        XCODE                       16.4     ACTIVE
xcode-26-2                        Xcode 26.2                        XCODE                       26.2     ACTIVE  True

Then describe a specific package using its exact resource ID from the list:

Android

gcloud beta device-run software-versions describe androidx-test-orchestrator-1-4-1

iOS

gcloud beta device-run software-versions describe xcode-16-4

Receiving output resembling:

Android

id: androidx-test-orchestrator-1-4-1
isDefault: true
lifecycle:
  state: ACTIVE
name: AndroidX Test Orchestrator 1.4.1
softwareType: ANDROIDX_TEST_ORCHESTRATOR
version: 1.4.1

iOS

id: xcode-16-4
lifecycle:
  state: ACTIVE
name: Xcode 16.4
softwareType: XCODE
supportedIosVersions:

-   '15.0'
-   '15.1'
-   '15.2'
-   '15.4'
-   '15.7'
-   '16.0'
-   '16.1'
-   '16.2'
-   '16.3'
-   '16.5'
-   '16.6'
-   '18.0'
-   '18.3'
-   '18.4'
version: '16.4'

Now that you know which software versions are available, you can use them in your test runs with either the --orchestrator-version or --xcode-version flags, like so:

Android

gcloud beta device-run sessions submit instrumentation \
  --device shiba-35 \
  --test ./ANDROID_TESTS.apk \
  --orchestrator-version=1.4.1

See Enable Orchestrator for more information.

iOS

gcloud beta device-run sessions submit xctest \
  --device iphonese3-18-4 \
  --test ./IOS_TESTS.zip \
  --xcode-version=16.4

See Device Run for iOS for more information.

Input validation

Developer Device Platform attempts to validate your inputs, including artifacts, and returns an ERROR rather than PASSED or FAILED when encountering erroneous input:

Session [session-94b57778] finished with result [ERROR].
JOB NAME  EXECUTION NAME  EXECUTION RESULT
job-000   execution-000   ERROR

Now append --full to the sessions describe command to see more details about the session:

gcloud beta device-run sessions describe --full session-94b57778

Which results in output resembling:

name: projects/user-test1/locations/global/sessions/session-94b57778
sessionConfig:
  displayName: instrumentation-session
  jobConfigs:
  -   action:
      androidInstrumentationTest:
        testInstallable:
          files:
          -   gcsInputFile:
              path: gs://user-test1-devicerun/automation/inputs/2026-09-16_18:55.17372947_EECF/my-test.apk
    allocationConfig:
      deviceConfigs:
      -   actions:
        -   androidLogcat: {}
        requirement:
          deviceId: mediumphone-arm-34
    displayName: job-000
  outputDirectoryConfig:
    gcsOutputDirectory:
      path: gs://user-test1-devicerun/automation/sessions
sessionReport:
  endTime: '2026-09-16T18:55:49.721Z'
  id: ed681f23-669b-4464-8a93-b28456e58136
  jobReports:
  -   displayName: job-000
    endTime: '2026-09-16T18:55:45.839Z'
    executionReports:
    -   displayName: execution-000
      endTime: '2026-09-16T18:55:46.694Z'
      id: ce370173-af94-4dd7-acc6-0863e4d2e9ec
      result:
        cause:
          summary:
            message: The instrumentation target package does not match any of the
              installable packages.
            reason: INSTRUMENTATION_TARGET_MISMATCH
            type: CUSTOMER
        resultType: ERROR
      startTime: '1970-01-01T00:00:00Z'
      status:
        statusType: PENDING
    id: 953b5106-3c20-40f0-aceb-18af89cd1b83
    result:
      cause:
        summary:
          message: The instrumentation target package does not match any of the installable
            packages.
          reason: INSTRUMENTATION_TARGET_MISMATCH
          type: CUSTOMER
      resultType: ERROR
    startTime: '2026-09-16T18:55:31.651Z'
    status:
      statusType: DONE
  result:
    resultType: ERROR
  startTime: '2026-09-16T18:55:24.442Z'
  status:
    statusType: DONE

What's next

Run an Android test or Run an iOS test with Developer Device Platform.