Developer Device Platform Device Run for iOS

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 iOS XCTest using the gcloud beta device-run CLI and find your results in the Google Cloud console. It assumes you have a Google Cloud account and project.

To use the device-run 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. Compiled your tests and packaged them into a ZIP.

Step 1. Choose device types

Using the device-run CLI, iOS tests can be executed across available physical 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        HARDWARE_TYPE  OS_VERSION  CAPACITY  AVAILABILITY  PRODUCTS
iphonese3-18-4    Apple  iPhone SE 3             iphonese3    PHYSICAL       18.4        NONE      NONE          Automation
iphonese3-26-3    Apple  iPhone SE 3             iphonese3    PHYSICAL       26.3        NONE      NONE          Automation

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. iphonese3-18-4) in the submit command.

Step 2. Prepare and package your XCTest

Before running your tests, you must compile them, ensure they are signed, verify the code signatures, and package the resulting artifacts into a ZIP file containing your .xctestrun configuration and the application test bundles.

1. Build your tests for physical iOS devices

Open your project in Xcode and build your app and test targets for testing:

1. Ensure that code signing is configured correctly in Xcode (specifying a valid provisioning profile and developer identity) for both the app target and the test runner target.

2. Build for testing using Xcode (Product > Build For > Testing) or with xcodebuild.

   For a workspace:

   xcodebuild build-for-testing \
     -workspace YourProject.xcworkspace \
     -scheme YourScheme \
     -derivedDataPath ./build \
     -destination "generic/platform=iOS"
   

   For a standalone project:

   xcodebuild build-for-testing \
     -project YourProject.xcodeproj \
     -scheme YourScheme \
     -derivedDataPath ./build \
     -destination "generic/platform=iOS"
   

This generates the build products under: ./build/Build/Products

Note: You don't need to register the Device Run device UDIDs in your Apple Developer account. Developer Device Platform re-signs your application and test bundles with a lab provisioning profile before installing them on the physical device, so a valid local development certificate and provisioning profile is all that is required to complete the build and packaging steps.

2. Verify build products and signatures

After building, verify that the application, runner, and .xctestrun manifest were generated under ./build/Build/Products/. If signed locally, you can verify bundle signatures using codesign:

1. Verify the app bundle:

   codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp.app
   

   Expected output: YourApp.app: valid on disk

2. If running an XCUITest, also verify the test runner bundle:

   codesign --verify --deep --verbose ./build/Build/Products/Debug-iphoneos/YourApp-Runner.app
   

   Expected output: YourApp-Runner.app: valid on disk

Note: A separate YourApp-Runner.app bundle is produced only for UI test (XCUITest) targets. Application-hosted unit tests are embedded in the host app instead, and are covered by the verification of YourApp.app.

3. Create the ZIP archive

Compress both the Debug-iphoneos directory and the .xctestrun file located in the build output products folder into a single ZIP archive.

Caution: The Debug-iphoneos/ directory and the .xctestrun file must reside directly at the root of the ZIP archive. Do NOT zip the outer Products/ or build/ folder.

Run the following command from the build products directory:

cd ./build/Build/Products
zip -r MyTests.zip Debug-iphoneos *.xctestrun

This creates the packaged MyTests.zip that is ready to be used with the --test flag.

Step 3. Run your XCTest

Note these flags are required:

• Device: Specify a device using --device: --device iphonese3-18-4
• Test: Specify the test zip file using --test: --test ./MyTests.zip

To run your XCTest, use the gcloud beta device-run sessions submit xctest command. You must provide the test zip file (MyTests.zip) compiled in the previous step.

To run a basic test session:

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

When execution begins, the CLI displays the created Session ID and the Cloud Storage destination where results will be stored:

Creating session [session-ee78b0ed] in location [global].
Result files will be stored at [https://console.cloud.google.com/storage/browser/BUCKET_NAME/automation/sessions/session-ee78b0ed/].

Waiting for session [session-ee78b0ed] to complete....

Step 4. Configure your test run

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

You can customize your test execution using the following optional flags (although at least one instance of the --device flag is required):

• Multiple devices: Specify the --device flag multiple times to run the same test on multiple devices concurrently: --device iphonese3-18-4 --device iphonese3-26-3 or --device iphonese3-18-4,iphonese3-26-3
• Additional apps: Install one or more additional .ipa packages before launching the test using --additional-apps: --additional-apps=/path/to/AdditionalApp.ipa
• Custom .xctestrun file: Pass a custom configuration file with --xctestrun-file: --xctestrun-file=/path/to/CustomTests.xctestrun
• Test timeout: Limit the execution duration: --xctest-timeout=10m (Valid range is 1m to 1h and defaults to 5m).
• Labels: Attach user-defined metadata to the session: --labels=env=staging,owner=my-team
• Push files to device: Push files to the app data container before test execution: --other-files-to-push=/tmp/data.txt=com.example.app:/Documents/data.txt
• Pull files from device: Pull files from the app data container after test execution: --paths-to-pull=com.example.app:/Documents/output.txt
• Flaky test retries: Set the maximum number of attempts to rerun flaky tests: --flaky-test-attempts=3 (Defaults to 1 attempt).
• Custom Cloud Storage bucket: Specify a custom Cloud Storage bucket for inputs and outputs: --bucket-name=my-custom-bucket (Defaults to PROJECT_ID-devicerun).
• Because uploading large ZIP or IPA files can be time-consuming, you can directly reference your files using their Cloud Storage gs:// paths to save upload time.

Step 5. Explore and manage your test run

You can track active runs and manage historic sessions using these commands:

• Describe session: Query the live progress or final results of a session: gcloud beta device-run sessions describe SESSION_ID Add --full to view complete details including device allocations, execution IDs, and Cloud Storage artifact paths.
• List sessions: View your recent runs: gcloud beta device-run sessions list --limit=10
• Cancel session: Stop a running test session: gcloud beta device-run sessions cancel SESSION_ID
• Cancel operation: Stop a pending or active operation: gcloud beta device-run operations cancel OPERATION_ID

What's next

Next up, find and analyze logs.