本文档将指导完成 iOS 自动化的环境配置。分为 电脑端配置 和 手机端配置 两部分。
🖥️ 电脑端配置 (Mac)
必须安装以下核心工具：
* Appium Server: appium
* Appium Doctor: appium-doctor (环境诊断工具)
* XCUITest Driver: appium-xcuitest-driver (iOS 驱动)
可能还需要手动安装的依赖：
- Xcode (必须)
* 请从 Mac App Store 下载并安装 Xcode。
* 安装完成后，运行一次 Xcode 并同意许可协议。
* 在终端执行：xcode-select --install 安装命令行工具。
- Carthage (可选，但推荐)
* 用于管理 WebDriverAgent 的依赖。
* 安装命令：brew install carthage
- libimobiledevice (真机通信必须)
* 用于与 iOS 设备通信。
* 安装命令：brew install libimobiledevice ios-deploy
🔍 环境检查
您可以在终端运行以下命令来检查环境是否就绪：
appium-doctor --ios
请根据输出的提示修复所有标记为 x 的项。
📱 手机端配置 (iPhone/iPad)
- 开启开发者模式
* 进入 设置 (Settings) -> 隐私与安全性 (Privacy & Security)。
* 滚动到底部，找到 开发者模式 (Developer Mode) 并开启。
* 根据提示重启设备并确认开启。
- 连接电脑与信任
* 使用数据线将 iOS 设备连接到 Mac。
* 手机上弹出"要信任此电脑吗？"，点击 信任 (Trust) 并输入锁屏密码。
- 安装与签名 WebDriverAgent (最关键步骤)
Appium 依赖 WebDriverAgent (WDA) 来控制 iOS 设备。您需要使用 Xcode 重新签名并安装它。
步骤如下：
- 找到 WDA 项目路径：
通常位于：~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
或者：~/.appium/node_modules/appium-xcuitest-driver/node_modules/webdriveragent
-
如果找不到，可以在终端运行 find ~/.appium -name "WebDriverAgent.xcodeproj" 查找。
-
打开项目：
双击 WebDriverAgent.xcodeproj 文件，使用 Xcode 打开。
- 配置签名 (Signing)：
* 在 Xcode 左侧导航栏点击顶部的 WebDriverAgent 图标。
* 在右侧选择 Targets 列表中的 WebDriverAgentRunner。
* 点击顶部的 Signing & Capabilities 选项卡。
* 勾选 Automatically manage signing。
* 在 Team 下拉框中，选择您的 Apple ID (如果没有，点击 Add an Account... 登录)。
* Bundle Identifier: 将默认的 ID 修改为唯一的 ID（例如 com.yourname.WebDriverAgentRunner），直到不再报错。
- 编译安装：
* 确保您的 iOS 设备已连接并被 Xcode 识别（顶部设备栏选择您的手机）。
* 菜单栏点击 Product -> Test (或快捷键 Cmd + U)。
* Xcode 会开始编译并尝试将 WDA 安装到您的手机上。
- 手机端信任证书：
* 如果是首次安装，手机上可能会提示"不受信任的开发者"。
* 进入手机 设置 -> 通用 -> VPN与设备管理。
* 找到您的 Apple ID 对应的开发者应用，点击 信任。
- 验证运行：
* 再次在 Xcode 中按 Cmd + U。
* 观察 Xcode底部的控制台 (Console) 输出。
* 如果看到类似 ServerURLHere->http://192.168.x.x:8100<-ServerURLHere 的日志，说明 WDA 启动成功！
🚀 开始使用
完成上述步骤后：
-
保持手机连接电脑，且 WDA 处于运行状态（或 Appium 会自动拉起它）。
-
在本项目中，确保启动了 turbo-server 和 desktop-atom-agent。
-
在设备管理页面添加 iOS 设备，IP 填写 localhost，端口填写 8100 (如果使用了端口转发) 或 Appium 默认端口。
-
本项目已配置使用 Appium 自动管理 WDA，只要您正确配置了环境，代码中的 webdriverio 会自动连接并控制设备。