> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/running-tests/devices.md).

# Devices

A test runs in one of three places: on your own Mac, on the Drizz device cloud, or on devices reserved for your organization.

|                       |                                                                     |
| --------------------- | ------------------------------------------------------------------- |
| **Platforms**         | Android · iOS                                                       |
| **Three types**       | Local · Cloud · Private                                             |
| **Session isolation** | Every test gets its own device session                              |
| **No device free**    | The run waits — it doesn't fail. Wait reason `pool_exhausted`       |
| **Watch out**         | Local runs one test at a time. Parallelism only exists in the cloud |

## Prerequisites

* Drizz desktop app installed and signed in, for local devices
* A test plan, for cloud and private devices
* Private devices arranged with your Drizz contact

## Device types

<table data-header-hidden data-search="false"><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td></td><td><strong>Local</strong></td><td><strong>Cloud</strong></td><td><strong>Private</strong></td></tr><tr><td><strong>Where</strong></td><td>Your Mac — emulator, simulator, or a USB device</td><td>The Drizz device cloud</td><td>Your own devices, reserved for your org</td></tr><tr><td><strong>Applies to</strong></td><td>Authoring and debugging</td><td>Regression, parallel runs, device coverage</td><td>Compliance, specific hardware, SIM and carrier testing</td></tr><tr><td><strong>Parallelism</strong></td><td>One test at a time</td><td>Many tests at once</td><td>Bounded by device count</td></tr><tr><td><strong>Queuing</strong></td><td>None — starts immediately</td><td>Waits when nothing is free</td><td>Waits when nothing is free</td></tr><tr><td><strong>Device range</strong></td><td>Whatever you have</td><td>A catalogue of models and OS versions</td><td>Exactly your hardware</td></tr><tr><td><strong>App install</strong></td><td>Whatever is on the device</td><td>The registered build the plan points at</td><td>The registered build the plan points at</td></tr><tr><td><strong>Set up by</strong></td><td>You, once, via the guided wizard</td><td>Nothing to set up</td><td>Arranged with your Drizz contact</td></tr></tbody></table>

## Getting a device

{% tabs %}
{% tab title="Local" %}

1. Open the guided wizard in the desktop app — see [Set up a device: guided wizard](/desktop-app/device-setup-wizard.md).
2. Complete setup for your emulator, simulator or USB device.
3. Open the Connect Device screen and select the device.
4. Confirm it shows as connected.

Local devices run one test at a time and never queue.
{% endtab %}

{% tab title="Cloud Public and Private Devices" %}

1. Open Integrations.
2. Authorise.
3. List of devices and OS will be shown which creating testplan.
   {% endtab %}
   {% endtabs %}

## Sessions are isolated

Every test gets its own device session. A 10-wide run is ten separate sessions, not ten tests sharing a device.

* Parallel tests cannot contaminate each other. One test's login state, cache or leftover data is invisible to the others.
* Test order within a plan is about dependency, not cleanup.
* State carried between tests must be explicit — a shared login module, or a dataset value.

## Waiting, and `pool_exhausted`

When nothing is free, a run **waits rather than failing**, and reports a wait reason.

| Wait reason               | Meaning                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `pool_exhausted`          | No device is free, or every row of a lockable pool is leased                                                       |
| Waiting with devices idle | The block is data, not hardware — check your [lockable pool](/writing-tests/which-variable/lockable-pools.md) size |

A wait times out. Runs that repeatedly wait have one of three causes: insufficient device capacity, concurrency set above capacity, or a lockable pool smaller than concurrency.

## Limits

| Limit                           | Detail                                                                                   |
| ------------------------------- | ---------------------------------------------------------------------------------------- |
| **Location**                    | Set when a cloud device is provisioned. Cannot be changed mid-test                       |
| **Precise location permission** | Not grantable on every device — see [Known limitations](/reference/known-limitations.md) |

## Common mistakes

| What you do                                       | What happens                                                                   |
| ------------------------------------------------- | ------------------------------------------------------------------------------ |
| Raise concurrency to clear a queue                | If the block is a lockable pool, more concurrency adds waiting, not throughput |
| Assume a run used the device you asked for        | It may have fallen back. Read the device recorded on the run                   |
| Debug a failing test on cloud devices             | Slower, and you can't watch the screen. Reproduce locally                      |
| Rely on one test cleaning up for the next         | Sessions are isolated. Make shared state explicit                              |
| Treat a waiting run as a failure                  | It's queued. It will start or time out                                         |
| Compare pass rates across different device models | Device-specific failures read as flakiness                                     |

## Next

* [Creating & running a plan](/running-tests/creating-and-running-a-plan.md)
* [Lockable pools](/writing-tests/which-variable/lockable-pools.md)
* [Troubleshooting](/reports-and-debugging/troubleshooting.md)

***

*Last updated: 6 August 2026*