Skip to main content
Control real Mobile Safari in the iOS Simulator for authentic mobile web testing. Requires macOS with Xcode.

​
Prerequisites

  • macOS with Xcode installed
  • Appium and XCUITest driver

​
Installation

1

Install Appium

npm install -g appium
2

Install XCUITest driver

appium driver install xcuitest

​
Usage

​
List Available Devices

View all available iOS simulators: 
agent-browser device list

​
Launch Safari on Simulator

Use the -p ios provider flag to enable iOS mode: 
# Launch on specific device
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# Or use environment variables
export AGENT_BROWSER_PROVIDER=ios
export AGENT_BROWSER_IOS_DEVICE="iPhone 16 Pro"
agent-browser open https://example.com

​
Basic Workflow

All standard commands work identically on iOS: 
# Get page snapshot
agent-browser -p ios snapshot -i

# Interact with elements 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
agent-browser -p ios close

​
Mobile-Specific Commands

iOS mode includes touch gestures: 
# Swipe gestures
agent-browser -p ios swipe up
agent-browser -p ios swipe down 500
agent-browser -p ios swipe left
agent-browser -p ios swipe right

# Tap (alias for click)
agent-browser -p ios tap @e1

​
Environment Variables

VariableDescription
AGENT_BROWSER_PROVIDERSet to ios to enable iOS mode
AGENT_BROWSER_IOS_DEVICEDevice name (e.g., “iPhone 16 Pro”, “iPad Pro”)
AGENT_BROWSER_IOS_UDIDDevice UDID (alternative to device name)

​
Real Device Support

Appium also supports real iOS devices connected via USB. Additional one-time setup required:
1

Get your device UDID

xcrun xctrace list devices
# or
system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"
2

Sign WebDriverAgent

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

Connect and use

# Connect device via USB, then:
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)
  • Device must be unlocked and connected via USB
  • Slightly slower initial connection than simulator
  • Tests against real Safari performance and behavior

​
Performance

First launch takes ~30-60 seconds as the simulator boots and Appium starts. Subsequent commands are fast.

​
Supported Devices

All iOS Simulators available in Xcode are supported, including:
  • iPhones (all models)
  • iPads (all models)
  • Real iOS devices (with additional setup)

​
Example: Mobile Testing Workflow

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

# Test responsive behavior
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1
agent-browser -p ios swipe up 300

# Capture mobile screenshot
agent-browser -p ios screenshot mobile-home.png

# Test landscape orientation (rotate simulator manually)
agent-browser -p ios screenshot mobile-landscape.png

# Clean up
agent-browser -p ios close

Build docs developers (and LLMs) love

Get started for freeTalk to us