python-wda：用 Python 操控 iOS 设备

facebook-wda 在 GitHub 上拿到了 1,869 Star。

这是一个非官方的 Facebook WebDriverAgent Python 客户端库，用来通过 Python 代码远程操控 iOS 设备。点按、滑动、截图、获取界面元素，都能用脚本完成。

1、 这项目是干嘛的

WebDriverAgent 是 Facebook 早年开源的一套 iOS 自动化框架，基于 XCTest 和 XCUITest 实现，能在不越狱的情况下操控 iOS 设备。后来 Facebook archive 了这个项目，社区 fork 出了 appium/WebDriverAgent 继续维护。

python-wda 就是这套协议的 Python 封装。你在 iOS 设备上跑起 WDA 服务，然后在电脑上用几行 Python 就能远程操作设备。本质上是一个 HTTP 客户端，通过 REST API 跟设备上的 WDA 服务端通信。

2、 能做什么

它的能力覆盖了 iOS 自动化测试的常见需求。

设备层面，可以按 Home 键、锁屏、解锁、获取屏幕尺寸、截图、获取当前前台应用信息。也能读取电池电量、设备时区等基本信息，还能调用 Siri。

应用操控层面，支持启动和终止应用、激活已运行的应用、获取应用运行状态。通过 session 机制，可以进入某个应用执行具体操作，也支持带参数启动，比如直接打开 Safari 并访问指定网页。

UI 交互层面，支持点击、长按、滑动、双击、捏合手势。也能通过 id、className、name、label、xpath、predicate、classChain 等多种方式定位元素，然后对元素执行点击、输入文字、滚动、清除内容等操作。

弹窗处理也内置了。可以监听特定按钮自动点击，也可以手动接受或取消弹窗。alert.watch_and_click 配合 with 语句，能在一段操作期间自动处理干扰弹窗。

元素查找失败后，会抛出 WDAElementNotFoundError。支持设置隐式等待时间和显式等待，避免脚本因为界面加载时序问题而崩溃。

3、 怎么用

使用之前，需要先在 iOS 设备或模拟器上启动 WebDriverAgent。可以用 tidevice 工具在 Linux 和 Windows 上直接启动，不需要 Xcode。也可以在 Mac 上用 xcodebuild 命令启动，真机运行需要配置好代码签名。

装好 WDA 之后，安装客户端库：

pip3 install -U facebook-wda

然后几行代码就能连接设备：

import wda

c = wda.Client('http://localhost:8100')
print(c.status())
c.screenshot('screen.png')

创建 session 进入某个应用：

with c.session('com.apple.Health') as s:
    print(s.orientation)
    s.tap(200, 200)

找元素并操作：

s(id="URL").tap()
s(name='URL').get(timeout=10.0)
s(text='Dashboard').click_exists(timeout=5.0)

支持坐标点击和比例点击，比如 s.click(0.5, 0.5) 直接点屏幕正中心，在不同分辨率设备上都能正常工作。

它也支持通过 USB 直连设备，绕过不稳定的 WiFi 连接。可以用 iproxy 做端口转发，或者直接用 USBClient 类通过 usbmuxd 通信，不需要手动配置网络。

另外还提供了回调机制，可以注册 HTTP 请求前后和错误处理的钩子，方便在复杂场景里做日志记录或自动重试。

4、 适合谁用

• 做 iOS 自动化测试的工程师，需要编写 UI 测试脚本
• 做 iOS 设备远程管理或云真机平台的技术团队
• 需要用 Python 批量操控 iPhone 做数据采集或流程自动化的开发者

这个项目把 WDA 的底层接口包成了直观的 Python API，上手门槛降了不少。iOS 自动化本身环境配置比较麻烦，这个库至少让写脚本这件事变简单了。

这个项目把 WDA 的底层接口包成了直观的 Python API，上手门槛降了不少。iOS 自动化本身环境配置比较麻烦，这个库至少让写脚本这件事变简单了。