owenleezy Agent Browser — iOS Simulator
Internal template. Entry point:
agent-browserskill.
Recommended config: agent-browser -p ios (short for --provider ios)
NEVER
NEVER run commands before Simulator is booted — daemon can't connect; boot first with xcrun simctl
NEVER use `scroll` on iOS — use `swipe up` / `swipe down` instead
NEVER use `click` on native touch targets — prefer `tap @ref` for iOS elements
NEVER copy element refs across navigations — re-run `snapshot -i` after every screen change
NEVER assume WebView content is inspectable — must enable Web Inspector in Safari → Develop → [device]
Prerequisites
iOS Simulator requires:
- macOS (Apple Silicon or Intel)
- Xcode with iOS Simulator — install from Mac App Store
- Appium —
npm install -g appium && appium driver install xcuitest - Simulator must be running in Xcode before starting agent-browser
# Verify prerequisites
xcodebuild -version # Xcode installed?
appium --version # Appium installed?
appium driver list --installed # XCUITest driver present?
Environment Check
printenv | grep AGENT_BROWSER # already set? Omit the corresponding inline flag
Workflow
# 1. Start Simulator in Xcode first (or via xcrun)
xcrun simctl boot "iPhone 15 Pro"
open -a Simulator
# 2. List available simulators
agent-browser -p ios device list
# 3. Open app in simulator
agent-browser -p ios --device "iPhone 15 Pro" open https://app.example.com
# 4. Explore interactive elements
agent-browser -p ios snapshot -i
# 5. iOS-native gestures
agent-browser -p ios tap @e1
agent-browser -p ios swipe up # scroll up
agent-browser -p ios swipe down # scroll down
agent-browser -p ios swipe left # swipe carousel / delete row
agent-browser -p ios swipe right # go back (swipe edge)
# 6. Standard commands work too
agent-browser -p ios screenshot --full ios-result.png
agent-browser -p ios find role button click --name "Submit"
agent-browser -p ios get text @e3
agent-browser -p ios wait --load networkidle
Key Patterns
| Pattern | Command |
|---|---|
| List simulators | agent-browser -p ios device list |
| Target specific device | -p ios --device "iPhone 15 Pro" |
| iOS scroll | swipe up / swipe down (not scroll) |
| iOS tap | tap @e1 (preferred over click for touch targets) |
| Navigate back | swipe right (edge swipe) |
| Dismiss bottom sheet | swipe down |
| Take evidence screenshot | screenshot --full ios-result.png |
| Inspect DOM (WebView) | snapshot -i (for web content in WKWebView) |
Chrome Commands That Still Work on iOS
These standard commands work with -p ios:
open <url>— navigatesnapshot/snapshot -i— accessibility treefind role button click --name "..."— semantic locatorget text @e1/get value @e1screenshot [path]/screenshot --fullwait @e1/wait --load networkidleis visible @e1/is enabled @e1errors/console(for WebView content)
Pitfalls
| Mistake | Fix |
|---|---|
| Simulator not started before running | Start Simulator in Xcode first, or xcrun simctl boot "iPhone 15 Pro" |
| Appium not installed | npm install -g appium && appium driver install xcuitest |
Using scroll instead of swipe |
iOS uses swipe up/swipe down, not scroll |
Using click on touch-only elements |
Prefer tap @e1 for native touch targets |
device list shows no devices |
Simulator not booted — open Xcode → Simulators and boot one |
| XCUITest driver missing | appium driver install xcuitest |
| WebView content not inspectable | Enable "Web Inspector" in Safari → Develop → [device name] |