> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile Testing

> Test mobile apps on virtual and physical iOS and Android devices.

Run natural language flows against iOS and Android apps in the cloud. Use iOS Simulators and Android Emulators for fast coverage, or run the same flows on physical devices when you need real hardware.

## Available devices and OS versions

Every mobile run can target a specific device model and OS version. In the run dialog, choose a **Target**, then select a **Model** and **OS version**. If you do not change the selection, BugRadar uses the newest model and OS.

| Target | Current coverage |
| - | - |
| Android Emulator | Pixel 6 through Pixel 10 families on Android 14–17 |
| iOS Simulator | iPhone and iPad models on iOS 17–26 |
| Real device | Available iOS and Android phones and tablets; the exact catalog changes with device availability |

The device picker shows the exact model and OS combinations available for your app. iOS Simulator versions marked **Fast launch** use an optimized startup path; every listed combination is supported.

For API runs, use [List Devices](/docs/api-runs.md#list-devices) to retrieve the current catalog, then pass one of the returned combinations in the run's `device` object.

## Physical Device Testing

Run any mobile flow on real hardware — actual iPhones, Pixels, and Galaxy devices — instead of an emulator or simulator. Same flows, same agent, real devices.

### Build requirements

What you can run depends on the build you upload:

| Platform | Build | Runs on |
| - | - | - |
| iOS | `.app` / `.app.zip` | Simulator only |
| iOS | `.ipa` | Real devices only |
| Android | `.apk` | Emulators **and** real devices |

For iOS, upload an `.ipa` built for physical devices. Android builds work on both targets with no changes.

### Running on a real device

> [tab] Dashboard
>
> Click **Run** on a flow (or suite), set **Target** to **Real device**, and pick a device model and OS version. The picker lists the live device catalog, newest models first, and defaults to the newest available device. If that device is busy, the run moves to the closest free device instead of failing. To keep the model or OS fixed, set `match` through the API (see [Picking a device](#picking-a-device)) or the [CI action](/docs/ci-cd-integration.md).
>
> If your app's default build is an `.ipa`, the dialog opens on **Real device** automatically.
>
> **Real device** stays visible but disabled when your organization has no real-device access or your app has no compatible build. Hover over or keyboard-focus the option to see why. For access, contact [founders@usebugradar.com](mailto:founders@usebugradar.com); for an iOS simulator-only app, upload an `.ipa`.

> [tab] API
>
> Pass one `device` object in the body — see [API → Run Flows](/docs/api-runs.md).
>
> ```bash theme={null}
> curl -X POST https://backend.usebugradar.com/api/v1/flows/run \
>   -H "X-API-Key: $BugRadar_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "bundle_id": "com.example.app",
>     "platform": "ios",
>     "flow_ids": ["660e8400-e29b-41d4-a716-446655440001"],
>     "device": {
>       "physical": true,
>       "model": "iPhone 16 Pro",
>       "os_version": "18"
>     }
>   }'
> ```
>
> Set model and OS to `"latest"`, or omit them, to run on the best available
> physical device for the platform.

### Picking a device

The `device` object narrows which device the run lands on:

* `model` — e.g. `"iPhone 16 Pro"`, `"Pixel 9"`, or `"latest"`. Matches the names shown in the dashboard picker.

* `physical` — use `true` for real hardware; it defaults to `false`.

* `os_version` — `"18"` matches any 18.x; `"18.3.1"` matches only that version; `"latest"` keeps it rolling.

* `match` — per field, `"similar"` (the default) or `"exact"`, for example `{"os_version": "exact"}`. When the pinned device is busy, the run moves to the closest free phone or tablet: same model on another OS first, then the same brand, closest OS and generation. A field set to `"exact"` never changes, so `{"os_version": "exact"}` means any model on that OS, preferring the one you pinned.

Device availability is checked when the run starts. If nothing acceptable is free, the run waits up to 5 minutes for one before it fails with a clear error. The run page always shows the device it actually ran on.

### What you get

Real-device runs flow through the same pipeline as every other run:

* **Full video recording** of the session, with per-action replay markers
* **Screenshots and annotations** for every agent action
* **Device identity on the run page** — the exact model and OS the run executed on (e.g. `Pixel 9 · Android 16 · Real device`)
* Suites share one device session across their flows, so back-to-back flows start fast

> [!NOTE]
>
> Real-device runs take \~1–2 minutes longer to start than emulator runs while a device is acquired, and iOS sessions take a few extra minutes to finalize their video after the run completes.

### Native in-app purchases

Testing native Apple or Google purchase flows on private devices requires an enterprise contract with BugRadar and coordinated onboarding. [Contact us](mailto:founders@usebugradar.com) before preparing a build so we can confirm feasibility, device availability, and the signing and test-account setup. Selecting **Real device** alone does not configure native purchase testing.

See [Testing In-App Purchases](/docs/guides-in-app-purchases.md#native-in-app-purchases-on-private-devices) for onboarding details and the self-service RevenueCat Test Store workflow.

### Push notifications

End-to-end push-notification testing on physical iOS and Android devices uses private devices that preserve the app's original signing and notification entitlements. This requires an enterprise contract. [Contact us](mailto:founders@usebugradar.com) for availability and setup.

For self-service APNs and FCM testing, see [Testing Push Notifications](/docs/guides-push-notifications.md) for the iOS Simulator and Android Emulator workflow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.