iOS Simulator

Test mobile web apps with real Safari on iOS Simulator

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

Variable	Description
AGENT_BROWSER_PROVIDER	Set to ios to enable iOS mode
AGENT_BROWSER_IOS_DEVICE	Device name (e.g., “iPhone 16 Pro”, “iPad Pro”)
AGENT_BROWSER_IOS_UDID	Device 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