Devices

Connect iOS Simulators, real iPhones, and Android devices and fix connection problems.

Pick a device with the device picker in the middle of the toolbar. It reads Select a device until you choose one. Choosing a device connects it, and Disconnect (at the bottom of the picker) releases it. The list updates when simulators or devices appear. When the app opens again, it reconnects the device you chose last (if it is there); after Disconnect it does not.

Disconnect also stops WebDriverAgent on the iPhone or simulator, so no test keeps running there. When you switch to another device or press Reconnect, WebDriverAgent keeps running for 10 minutes, and coming back within that time connects in about a second.

While connecting, the panel shows steps such as Connect to simulator, Connect to iPhone, Connect to emulator, Connect to driver and Stream to Astra Scout. The first iOS connection builds WebDriverAgent (WDA) and takes about 3 to 10 minutes. After that, the build is reused.

Check your machine first

Help → Setup Check… tests everything on this page and tells you how to fix each item. See Settings.

iOS Simulator

1. Install Xcode from the App Store, then open it once to accept the license and install the components it offers.

2. In Xcode → Settings → Components, download an iOS Simulator runtime.

3. Point the command-line tools at Xcode:

   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
   sudo xcodebuild -license accept
   sudo xcodebuild -runFirstLaunch

4. Check that xcrun simctl list runtimes lists a line starting with iOS.

5. Choose a simulator in the device picker.

The app renders the simulator screen itself through Xcode's SimulatorKit. Touches, keys, hardware buttons and rotation go through devicehid, and the mouse wheel becomes a one-finger drag. Without the native app, the server shows simulators as slower WDA screenshots. Flow videos are recorded with xcrun simctl io recordVideo.

The simulator's element tree is read through xcuiax, which is faster than WDA but needs an iOS 27+ simulator. Older simulators, screens with web content, and any error fall back to WDA automatically. Run the server with SCOUT_FAST_AX=0 to turn this off.

Real iPhone

Running on a real iPhone requires signing WebDriverAgent with your Apple account. Do these steps once per Mac and per iPhone.

1. Sign in to Xcode

1. Finish the iOS Simulator steps above.
2. In Xcode → Settings → Accounts, add your Apple ID (one that belongs to the company's Apple Developer team, or a personal one).
3. Select the team, then Manage Certificates… → + → Apple Development. Your Keychain now has a certificate named "Apple Development: Your Name (XXXXXXXXXX)".

The code in parentheses is not the Team ID

The Team ID is the 10-character value on developer.apple.com → Membership details. The app reads the correct Team ID from the certificate.

A Personal Team (free Apple ID) works, but its provisioning profile lasts only 7 days. When it expires, WDA no longer opens and you must reconnect so the app signs again. Use the company team if you have one.

2. Choose a team in the app

1. Open Settings → iOS (section Signing Team).
2. Choose a team from the Team list (saved immediately, no restart needed). If there is exactly one team, it is used automatically.
3. If your team is missing, recheck the step above and click Rescan. You can also enter the Team ID by hand (10 characters, A to Z and 0 to 9) and click Save.
4. The line "In use: …" shows the Team ID the next connection will use.

Whoever runs the server from the command line can use --team-id or MAESTRO_TEAM_ID. The value chosen in Settings takes priority.

3. Prepare the iPhone

1. Connect it with a cable and unlock it. Tap Trust when it asks "Trust This Computer?".
2. In Xcode, open Window → Devices and Simulators, select the iPhone and wait for it to finish preparing.
3. On the iPhone, turn on Settings → Privacy & Security → Developer Mode. It restarts. Unlock it and confirm again. This item only appears after the iPhone has been connected to Xcode.
4. Set Settings → Display & Brightness → Auto-Lock → Never while testing. Astra Scout cannot read this setting, but Setup Check reminds you.

4. Connect and trust the developer

Choose the iPhone in the device picker. The first time, the app builds and installs WDA. If the iPhone shows "Untrusted Developer", go to Settings → General → VPN & Device Management, choose the Apple Development: … certificate and tap Trust, then connect again.

If the WDA build fails because of signing, the line under the mirror shows the fix and the path to build.log, with an Open iOS Settings… button that opens Settings → iOS.

When the iPhone locks itself

A locked iPhone gives a black mirror, a very slow inspector and failing steps. Before each run, exploration, autofix, MCP command and inspector use, Astra Scout asks WDA whether the screen is locked.

• An iPhone without a passcode is unlocked automatically and the run continues.
• An iPhone with a passcode only lights up. Astra Scout refuses the run with "iPhone screen is locked — unlock the iPhone and try again".
• The mirror shows a The iPhone screen is locked notice when it sees the lock.
• If the iPhone locks mid-run, the verdict is Blocked with the code DEVICE_LOCKED. It is not treated as an app bug.

Mirroring

The device frame mirrors an iPhone with CoreDevice's media stream (Xcode 27 and iOS 27, wired or Wi-Fi). It is the only mirror: there is no USB screen capture and no Camera permission. Typing and buttons still go through WDA.

• If the iPhone is locked or not reachable yet, the frame asks you to unlock it and starts by itself once the iPhone answers.
• An iPhone that offers no media stream shows "this iPhone cannot stream its screen over CoreDevice". Flows still run normally.
• If you disconnect and reconnect within 15 seconds, the running stream is reused.
• Flow recordings on an iPhone come only from the CoreDevice media stream. When it is not available, the flow runs without a video and the reason is logged.

Direct control (HID)

With Xcode 27 on the Mac and iOS 27 on the iPhone, taps and drags on the mirror are sent directly to the iPhone's virtual touchscreen by the bundled devicehid tool. The finger presses when you click, follows the mouse, and lifts when you release. Siri, the Action Button, Screenshot, the App Switcher and edge swipes also use HID. Typing, scrolling, rotation and the Home, volume and Power buttons still go through WDA.

• The control session opens at your first tap on the mirror and stays open while the mirror is open, plus 15 seconds after you disconnect.
• While it is open, the iPhone shows "<Mac name> is viewing and controlling this iPhone". This is normal.

Do not tap "Stop Session" on the iPhone

It unpairs the iPhone from the Mac. You would need to plug it in again, tap Trust and pair it again in Xcode.

• If it is unavailable, gestures fall back to WDA replay and flows still run.
• Help → Setup Check… → Real iPhone → Direct iPhone control (HID) shows which iPhone can use it. devicehid is tied to the Xcode CoreDevice framework version, so after updating Xcode, install a newer build if the check reports an error.
• Turn it off by running the server with SCOUT_IOS_HID=0.

clearState on a real iPhone

iOS has no "clear app data" command, so clearState uninstalls and reinstalls the app. On the Simulator Astra Scout takes the installed app itself. On a real iPhone it needs an .ipa or an iPhone-build .app on your Mac. It looks in this order:

1. The file you chose in the toolbar's app menu → App for Real iPhone: enter the App ID, then Choose file….
2. The newest iPhone build of the app (matching bundle id) in Xcode DerivedData or Archives. To create one, choose the plugged-in iPhone as the run destination in Xcode and press Product → Build.

A file is usable only if it is a build for iPhone (iphoneos, not iphonesimulator), is signed, and its provisioning profile includes the plugged-in iPhone. App Store release builds cannot be installed on a test device. Settings shows which file will be used and why a file cannot be used.

If no usable file exists, the run stops before its first step with the verdict Blocked and the code APP_FILE_REQUIRED.

clearState erases app data

It removes all of the app's data on the device (logins, settings, downloaded files), just like uninstalling by hand.

Android

1. Install Android Studio and let it download the Android SDK (default ~/Library/Android/sdk).
2. In Android Studio → Settings → Languages & Frameworks → Android SDK → SDK Tools, enable Android SDK Platform-Tools and Android Emulator.
3. Create a virtual device in Device Manager → Create Virtual Device (for example Pixel 8, API 34 or later).
4. In Astra Scout, open Settings → Emulators → Android SDK. Leave it empty if the SDK is in a default location, or type the path or click Choose Folder….

For a real Android device, tap Build number 7 times in Settings → About phone to enable Developer options, turn on USB debugging, connect the cable and tap Allow USB debugging on the device (tick "Always allow from this computer"). Check with:

~/Library/Android/sdk/platform-tools/adb devices

The device must show the status device, not unauthorized.

Working with a connected device

Controls under the mirror

The action bar under the mirror has buttons that appear only when the connected device supports them.

Where	iOS	Android
Action bar	Home, Screenshot, Rotate, Inspect, Explore	Back, Home, Screenshot, Rotate, Inspect, Explore
More device actions (⋯) menu	App Switcher, Volume Up, Volume Down, Siri (real iPhone), Action Button, Lock, then Install App…, Maximize Mirror and Open in Window	Recents, Volume Up, Volume Down, Power, then Install App…, Maximize Mirror and Open in Window

The side buttons are listed in the ⋯ menu only when the mirror has no device bezel that shows them. Inspect and Explore match Device → Inspect Elements and Device → Explore the App….

On a real iPhone with Xcode 27 on the Mac and iOS 27 on the iPhone, Siri, Action Button, Screenshot and App Switcher go through the CoreDevice HID path (see Direct control (HID)), while Home, volume and Lock go through WDA. Without Xcode 27 and iOS 27 the iPhone only gets the buttons that WDA can press.

Simulator settings (iOS Simulator)

Change simulator settings without leaving the mirror, in the Settings button of the inspector or in Device → Simulator:

• Appearance: Light or Dark.
• Text Size: Smaller, Larger or Default in the menu, or a slider in the inspector.
• Increase Contrast: On or Off.
• Location: a preset, Custom… (latitude and longitude separated by a comma, for example 37.3349, -122.009) or None to clear it.
• Face ID / Touch ID: Enrolled or Not enrolled, then Matching face / finger or Non-matching face / finger to answer a prompt.
• Shake.

The Info button of the inspector lists what Astra Scout knows about the connected device.

Gestures on a real iPhone

Drag up from the bottom edge of the mirror to perform the Home gesture, like on the phone. A touch that starts within about 3% of the screen edge counts as an edge swipe. Flows use the same edge swipes.

Landscape, Maximize and separate window

• Landscape: when you rotate the device, the device bezel turns with the screen.
• Maximize Mirror: gives the mirror the whole window. Click Show Other Panes to bring the layout back. The stream keeps running.
• Open in Window: pops the mirror out into its own window with full touch and keyboard input. The window keeps the aspect ratio of the screen and turns with the device. The main window shows a placeholder with Bring Back, and the Element Hierarchy stays in the main window. The window closes with the device, the main window or the server.

Real iPhone notes

• While the control session is open, the iPhone shows "<Mac name> is viewing and controlling this iPhone". Never tap Stop Session: it unpairs the iPhone. To pair again, plug it in, tap Trust and use Xcode → Window → Devices and Simulators.
• macOS must see the iPhone. A cable always works. Over Wi-Fi sync the iPhone is visible only while it is awake and can disappear when it sleeps, so use a cable.

Install an app

Choose Device → Install App… (Shift+Cmd+I), or Install App… in the ⋯ menu under the mirror. Choose an .app or .ipa file for iOS, or an .apk or .apkm file for Android with Browse…, or pick one under Recently used, then click Install. Astra Scout warns you if the app platform does not match the connected device.

Driver health

Astra Scout checks the driver (WDA on iOS, the DeviceLab socket on Android) before each run and every 15 seconds while connected. If the driver stops answering, the device shows Reconnecting driver… and the driver restarts once. If that fails, the device shows an error with a Retry button, and runs do not start.

Element hierarchy

Device → Element Hierarchy (Option+Cmd+E) shows a tree of the elements on the current screen in the navigator. See Inspector.