跳转至

iOS 模拟器

在 iOS 模拟器中控制真实的 Mobile Safari，以实现真实的移动 Web 测试。使用 Appium 与 XCUITest 进行原生自动化。

要求

  • 安装了 Xcode 的 macOS
  • iOS 模拟器运行时（通过 Xcode 下载）
  • 带有 XCUITest 驱动的 Appium

设置

# Install Appium globally
npm install -g appium

# Install the XCUITest driver for iOS
appium driver install xcuitest

列出可用设备

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

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 模式。工作流程与桌面端相同：

# 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

移动端专用命令

# 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 模式：

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 模拟器，包括：

  • 所有 iPhone 机型（iPhone 15、16、17、SE 等）
  • 所有 iPad 机型（iPad Pro、iPad Air、iPad mini 等）
  • 多个 iOS 版本（17.x、18.x 等）

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

真机支持

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

1. 获取设备 UDID

# List connected devices
xcrun xctrace list devices

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

2. 对 WebDriverAgent 进行签名（一次性）

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

# 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. 选择您的团队（需要 Apple Developer 账户，免费版本即可）
  4. 让 Xcode 自动管理签名

3. 与 agent-browser 一起使用

# 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 的性能和行为进行测试
  • 首次安装后，前往“设置 → 通用 → VPN 与设备管理”以信任开发者证书

性能说明

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

与桌面版的区别

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

故障排查

找不到 Appium

# Make sure Appium is installed globally
npm install -g appium
appium driver install xcuitest

# Verify installation
appium --version

没有可用的模拟器

打开 Xcode，从设置 → 平台下载 iOS 模拟器运行时。

模拟器无法启动

尝试从 Xcode 或“模拟器”App 手动启动模拟器，确保其正常工作，然后使用 agent-browser 重试。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 agen/agent-browser