agent-browser

iOS 模拟器#

在 iOS 模拟器中控制真实的 Mobile Safari，用于逼真的移动端网页测试。原生自动化通过 Appium 和 XCUITest 实现。

要求#

  • 安装了 Xcode 的 macOS
  • iOS Simulator runtime（通过 Xcode 下载）
  • 带有 XCUITest driver 的 Appium

设置#

bash
# Install Appium globally
npm install -g appium

# Install the XCUITest driver for iOS
appium driver install xcuitest

列出可用设备#

查看系统中可用的所有 iOS 模拟器：

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

基本用法#

使用 -p ios 标志启用 iOS 模式。工作流与桌面端完全一致：

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

移动端专用命令#

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

环境变量#

通过环境变量配置 iOS 模式：

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
变量描述
AGENT_BROWSER_PROVIDER设为 ios 可启用 iOS 模式
AGENT_BROWSER_IOS_DEVICE设备名称（例如 "iPhone 16 Pro"）
AGENT_BROWSER_IOS_UDID设备 UDID（可替代设备名称）

支持的设备#

Xcode 中所有可用的 iOS 模拟器都受支持，包括：

  • 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.)

真机 也支持通过 USB 连接（见下文）。

真机支持#

Appium 可以通过 USB 控制连接的 iOS 真机上的 Safari。这需要额外的一次性设置。

1. 获取设备 UDID#

bash
# List connected devices
xcrun xctrace list devices

# Or via system profiler
system_profiler SPUSBDataType | grep -A 5 "iPhone\|iPad"

2. 签名 WebDriverAgent（仅一次）#

WebDriverAgent 需要使用你的 Apple Developer 证书签名后才能在真机上运行。

bash
# Open the WebDriverAgent Xcode project
cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
open WebDriverAgent.xcodeproj

在 Xcode 中：

  1. 选择 WebDriverAgentRunner 目标
  2. 进入 Signing & Capabilities
  3. 选择你的 Team（需要 Apple Developer 账号，免费层也可以）
  4. 让 Xcode 自动管理签名

3. 与 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

真机注意事项#

  • 首次运行会把 WebDriverAgent 安装到设备上（可能需要在设备上确认信任）
  • 设备必须解锁并通过 USB 连接
  • 首次连接速度会比模拟器稍慢
  • 用于测试真实 Safari 的性能和行为
  • 首次安装后，前往 Settings → General → VPN & Device Management 信任开发者证书

性能说明#

  • 首次启动： 需要 30-60 秒来启动模拟器并启动 Appium
  • 后续命令： 很快（模拟器会保持运行）
  • 关闭命令： 关闭模拟器和 Appium 服务器

与桌面的差异#

功能桌面端iOS
浏览器Chrome、Lightpanda仅 Safari
标签页支持仅单标签页
PDF 导出支持不支持
投屏支持不支持
滑动手势非原生原生支持

故障排查#

找不到 Appium#

bash
# 确保全局已安装 Appium
npm install -g appium
appium driver install xcuitest

# 验证安装
appium --version

没有可用模拟器#

打开 Xcode，并在 Settings → Platforms 下载 iOS Simulator runtime。

模拟器无法启动#

先尝试从 Xcode 或 Simulator App 手动启动模拟器，确认其可用后，再用 agent-browser 重试。