iOS Simulator

Control real Mobile Safari in the iOS Simulator for authentic mobile web testing. Uses Appium with XCUITest for native automation.

Requirements

macOS with Xcode installed
iOS Simulator runtimes (download via Xcode)
Appium with XCUITest driver

Setup

bash

# Install Appium globally
npm install -g appium

# Install the XCUITest driver for iOS
appium driver install xcuitest

List available devices

See all iOS simulators available on your system:

bash

agent-browser device list

# Output:
# Available iOS Simulators:
#
#   ○ iPhone 16 Pro (iOS 18.0)
#     F21EEC0D-7618-419F-811B-33AF27A8B2FD
#   ○ iPhone 16 Pro Max (iOS 18.0)
#     50402807-C9B8-4D37-9F13-2E00E782C744
#   ○ iPad Pro 13-inch (M4) (iOS 18.0)
#     3A6C6436-B909-4593-866D-91D1062BB070
#   ...

Basic usage

Use the -p ios flag to enable iOS mode. The workflow is identical to desktop:

bash

# Launch Safari on iPhone 16 Pro
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# Get snapshot with refs (same as desktop)
agent-browser -p ios snapshot -i

# Interact using refs
agent-browser -p ios tap @e1
agent-browser -p ios fill @e2 "text"

# Take screenshot
agent-browser -p ios screenshot mobile.png

# Close session (shuts down simulator)
agent-browser -p ios close

Mobile-specific commands

bash

# Swipe gestures
agent-browser -p ios swipe up
agent-browser -p ios swipe down
agent-browser -p ios swipe left
agent-browser -p ios swipe right

# Swipe with distance (pixels)
agent-browser -p ios swipe up 500

# Tap (alias for click, semantically clearer for touch)
agent-browser -p ios tap @e1

Environment variables

Configure iOS mode via environment variables:

bash

export AGENT_BROWSER_PROVIDER=ios
export AGENT_BROWSER_IOS_DEVICE="iPhone 16 Pro"

# Now all commands use iOS
agent-browser open https://example.com
agent-browser snapshot -i
agent-browser tap @e1

<table> <thead> <tr><th>Variable</th><th>Description</th></tr> </thead> <tbody> <tr><td><code>AGENT_BROWSER_PROVIDER</code></td><td>Set to <code>ios</code> to enable iOS mode</td></tr> <tr><td><code>AGENT_BROWSER_IOS_DEVICE</code></td><td>Device name (e.g., "iPhone 16 Pro")</td></tr> <tr><td><code>AGENT_BROWSER_IOS_UDID</code></td><td>Device UDID (alternative to device name)</td></tr> </tbody> </table>

Supported devices

All iOS Simulators available in Xcode are supported, including:

All iPhone models (iPhone 15, 16, 17, SE, etc.)
All iPad models (iPad Pro, iPad Air, iPad mini, etc.)
Multiple iOS versions (17.x, 18.x, etc.)

Real devices are also supported via USB connection (see below).

Real device support

Appium can control Safari on real iOS devices connected via USB. This requires additional one-time setup.

1. Get your device UDID

bash

# List connected devices
xcrun xctrace list devices

# Or via system profiler
system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"

2. Sign WebDriverAgent (one-time)

WebDriverAgent needs to be signed with your Apple Developer certificate to run on real devices.

bash

# Open the WebDriverAgent Xcode project
cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
open WebDriverAgent.xcodeproj

In Xcode:

Select the WebDriverAgentRunner target
Go to Signing & Capabilities
Select your Team (requires Apple Developer account, free tier works)
Let Xcode manage signing automatically

3. Use with agent-browser

bash

# Connect device via USB, then use the UDID
agent-browser -p ios --device "<DEVICE_UDID>" open https://example.com

# Or use the device name if unique
agent-browser -p ios --device "John's iPhone" open https://example.com

Real device notes

First run installs WebDriverAgent to the device (may require Trust prompt on device)
Device must be unlocked and connected via USB
Slightly slower initial connection than simulator
Tests against real Safari performance and behavior
On first install, go to Settings → General → VPN & Device Management to trust the developer certificate

Performance notes

First launch: Takes 30-60 seconds to boot the simulator and start Appium
Subsequent commands: Fast (simulator stays running)
Close command: Shuts down simulator and Appium server

Differences from desktop

<table> <thead> <tr><th>Feature</th><th>Desktop</th><th>iOS</th></tr> </thead> <tbody> <tr><td>Browser</td><td>Chrome, Lightpanda</td><td>Safari only</td></tr> <tr><td>Tabs</td><td>Supported</td><td>Single tab only</td></tr> <tr><td>PDF export</td><td>Supported</td><td>Not supported</td></tr> <tr><td>Screencast</td><td>Supported</td><td>Not supported</td></tr> <tr><td>Swipe gestures</td><td>Not native</td><td>Native support</td></tr> </tbody> </table>

Troubleshooting

Appium not found

bash

# Make sure Appium is installed globally
npm install -g appium
appium driver install xcuitest

# Verify installation
appium --version

No simulators available

Open Xcode and download iOS Simulator runtimes from Settings → Platforms.

Simulator won't boot

Try booting the simulator manually from Xcode or the Simulator app to ensure it works, then retry with agent-browser.