> 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/desktop-app/ios-simulator-setup.md).

# iOS simulator setup

Install Xcode, open it once, boot a simulator, connect from the desktop app.

{% hint style="info" %}
`Connect Device` → **iOS** → pick a simulator
{% endhint %}

|                   |                                                                                  |
| ----------------- | -------------------------------------------------------------------------------- |
| **Platforms**     | iOS (simulator)                                                                  |
| **Requires**      | Xcode, installed from the App Store and **opened once**                          |
| **Disk space**    | 40–50 GB                                                                         |
| **First connect** | A minute or two longer — Drizz builds WebDriverAgent, then caches it             |
| **Watch out**     | Installing Xcode isn't enough. If you never open it, the simulator won't connect |

## Prerequisites

* Drizz desktop app installed and signed in
* macOS 12 or later
* **Xcode**, installed from the Mac App Store and opened at least once with the license screen dismissed
* Xcode command-line tools installed
* 40–50 GB free disk space

{% hint style="success" %}
The [guided setup wizard](/desktop-app/device-setup-wizard.md) performs everything on this page except the Xcode download, which Apple does not allow any app to automate.
{% endhint %}

## Set up Xcode

1. Install **Xcode** from the Mac App Store.
2. Open Xcode once and dismiss the license screen. Creating a project is not required.
3. Install the command-line tools when Xcode prompts on first launch.
4. Confirm `/Applications/Xcode.app` exists. Drizz checks for the full app, not the command-line tools.

Opening Xcode once is required because Drizz accepts the Xcode license from the command line during setup. That only works after the first-launch license screen has been dismissed in Xcode's own window. Otherwise the command waits for a click that cannot arrive in a background process, and it hangs.

## Boot a simulator

1. Open Xcode → **Open Developer Tool** → **Simulator**.
2. Select any iPhone simulator.
3. Wait for it to finish booting, and leave it running.

Drizz connects to a booted simulator. Outside the guided wizard, it does not install one.

## Connect from Drizz

1. In the desktop app, open **Connect Device** and choose **iOS**.
2. Select your simulator from the list.
3. Choose the app under test.
4. Confirm the device panel shows the simulator as connected.

## First connect

Drizz builds and installs **WebDriverAgent** onto the simulator on the first connect. That takes one to two minutes.

| Behavior      | Detail                                                                     |
| ------------- | -------------------------------------------------------------------------- |
| Build caching | The build is cached and reused, so later connects are fast                 |
| Pre-build     | Drizz pre-builds WebDriverAgent in the background when the app starts      |
| Apparent hang | A first connect can take up to two minutes before the device panel updates |

## Simulator vs physical device

| Capability                    | Simulator              | Physical device                                    |
| ----------------------------- | ---------------------- | -------------------------------------------------- |
| Authoring and debugging       | ✅                      | ✅                                                  |
| Camera, Bluetooth, biometrics | ❌                      | ✅                                                  |
| Real push notifications       | ✅                      | ✅                                                  |
| Hardware-only app builds      | ❌                      | ✅                                                  |
| Cost and availability         | Free, always available | Requires an Apple development team and a USB cable |

Setup for hardware is on [Physical iOS device setup](/desktop-app/ios-physical-device.md).

iOS steps run approximately twice as slow as the equivalent Android steps. This is a platform characteristic, not a property of the test.

## Common mistakes

| What you do                                   | What happens                                                                      |
| --------------------------------------------- | --------------------------------------------------------------------------------- |
| Install Xcode but never open it               | Setup hangs on the license step, and the simulator won't connect                  |
| Install only the command-line tools           | Drizz checks for the full `Xcode.app` and refuses. Install Xcode itself           |
| Assume the first connect is stuck             | It's building WebDriverAgent. Wait two minutes before restarting anything         |
| Quit the simulator between runs               | Every connect starts from cold. Leave it booted while you're authoring            |
| Rely on `CLEAR_APP` for a clean state on iOS  | It's effectively a no-op on iOS. Reset in-app, or reinstall between tests         |
| Use `PRESS_DEVICE_BACK_BUTTON` in an iOS test | The command doesn't exist on iOS. Tap the back button or swipe from the left edge |

## Next

* [Physical iOS device setup](/desktop-app/ios-physical-device.md)
* [Set up a device: guided wizard](/desktop-app/device-setup-wizard.md)
* [Tour of the interface](/desktop-app/interface-tour.md)

***

*Last updated: 6 August 2026*