iOS simulator setup

Install Xcode, open it once, launch a simulator, and connect it to Drizz. What happens on the first connect.

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

Connect Device → iOS → pick a simulator

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

The guided setup wizard performs everything on this page except the Xcode download, which Apple does not allow any app to automate.

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.

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

• Set up a device: guided wizard

• Tour of the interface

---

Last updated: 6 August 2026