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

# 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:

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:

# 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

# 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:

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

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

# 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.

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

In Xcode:

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

3. Use with agent-browser

# 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

Troubleshooting

Appium not found

# 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.