> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel-labs/agent-browser/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Install Appium">
    ```bash theme={null}
    npm install -g appium
    ```
  </Step>

  <Step title="Install XCUITest driver">
    ```bash theme={null}
    appium driver install xcuitest
    ```
  </Step>
</Steps>

## Usage

### List Available Devices

View all available iOS simulators:

```bash theme={null}
agent-browser device list
```

### Launch Safari on Simulator

Use the `-p ios` provider flag to enable iOS mode:

```bash theme={null}
# 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:

```bash theme={null}
# 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:

```bash theme={null}
# 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

<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", "iPad Pro")</td>
    </tr>

    <tr>
      <td><code>AGENT\_BROWSER\_IOS\_UDID</code></td>
      <td>Device UDID (alternative to device name)</td>
    </tr>
  </tbody>
</table>

## Real Device Support

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

<Steps>
  <Step title="Get your device UDID">
    ```bash theme={null}
    xcrun xctrace list devices
    # or
    system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"
    ```
  </Step>

  <Step title="Sign WebDriverAgent">
    Open the WebDriverAgent Xcode project:

    ```bash theme={null}
    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
  </Step>

  <Step title="Connect and use">
    ```bash theme={null}
    # 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
    ```
  </Step>
</Steps>

<Note>
  **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
</Note>

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

```bash theme={null}
# 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
```