XCUITest Intro

TestingBot provides a grid of physical iOS devices in the cloud, ready to run your XCUITests.
XCUITest (a framework within the larger XCTest Testing framework) is Apple's automation framework, which comes with Apple's XCode IDE, capable of running automated UI tests on iPhone and iPad devices.

Setup

XCUITest is packaged in a zip file. You will need two files to perform XCUITesting on our cloud:

An .ipa file of the actual mobile application that you want to test.
Another .zip file of the XCUITests.

If you just want to give this a try, we have a TestingBot XCUITest Demo App which you can use with the following steps.

TestingBot CLI

The easiest way to run XCUITests on TestingBot is using our CLI tool. It handles uploading your app, test ZIP, and running tests in a single command.

Installation

npm install -g @testingbot/cli

Authentication

Authenticate using this command:

testingbot login

This opens your browser for authentication. After logging in, your credentials are saved to ~/.testingbot and you can start using the CLI.

Other Authentication Methods

Command-line options: --api-key and --api-secret
Environment variables: TB_KEY and TB_SECRET
Config file: Create ~/.testingbot with content key:secret

Quick Start

Run XCUITests with a single command:

testingbot xcuitest app.ipa app-test.zip --device "iPhone 16" --real-device

The CLI will:

Upload your app IPA to TestingBot
Upload your test ZIP
Start the test run
Show real-time progress and results

Upload iOS App

You can upload your .ipa file to TestingBot storage with our REST-API.

When using the CLI, the app upload is handled automatically as part of the testingbot xcuitest command. Simply specify your app IPA file as the first argument:

testingbot xcuitest /path/to/app/sample-debug.ipa /path/to/test/app-test.zip --device "iPhone 16" --real-device

Alternatively, you can use the --app option:

testingbot xcuitest --app /path/to/app/sample-debug.ipa --test-app /path/to/test/app-test.zip --device "iPhone 16" --real-device

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/xcuitest/app" \
-F "file=@/path/to/app/file/sample-debug.ipa"

The API response will include an id response, which you can use in the other API calls.

{
    "id": 4012
}

Upload XCUITest Suite

If you do not have a .zip file yet, please see our Build Testsuite documentation.

When using the CLI, the test ZIP upload is handled automatically. Specify your test ZIP as the second argument:

testingbot xcuitest app.ipa app-test.zip --device "iPhone 16" --real-device

Or use the --test-app option:

testingbot xcuitest --app app.ipa --test-app app-test.zip --device "iPhone 16" --real-device

To upload the XCUITest suite, in .zip file, please use our REST-API.

curl -u api_key:api_secret \
-X POST "https://api.testingbot.com/v1/app-automate/xcuitest/:id/tests" \
-F "file=@/path/to/app/file/application-debug-test.zip"

Replace the :id with the identifier you received during the app upload call. (In this example 4012)

Run XCUI tests

Once you've uploaded both your app and test suite, you can start a XCUITest on the TestingBot cloud.

Use the CLI to run tests with device selection options:

# Basic usage with device selection
testingbot xcuitest app.ipa app-test.zip --device "iPhone 16" --real-device

# With test name and build identifier
testingbot xcuitest app.ipa app-test.zip \
  --device "iPhone 16" \
  --real-device \
  --name "Smoke Tests" \
  --build "v2.1.0"

Device Options

Option	Description
`--device <name>`	Device name (e.g., "iPhone 16", "iPad.*")
`--platform-version <version>`	iOS version (e.g., "17.0", "18.2")
`--real-device`	Use a real device instead of simulator
`--tablet-only`	Only allocate tablet devices (iPads)
`--phone-only`	Only allocate phone devices (iPhones)
`--orientation <orientation>`	Screen orientation: PORTRAIT or LANDSCAPE

Localization & Network

# With localization settings
testingbot xcuitest app.ipa app-test.zip \
  --device "iPhone 16" \
  --real-device \
  --locale "DE" \
  --language "de" \
  --timezone "Europe/Berlin"

# With network throttling and geolocation
testingbot xcuitest app.ipa app-test.zip \
  --device "iPhone 16" \
  --real-device \
  --throttle-network "3G" \
  --geo-location "DE"

Specify one or more capabilities, to indicate on which iOS devices you want to run your tests on.

Replace the :id with the identifier you received during the app upload call. (In this example 4012)

We offer special parameters which you can use to allocate a device:

Regex Input	Result
`"iPhone.*"`	This will allocate any available iPhone device (phone)
`"*"`	This will allocate a random available device
`"iPhone [8-11]"`	This will allocate either an iPhone 8 or 11
`"iPhone 6.*"`	This will allocate either an iPhone 6 or 6S

Some Examples:

// find any iPhone, except 6 or 6s
-d '{"capabilities":[{"deviceName":"^(iPhone.*)(?!6|6S)$", "platformName":"iOS", "realDevice": true}]}'

// find any device which name starts with iPad
-d '{"capabilities":[{"deviceName":"iPad.*", "platformName":"iOS", "realDevice": true}]}'

Tablet Only

You can specify the tabletOnly capability when you only want to allocate a tablet device.

Phone Only

You can specify the phoneOnly capability when you only want to allocate a phone device.


-d '{"capabilities":[{"deviceName":"*", "tabletOnly": true, "platformName":"iOS", "realDevice": true}]}'

-d '{"capabilities":[{"deviceName":"*", "phoneOnly": true, "platformName":"iOS", "realDevice": true}]}'

View XCUITest Results

The XCUITest results will be available in the TestingBot dashboard.

Each test result contains a video, test logs and other meta data generated during the test run.

By default, the CLI waits for test completion and displays real-time progress:

testingbot xcuitest app.ipa app-test.zip --device "iPhone 16" --real-device

The CLI will show:

Upload progress for app and test ZIP
Device allocation status
Live output from XCUITests
Final pass/fail status

Async Mode

Use --async to start tests without waiting for results:

testingbot xcuitest app.ipa app-test.zip --device "iPhone 16" --real-device --async

Download Reports

Download a JUnit or HTML report after test completion:

testingbot xcuitest app.ipa app-test.zip --device "iPhone 16" --real-device \
  --report junit \
  --report-output-dir ./reports

You can also use an API call to get the results from the run(s):

curl -u api_key:api_secret \
"https://api.testingbot.com/v1/app-automate/xcuitest/:id"

Replace the :id with the identifier you received during the app upload call.