docs: mdx, light/dark mode, ask (#400)

2026-02-09 11:16:21 -06:00
parent 4d8097a56f
commit e8ceafcbe1
36 changed files with 4221 additions and 1258 deletions
@@ -0,0 +1,199 @@
+export const metadata = { title: "iOS Simulator" }
+
+# 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
+```
+
+| Variable | Description |
+| --- | --- |
+| `AGENT_BROWSER_PROVIDER` | Set to `ios` to enable iOS mode |
+| `AGENT_BROWSER_IOS_DEVICE` | Device name (e.g., "iPhone 16 Pro") |
+| `AGENT_BROWSER_IOS_UDID` | Device UDID (alternative to device name) |
+
+## 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:
+
+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
+
+```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
+
+| Feature | Desktop | iOS |
+| --- | --- | --- |
+| Browser | Chromium/Firefox/WebKit | Safari only |
+| Tabs | Supported | Single tab only |
+| PDF export | Supported | Not supported |
+| Screencast | Supported | Not supported |
+| Swipe gestures | Not native | Native support |
+
+## 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.