XCUITest

This guide covers how to build and package your compiled XCUITest suite (*-Runner.app) so it runs correctly on the MobileBoost device grid, and how to trigger and monitor runs via the API. Follow the section that matches where you want to run: physical devices or virtual devices (simulators). The two are not interchangeable - a runner built for one will not launch on the other.

You do not need to solve code signing or provisioning for our devices. Our grid re-signs the test runner with the certificate and device profile for the specific hardware it runs on.

All API endpoints below authenticate with your mb_live_ API key passed as a Bearer token in the Authorization header.

Prerequisites

Xcode (matching or newer than the OS versions you target).
Your project has a UI Testing bundle target and a scheme that includes it in its Test action.
You know three bundle identifiers - you’ll need them at upload time:
- App under test (must match the .ipa you upload)
- Test runner (*-Runner)
- Test bundle (*UITests)

1. Why physical vs. virtual matters

build-for-testing compiles your runner and its .xctest bundle for one platform slice at a time:

Target	Destination	Output folder	Runs on
Physical	`generic/platform=iOS`	`Debug-iphoneos/`	Real iPhones/iPads
Virtual	`generic/platform=iOS Simulator`	`Debug-iphonesimulator/`	Simulators

A simulator build links the simulator XCTest frameworks and CPU slice; a device build links the device ones. Uploading the wrong slice is the single most common failure - it will install but the test harness won’t start. If you want to run on both, build and upload two separate zips.

2. Build the runner

Physical devices
Virtual devices (simulators)

xcodebuild build-for-testing \
  -scheme <YOUR_SCHEME> \
  -destination 'generic/platform=iOS' \
  -derivedDataPath ./build

Output lands in:

./build/Build/Products/Debug-iphoneos/<YOUR_SCHEME>UITests-Runner.app
./build/Build/Products/<...>.xctestrun

xcodebuild build-for-testing \
  -scheme <YOUR_SCHEME> \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath ./build

Output lands in:

./build/Build/Products/Debug-iphonesimulator/<YOUR_SCHEME>UITests-Runner.app
./build/Build/Products/<...>.xctestrun

3. Package the runner zip

Zip from inside the Products slice folder so the .app is at the root of the archive, and use --symlinks (framework bundles contain symlinks - omitting this bloats the zip and can break the embedded frameworks).

Physical devices
Virtual devices (simulators)

cd ./build/Build/Products/Debug-iphoneos
zip --symlinks -r ~/MyAppUITests-physical.zip \
  *-Runner.app \
  ../*.xctestrun

cd ./build/Build/Products/Debug-iphonesimulator
zip --symlinks -r ~/MyAppUITests-simulator.zip \
  *-Runner.app \
  ../*.xctestrun

Zip contents (required + recommended):

*-Runner.app - required (contains PlugIns/*.xctest, your compiled tests)
*.xctestrun - recommended. It preserves your test configuration: launch environment variables, launch arguments, the target-app reference, and skip/only test lists. Include it and your tests run exactly as configured in your scheme.

4. Verify the zip before uploading

# Confirm the runner and the compiled test bundle are present
unzip -l ~/MyAppUITests-physical.zip | grep -E 'Runner.app|\.xctest|\.xctestrun'

You should see the *-Runner.app, a PlugIns/*UITests.xctest inside it, and the .xctestrun. To sanity-check you built the device slice (not simulator) when targeting physical hardware, confirm it came out of the Debug-iphoneos folder - that folder is the source of truth for the slice.

5. Bundle-ID matching

The app under test you upload as .ipa must have the same bundle identifier the test scheme was built against. If your tests use a bare XCUIApplication(), it launches the scheme’s target app by bundle ID; a mismatch means the tests launch nothing (or the wrong app).

For physical runs, upload your enterprise-distribution .ipa as the app under test. Do not upload the debug Debug-iphoneos/*.app produced by build-for-testing as the app under test - that debug app and your test runner just need to share the bundle ID, not the binary.
If your tests target a specific bundle explicitly, use XCUIApplication(bundleIdentifier: "<APP_UNDER_TEST_BUNDLE_ID>") and tell us that ID.

6. Code signing - what you do and don’t need to do

Physical devices: You do not need a provisioning profile that includes our devices. We re-sign the runner with our own Apple Development certificate and a profile scoped to the target hardware. To avoid any local provisioning friction, you can even build without signing:

xcodebuild build-for-testing \
  -scheme <YOUR_SCHEME> \
  -destination 'generic/platform=iOS' \
  -derivedDataPath ./build \
  CODE_SIGNING_ALLOWED=NO

(Building with your own team’s automatic signing is also fine - we strip and re-sign either way.) Virtual devices: Simulators don’t enforce code signing; no certificates or profiles are required. Because we re-sign the runner, please keep bundle identifiers stable and don’t hard-code entitlements that depend on your own team’s provisioning (e.g. keychain-sharing / app-group IDs tied to your Team ID) in the UI test target - those can break re-signing. Your app under test is unaffected; it keeps your enterprise signature.

7. Optional: get your test list for sharding

If you want to split tests across devices, we can shard automatically, or you can send us the test identifiers:

xcodebuild -scheme <YOUR_SCHEME> -showTestPlans

Identifiers use TargetName/ClassName/testMethod and can be passed as only-testing / skip-testing filters at launch time.

8. What to upload

You’ll end up with, per target type:

File	Purpose	Upload endpoint
`MyApp.ipa`	App under test (enterprise-signed for physical; simulator `.app`-zip for virtual)	`POST /uploadBuild`
`MyAppUITests-<physical\|simulator>.zip`	Compiled test runner + `.xctestrun`	`POST /app-automate/xcui/test-suite`

Common mistakes checklist

Built for simulator, uploaded for a physical run (or vice-versa). → Build the matching slice; upload the matching zip.
Zipped from the wrong directory, so the .app is nested under Build/Products/... inside the archive. → cd into the slice folder first; the .app must be at the zip root.
Zipped without --symlinks. → Frameworks break / signing fails.
App-under-test bundle ID ≠ what the tests expect. → Keep them identical; tell us the ID.
Uploaded the debug build-for-testing app instead of the enterprise .ipa for physical runs. → Upload your enterprise IPA as the app under test.
Ran test instead of build-for-testing (produces no reusable runner). → Use build-for-testing.

9. Trigger a test run

Once both files are uploaded, start a run with the IDs returned by the two upload calls: the app_id from POST /uploadBuild and the test_suite_id from POST /app-automate/xcui/test-suite. Endpoint

POST /app-automate/xcui/build

Minimal request

curl -X POST "https://api.mobileboost.io/app-automate/xcui/build" \
  -H "Authorization: Bearer $MOBILEBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "<APP_ID>",
    "testSuite": "<TEST_SUITE_ID>"
  }'

Required parameters

Field	Description
`app`	The `app_id` returned by `POST /uploadBuild`.
`testSuite`	The `test_suite_id` returned by `POST /app-automate/xcui/test-suite`.

Optional parameters

Field	Description
`project`, `buildTag`	Free-text labels for grouping and filtering runs.
`gpsLocation`	Location applied to every device before tests start.
`only-testing` / `skip-testing`	Run or exclude specific tests (whole run, no sharding). Values are `TargetName/ClassName/testMethod` identifiers.
`shards`	Split the suite across devices, optionally with an explicit test list per shard.

Full request with GPS and sharding

curl -X POST "https://api.mobileboost.io/app-automate/xcui/build" \
  -H "Authorization: Bearer $MOBILEBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app": "<APP_ID>",
    "testSuite": "<TEST_SUITE_ID>",
    "project": "My iOS App",
    "buildTag": "main-2026-07-01",

    "gpsLocation": { "latitude": 40.698979, "longitude": -73.9958661 },

    "shards": {
      "numberOfShards": 2,
      "mapping": [
        {
          "name": "shard-1",
          "strategy": "only-testing",
          "values": ["MyAppUITests/LoginTests", "MyAppUITests/CheckoutTests/testAddToCart"]
        },
        {
          "name": "shard-2",
          "strategy": "only-testing",
          "values": ["MyAppUITests/SearchTests"]
        }
      ]
    }
  }'

GPS location

gpsLocation overrides the device’s location for the whole run; it is applied on each device before your first test starts and cleared automatically at teardown.

{ "latitude": 40.698979, "longitude": -73.9958661, "altitude": 0.0 }

Field	Required	Notes
`latitude`	yes	Decimal degrees.
`longitude`	yes	Decimal degrees.
`altitude`	no	Meters, default `0.0`. Honored on virtual devices only; ignored on physical iOS (the simulated-location channel there is lat/long only).

If you omit gpsLocation, physical devices keep their real GPS and virtual devices use our neutral default. To read or change the location from inside a test, drive your app’s own location flows as usual - gpsLocation sets the starting position for the run.

Sharding

Sharding is optional. Provide a shards object to split the suite across devices and run them in parallel. Auto-distribute - give only numberOfShards; we spread the discovered tests evenly across that many shards:

{ "numberOfShards": 3 }

Explicit test cases per shard - provide a mapping array. Each entry names a shard and lists the tests it runs via strategy: "only-testing" and a values list of TargetName/ClassName[/testMethod] identifiers. numberOfShards must match the number of mapping entries.

{
  "numberOfShards": 2,
  "mapping": [
    { "name": "shard-1", "strategy": "only-testing", "values": ["MyAppUITests/LoginTests"] },
    { "name": "shard-2", "strategy": "only-testing", "values": ["MyAppUITests/SearchTests"] }
  ]
}

A strategy of skip-testing is also accepted per shard if you prefer to express a shard as “everything except these”. Use -showTestPlans to list valid identifiers. Response

{
  "message": "Success",
  "build_id": "4d2b4deb810af077d5aed98f479bfdd2e64f36c3"
}

Store the build_id; it identifies the run when you poll status and download results.

10. Check run status

Poll the build with the build_id from the launch response.

GET /app-automate/xcui/build/<BUILD_ID>

curl -H "Authorization: Bearer $MOBILEBOOST_API_KEY" \
  "https://api.mobileboost.io/app-automate/xcui/build/$BUILD_ID"

The build carries an overall status plus one session per device/shard combination. Each session has its own session_id.

{
  "build_id": "4d2b4deb810af077d5aed98f479bfdd2e64f36c3",
  "status": "running",
  "sessions": [
    {
      "session_id": "9f1c2a7b6e3d4f018a2b5c6d7e8f9012",
      "device": "iPhone 15 Pro-18.5",
      "shard": "shard-1",
      "status": "passed",
      "tests": { "total": 12, "passed": 12, "failed": 0, "skipped": 0 }
    },
    {
      "session_id": "1a2b3c4d5e6f70819aabbccddeeff0011",
      "device": "iPhone 15 Pro-18.5",
      "shard": "shard-2",
      "status": "running",
      "tests": { "total": 8, "passed": 3, "failed": 0, "skipped": 0 }
    }
  ]
}

Status values (both build and session): queued, running, passed, failed, error (infrastructure/setup problem, e.g. install or signing failure), timedout. Poll until terminal

while :; do
  STATUS=$(curl -s -H "Authorization: Bearer $MOBILEBOOST_API_KEY" \
    "https://api.mobileboost.io/app-automate/xcui/build/$BUILD_ID" | jq -r '.status')
  echo "status: $STATUS"
  case "$STATUS" in
    queued|running) sleep 10 ;;
    *) break ;;
  esac
done

11. Retrieve results

Once the build reaches a terminal status, fetch the machine-readable report at the build level.

GET /app-automate/xcui/build/<BUILD_ID>/report?format=<junit|json>

curl -H "Authorization: Bearer $MOBILEBOOST_API_KEY" \
  "https://api.mobileboost.io/app-automate/xcui/build/$BUILD_ID/report?format=junit" \
  -o results.xml

junit returns a standard JUnit XML your CI can ingest; json returns the same pass/fail data as structured JSON.

Getting started

Tests

Runs

Builds

Native Runners

Audit

Prerequisites

1. Why physical vs. virtual matters

2. Build the runner

3. Package the runner zip

4. Verify the zip before uploading

5. Bundle-ID matching

6. Code signing - what you do and don’t need to do

7. Optional: get your test list for sharding

8. What to upload

Common mistakes checklist

9. Trigger a test run

GPS location

Sharding

10. Check run status

11. Retrieve results

​Prerequisites

​1. Why physical vs. virtual matters

​2. Build the runner

​3. Package the runner zip

​4. Verify the zip before uploading

​5. Bundle-ID matching

​6. Code signing - what you do and don’t need to do

​7. Optional: get your test list for sharding

​8. What to upload

​Common mistakes checklist

​9. Trigger a test run

​GPS location

​Sharding

​10. Check run status

​11. Retrieve results

Prerequisites

1. Why physical vs. virtual matters

2. Build the runner

3. Package the runner zip

4. Verify the zip before uploading

5. Bundle-ID matching

6. Code signing - what you do and don’t need to do

7. Optional: get your test list for sharding

8. What to upload

Common mistakes checklist

9. Trigger a test run

GPS location

Sharding

10. Check run status

11. Retrieve results