Appium iOS 自动化入门：XCUITest、真机签名与 Python 脚本

用当前 Appium XCUITest driver 搭建 iPhone 自动化，区分 Appium server 与 WebDriverAgent，正确设置能力、元素等待及 WebView 调试。

先理清四层连接

测试脚本把 WebDriver 命令发送给 Appium server；XCUITest driver 将命令交给运行在模拟器或真机上的 WebDriverAgent（WDA）；WDA 再通过 Apple 自动化能力操作 App。Appium Inspector 是查看页面元素和能力配置的辅助工具，不代替 driver。

旧笔记曾将 iOS driver 写成 uiautomator2，并把 automationName 设为 Chromium。那是过时或误写的配置；下文依当前 XCUITest 文档重写。

表格可左右滑动，查看完整比较 →

组件	作用	常见混淆
Appium server	接受测试客户端会话	通常连接 localhost:4723
XCUITest driver	在 iOS 上执行自动化	安装 xcuitest，不是 uiautomator2
WebDriverAgent	设备侧自动化桥接	8100 不是普通 Appium server 地址
Appium Inspector	查看元素与调试会话	不会替代签名和 WDA

安装并先跑通模拟器

先按 Appium 当前文档安装兼容版本的 Node.js、Appium 和 Xcode。下面的命令安装 XCUITest driver，列出已安装的 driver，再启动 Appium server；最低版本以你安装的 driver 文档为准。

优先用可启动的 iOS Simulator、已安装的测试 App 和唯一的 bundleId 跑通一条简单操作，再转真机。测试脚本使用 platformName=iOS、appium:automationName=XCUITest 和 appium:bundleId；设备有多个时再指定 appium:udid。

npm install -g appium
appium driver install xcuitest
appium driver list --installed
appium

Python 最小会话应怎么写

安装与当前 Appium server / XCUITest driver 兼容的 Appium Python Client。使用 XCUITestOptions 和 webdriver.Remote 的 options 参数；把示例 bundleId、可访问性标识替换为自己 App 的值，且先确保测试 App 已安装。

from appium import webdriver
from appium.options.ios import XCUITestOptions
from appium.webdriver.common.appiumby import AppiumBy
from selenium.webdriver.support.ui import WebDriverWait

options = XCUITestOptions()
options.set_capability("appium:bundleId", "com.example.TestApp")
# If several devices are available:
# options.set_capability("appium:udid", "YOUR_DEVICE_UDID")

driver = webdriver.Remote("http://127.0.0.1:4723", options=options)
try:
    button = WebDriverWait(driver, 10).until(
        lambda d: d.find_element(AppiumBy.ACCESSIBILITY_ID, "start-button")
    )
    button.click()
    driver.save_screenshot("after-tap.png")
finally:
    driver.quit()

表格可左右滑动，查看完整比较 →

旧笔记写法	当前建议
desired_caps 位置参数	XCUITestOptions + options=options
find_element_by_name	AppiumBy.ACCESSIBILITY_ID 或其他明确定位方式
连接设备 8100 端口	普通测试连接 Appium server 的 4723 端口
把等待对象当成 sleep	WebDriverWait(...).until(...) 等待具体条件

创建 XCUITestOptions，设置 appium:bundleId；有多台设备时设置 appium:udid。
连接本机 Appium server，而不是直接把 WDA 的 8100 端口当作会话入口。
用 WebDriverWait 等待元素，再用 AppiumBy.ACCESSIBILITY_ID 定位并操作。
无论成功或异常，都在 finally 中 driver.quit()，避免残留会话。

真机失败时先查 WDA 签名

真机使用 WDA 时，需要 Xcode 开发团队、可用的签名身份和测试设备授权。按 XCUITest 官方真机签名指南配置 xcodeOrgId、xcodeSigningId 或相应 provisioning profile；不要在公开日志贴团队证书、UDID 或 App 的内部 bundleId。

出现“WDA 启动失败”时先区分构建失败、签名失败、设备未信任、目标 App 未安装与网络转发失败。保存 Appium 与 Xcode 的第一条有效错误，再按错误所在层修复；反复改 capabilities 往往会遮住真正原因。

混合 App 的 WEBVIEW 什么时候可见

原生元素位于 NATIVE_APP context，网页内容需要当前 XCUITest driver 能发现对应 WEBVIEW context。先确认页面确实使用可检查的 WKWebView、设备与 Safari Web Inspector 设置满足官方前置条件，然后等待 contexts 出现并切换；不要把整个 iOS 会话的 automationName 改成 Chromium。

如果 contexts 只有 NATIVE_APP，先看 WebView 是否加载完、调试权限与远程检查是否可用。返回原生界面前再切回 NATIVE_APP。对于 iOS 返回操作，优先定位 App 自己的返回按钮；不要把特定应用里 driver.back() 的失败写成所有 iOS App 的通用规则。

验证与维护

把一个可复现用例固定下来：冷启动测试 App、等待指定元素、点击、截图、退出。记录 Appium、driver、Python client、Xcode、iOS 和 App 版本，以便升级后定位兼容性变化。资料核对日期：2026-11-06；本文基于作者旧笔记重写，未声称在当前读者设备上完成实测。