Text of docs.cloud.google.com › developer-device-platform › device-run as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Developer Device Platform Device Run Overview | Google Cloud Documentation

Skip to main content Console English Deutsch Español – América Latina Français Indonesia Italiano Português – Brasil עברית 中文 – 简体 中文 – 繁體 日本語 한국어 Sign in Developer Device Platform Start free Home Documentation Application development Developer Device Platform Guides Developer Device Platform Device Run Overview Stay organized with collections Save and categorize content based on your preferences.

Welcome to Developer Device Platform Device Run, which lets you run tests and executables on physical and virtual Android devices and physical iOS devices in the cloud. This page summarizes capabilities and describes commonalities between running Android instrumentation tests , Android executables , and iOS XCTest tests. If you are migrating from Firebase Test Lab to Developer Device Platform, see our migration guide , command and flag translation , and migration skill for AI agents.

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 To instead use the API directly, see the Device Run REST API reference documentation. Key capabilities Developer Device Platform Device Run is a Google Cloud service that lets you execute automated test suites across physical and virtual mobile devices. Built for modern Continuous Integration and Continuous Delivery (CI/CD) workflows, Device Run offers command-line control through the Google Cloud CLI ( gcloud beta device-run ), allowing teams to run, manage, and scale test suites on dedicated hardware and virtual environments.

1. Cross-platform automated testing Android and iOS support : Device Run supports built-in test frameworks, including Android Instrumentation tests ( .apk ), Android executables (compiled binaries), and iOS XCTests ( .ipa or .zip ). Flexible device targeting : Target specific physical or virtual devices listed in the Device Catalog using OS and model identifiers (e.g., Pixel or iPhone models) via the --device flag. Multi-device parallel execution : Execute identical test suites concurrently across multiple devices by specifying comma-separated device IDs or supplying multiple --device flags.

2. Flexible execution modes and controls Synchronous and asynchronous submissions : Test runs operate synchronously by default, displaying a summary upon completion. Adding the --async flag returns a session ID immediately for non-blocking execution, which can be monitored later using gcloud beta device-run sessions wait . Custom execution timeouts *: Configure execution duration limits with --instrumentation-timeout or --xctest-timeout .

Flaky test retries : Set maximum retry attempts for flaky test executions using the --flaky-test-attempts flag. 3. Software version and dependency management Configurable test environments *: Discover, inspect, and select specific software environment versions — such as AndroidX Test Orchestrator and Apple Xcode — prior to initiating test runs. Version discovery : Use gcloud beta device-run software-versions list and describe commands to view active software packages, supported OS versions, and default runtime specifications.

4. Storage and artifact management Cloud Storage integration : Test inputs (APKs, IPAs, supporting apps) and output artifacts (logs, test reports) are stored in Cloud Storage. Bucket flexibility : Automatically defaults to a project bucket named PROJECT_ID-devicerun or routes to a custom bucket specified via the --bucket-name flag. You are in complete control of this bucket and will need to manually remove its contents when no longer needed or otherwise configure automated lifecycle management on the bucket.

See About object deletion for instructions. Direct cloud paths : Reference existing gs:// paths directly for large files to eliminate upload overhead. 5. Advanced Android testing features Android Test Orchestrator : Isolate test execution by running each test in its own Instrumentation instance to prevent shared app state and isolate application crashes. Test Sharding : Uniform Sharding : Evenly splits test cases across a specified number of shards ( --sharding-option=uniform ).

Smart Sharding : Uses historical test execution data to balance test cases dynamically across shards, targeting a specific total execution duration ( --sharding-option=smart ). 6. Session management and diagnostics Full session control : List, describe, filter, or cancel active or historic test runs using sessions list , sessions describe , and sessions cancel . Early input validation : Performs automatic validation on submitted test binaries and configuration artifacts, surfacing explicit error details and root causes (such as target package mismatches) when errors occur.

Core settings Required flags Note these flags are required: Device : Specify a device using --device : --device shiba-35 or --device iphonese3-18-4 Test or executable : Specify the test package using --test ( --test /path/to/test.apk or --test /path/to/MyTests.zip ) for test runs, or specify the executable binary or script using --executable ( --executable /path/to/my_executable ) for Android executable runs. The following configuration options are common across Device Run sessions.

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 , --executable , --apps , --additional-apps , --other-files-to-push , 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]/ . 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: INSTRUMENTA

The rest of this page is on the live site.