iOS自动化测试：绕过Xcode编译，使用预装WDA实现Appium真机连接

1. 项目概述为什么我们需要绕开Xcode编译如果你是一名iOS自动化测试工程师或者正在尝试用Appium连接iPhone真机进行测试那么“WDA环境搭建”这几个字大概率是你职业生涯中绕不开的噩梦。传统的流程需要你打开Xcode配置开发者证书、Provisioning Profile然后编译WebDriverAgentWDA这个核心组件。这个过程对于不熟悉iOS开发的测试同学来说堪称玄学——证书报错、签名失败、编译卡住随便一个坑都能让你折腾一整天。这个教程要解决的就是这个核心痛点。我们不再依赖Xcode的编译流程而是利用Appium Desktop和Appium 2.0的新特性通过usePreinstalledWDA这个能力直接安装并启动一个预先准备好的WDA应用包。这就像是你不再需要从面粉开始做面包而是直接去面包店买一个现成的。整个过程你甚至不需要打开Xcode。这对于需要在多台设备、多个开发者账号下快速部署测试环境的团队来说效率提升是颠覆性的。2. 核心原理与方案选型usePreinstalledWDA是如何工作的要理解这个“一键搞定”的方案我们必须先拆解Appium连接iOS真机的传统路径和新的捷径。2.1 传统路径Xcode编译的“黑盒”过程传统上当你启动一个针对iOS真机的Appium会话时背后发生了这些事情启动Appium服务器。Appium XCUITest驱动接收到你的会话能力Capabilities。驱动调用xcodebuild命令在你的Mac上实时编译WebDriverAgent项目。编译产物一个.app包被签名并安装到目标iPhone上。Appium在设备上启动这个WDA应用它内部运行着一个HTTP服务器。后续所有的自动化指令如点击、滑动都通过这个HTTP服务器转发给iOS系统的XCUITest框架执行。问题所在第3步的编译和第4步的签名严重依赖本地的Xcode环境、证书配置和项目状态。任何环节出错如证书过期、描述文件不匹配、项目路径有空格都会导致整个流程失败且错误信息往往晦涩难懂。2.2 新方案捷径预安装与直接启动Appium 2.0的XCUITest驱动引入了一个关键能力appium:usePreinstalledWDA。当这个能力设置为true时流程变为前提你已经通过某种方式教程的核心将一个已经签名好的WebDriverAgentRunner-Runner.app安装到了目标设备上。启动Appium会话时驱动会检查设备上是否已存在符合要求的WDA应用。如果存在则直接通过系统命令如iOS 17上的xcrun devicectl启动这个已安装的应用进程完全跳过xcodebuild编译步骤。优势对比对比项传统Xcode编译方案usePreinstalledWDA预安装方案环境依赖重度依赖Xcode、证书、项目源码仅需最终生成的.app包和安装工具启动速度慢每次需编译极快直接启动稳定性易受编译环境和签名影响高包是预先验证好的设备批量部署困难每台设备需单独编译签名容易同一签名包可安装到多台设备跨机器共享困难需复制整个Xcode项目和环境简单只需分享一个.app文件注意此方案对iOS版本有要求。根据Appium官方文档完整支持需要iOS/tvOS 17以及WebDriverAgent v13对应XCUITest驱动v11.5.0。对于更早的系统虽然也可以通过webDriverAgentUrl连接已运行的WDA服务但预安装启动的方式可能受限。3. 保姆级实操四步构建“开箱即用”的WDA环境接下来我们抛开理论直接上手。我们的目标是在不打开Xcode的情况下生成一个通用的、可重复使用的WDA应用包并将其部署到你的iPhone上。3.1 第一步前期准备与环境检查工欲善其事必先利其器。请确保你的工作环境满足以下条件硬件与系统Mac电脑这是必须的因为涉及iOS应用的签名和安装。iPhone真机系统版本建议在iOS 17及以上以获得最佳兼容性。USB数据线用于连接手机和Mac。软件安装Xcode是的我们虽然不用它编译但需要它的命令行工具和部分框架。请从Mac App Store安装最新稳定版Xcode并打开一次完成初始化和同意许可协议。HomebrewmacOS的包管理器用于安装其他工具。如果未安装打开终端执行/bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)Appium Desktop从 Appium官网 下载并安装。这是我们可视化管理会话的客户端。Appium Server (CLI)我们主要使用命令行版本。通过npm安装确保已安装Node.jsnpm install -g appium第三方安装工具我们将使用一个名为tidevice的国产优秀工具它比苹果原生工具更强大。通过brew安装brew install tidevice开发者账号配置关键 这是整个流程中最容易出错的一环。你需要一个有效的Apple开发者账号个人或公司。在 Apple开发者网站 登录。为你的设备创建一个Provisioning Profile描述文件。选择“iOS App Development”类型。在创建时确保勾选了你的iPhone设备并关联了一个有效的“iOS Development”证书。下载并双击这个.mobileprovision文件它会自动导入到你的钥匙串Keychain和Xcode中。实操心得很多人卡在证书上。一个检查方法是用USB连接iPhone后打开Xcode进入Window - Devices and Simulators如果能看到你的设备并且旁边没有警告图标通常说明证书和描述文件基本没问题。tidevice工具对证书的容错性比Xcode好一些但有效的开发者身份仍是基础。3.2 第二步获取“干净”的WDA应用包我们的目标不是从源码编译而是获取一个“官方预制”的、或者自己预先编译好的WDA包。这里提供两种最可靠的方法。方法A使用Appium驱动命令直接获取推荐Appium 2.0的驱动管理器非常强大。我们可以用它来搭建WDA项目并编译出我们需要的包。安装XCUITest驱动如果尚未安装appium driver install xcuitest使用驱动命令打开并编译WDA 执行以下命令这会让驱动自动处理WDA项目的克隆和编译。appium driver run xcuitest open-wda这个命令可能会自动打开Xcode并加载WDA项目。我们的目的不是在这里编译而是让驱动帮我们准备好项目路径。更直接的方法是我们可以定位到驱动缓存的WDA项目。定位编译产物 实际上更高效的方式是直接使用驱动来构建。但为了完全脱离Xcode的UI我们可以用命令行编译。首先找到WDA项目路径通常位于Appium的缓存目录下例如~/.appium/appium-xcuitest-driver/node_modules/appium-webdriveragent。 进入该目录然后使用xcodebuild命令为你的真机进行编译cd ~/.appium/appium-xcuitest-driver/node_modules/appium-webdriveragent xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination generic/platformiOS -configuration Debug build-for-testing关键参数解释-scheme WebDriverAgentRunner指定编译的是Runner scheme这是能在设备上独立运行的应用。-destination generic/platformiOS指定为通用iOS设备编译而不是某个特定模拟器。-configuration Debug编译Debug版本便于调试。build-for-testing生成用于测试的.xctestrun包和相关产物。找到生成的.app包 编译成功后产物会在派生数据DerivedData目录中。这个路径比较长且带有随机字符串一个典型的路径是~/Library/Developer/Xcode/DerivedData/WebDriverAgent-一串随机字符/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app你可以使用find命令查找find ~/Library/Developer/Xcode/DerivedData -name WebDriverAgentRunner-Runner.app -type d 2/dev/null找到这个.app目录将其复制到一个你容易访问的位置例如~/Desktop/WDA_Prebuilt/。这个就是我们的核心资产——预构建的WDA应用包。方法B从官方Release页面下载适用于高级用户WebDriverAgent项目在GitHub的Release页面有时会提供预编译的.ipa文件。你可以去 appium/WebDriverAgent 页面查看。但通常这些包未签名你需要自己重签名过程更复杂。对于追求稳定和可控的我们方法A是首选。3.3 第三步为iOS 17设备优化WDA包关键步骤如果你针对的是iOS 17或更高版本的设备有一个至关重要的优化步骤否则WDA进程可能会在启动时崩溃。这是因为iOS 17的测试管理服务testmanagerd有变更WDA应用不应该再包含本地的XCTest框架副本而应该使用设备系统自带的。你需要移除WDA应用包内嵌的XCTest框架打开终端进入你上一步保存的WebDriverAgentRunner-Runner.app包内部。cd ~/Desktop/WDA_Prebuilt/WebDriverAgentRunner-Runner.app查看并删除Frameworks目录下特定的框架文件# 查看有哪些XCTest相关的框架 ls -la Frameworks/ # 通常会看到 XC*.framework 这样的文件例如 XCTest.framework, XCUnit.framework等 # 安全地删除它们 rm -rf Frameworks/XC*.framework # 为了进一步减小包体积非必须但推荐还可以删除另外两个非必需的大文件 rm -rf Frameworks/Testing.framework Frameworks/libXCTestSwiftSupport.dylib执行完这些操作后你的WDA应用包体积会从原来的10MB左右减小到3MB以下并且完全兼容iOS 17的直接启动方式。注意事项这个步骤是iOS 17真机预安装方案成功的关键。很多人在这一步忽略导致Appium日志中WDA进程一闪而过就崩溃。务必执行。3.4 第四步使用tidevice签名并安装到真机现在我们有了一个“干净”且优化过的WDA应用包.app目录。接下来需要将它签名并安装到iPhone上。我们将使用tidevice它比Xcode和ios-deploy更简洁强大。连接设备并查看UDIDtidevice list这会输出已连接USB的iPhone信息复制设备的UDID一串40位的十六进制字符串。使用tidevice安装并签名tidevice的install命令可以自动处理签名使用你钥匙串中有效的开发者证书。tidevice --udid 你的设备UDID install ~/Desktop/WDA_Prebuilt/WebDriverAgentRunner-Runner.app例如tidevice --udid 00008101001a101de11e1e1e1e1e1e1e1e1e1e1e install ~/Desktop/WDA_Prebuilt/WebDriverAgentRunner-Runner.app命令执行后tidevice会自动选择合适的证书进行签名并将应用安装到设备上。你可以在iPhone上看到一个新的、名为“WebDriverAgentRunner-Runner”的应用图标可能位于资源库中主屏幕不可见。验证安装 查看设备上已安装的应用列表确认WDA存在tidevice --udid 你的设备UDID applist在列表中寻找类似com.apple.test.WebDriverAgentRunner-Runner或你自定义的Bundle ID的应用。4. 配置Appium Desktop与启动自动化会话环境部署完毕现在进入“一键搞定”的享受阶段。4.1 启动Appium Server你可以使用Appium Desktop内置的服务器也可以使用命令行。为了更清晰地看到日志我推荐使用命令行启动一个独立的Appium服务器appium --allow-insecureadb_shell --base-path /wd/hub--allow-insecure允许一些非标准的安全特性确保兼容。--base-path /wd/hub设置基础路径这是Appium客户端的默认期望路径。保持这个终端窗口运行不要关闭。4.2 配置Appium Desktop会话能力Capabilities打开Appium Desktop点击“Start Server”来启动其内置服务器或者直接连接我们上一步启动的localhost:4723。然后点击“Create New Session”。在弹出的“Desired Capabilities”配置窗口中我们需要填写一组关键参数。点击“”号添加以下每一项参数名参数值说明platformNameiOS指定操作系统平台appium:automationNameXCUITest指定自动化引擎appium:udid你的设备UDID替换为tidevice list查到的UDIDappium:usePreinstalledWDAtrue核心告诉Appium使用已安装的WDAappium:updatedWDABundleIdcom.apple.test.WebDriverAgentRunner已安装WDA应用的Bundle ID。注意这个ID需要与你实际安装的包ID一致。如果你用tidevice默认安装通常是这个。appium:updatedWDABundleIdSuffix.xctrunnerBundle ID的后缀。如果安装的包ID已经是完整格式如com.xxx.WebDriverAgentRunner.xctrunner这里可以留空或填写.xctrunner。如果安装的包ID没有后缀如io.appium.wda则此项必须设置为空字符串。appium:prebuiltWDAPath~/Desktop/WDA_Prebuilt/WebDriverAgentRunner-Runner.app可选但推荐。提供本地.app包的路径。如果提供Appium会在每次会话前检查并重新安装此包确保设备上的WDA永远是最新的。一个完整的JSON格式能力集看起来像这样{ platformName: iOS, appium:automationName: XCUITest, appium:udid: 00008101001a101de11e1e1e1e1e1e1e1e1e1e1e, appium:usePreinstalledWDA: true, appium:updatedWDABundleId: com.apple.test.WebDriverAgentRunner, appium:updatedWDABundleIdSuffix: .xctrunner, appium:prebuiltWDAPath: /Users/你的用户名/Desktop/WDA_Prebuilt/WebDriverAgentRunner-Runner.app }4.3 启动会话与验证配置完成后点击“Start Session”。如果一切顺利你将看到以下迹象Appium Desktop会启动一个Inspector会话窗口。在Appium Server的日志中你不会看到大段的xcodebuild编译输出取而代之的是类似[XCUITest] Using pre-installed WDA at bundle id com.apple.test.WebDriverAgentRunner.xctrunner的日志。日志会显示通过devicectliOS 17或类似工具直接启动进程。几秒到十几秒后Inspector窗口成功加载出你iPhone的屏幕截图和UI层级树。恭喜这意味着你已经完全绕过了Xcode编译成功通过预安装的WDA启动了自动化会话。整个过程的核心耗时就是网络通信和设备启动应用的时间比传统编译方式快了几个数量级。5. 避坑指南与常见问题排查即使按照教程一步步操作也可能遇到问题。这里记录了我实践中遇到的高频坑点。5.1 证书与签名问题问题现象tidevice install失败提示Installation failed: ... 0xe8008016 (The identity used to sign the executable is no longer valid.)。排查思路证书过期前往钥匙串访问Keychain Access查看“我的证书”中你的开发者证书是否过期。过期需在Apple开发者网站重新生成并下载。描述文件不匹配确保你导入的描述文件.mobileprovision包含了当前设备的UDID并且关联的证书是有效的。可以在Xcode的Accounts - Manage Certificates...或苹果开发者网站检查。tidevice未找到证书tidevice默认使用钥匙串中“登录”钥匙串的证书。确保你的证书在“登录”分组下而不是“系统”下。可以尝试用security find-identity -v -p codesigning命令查看当前可用的签名身份。5.2 WDA启动后立刻崩溃问题现象Appium日志显示WDA进程被启动但马上退出Inspector无法连接日志可能出现Process exited with code 1或signal: Killed。排查思路iOS 17框架未移除这是最常见的原因务必回头执行3.3节的步骤删除WDA应用包内的Frameworks/XC*.framework。Bundle ID不匹配检查appium:updatedWDABundleId和appium:updatedWDABundleIdSuffix的设置是否与设备上实际安装的WDA应用的Bundle ID完全一致。可以使用tidevice applist --json查看已安装应用的详细Bundle ID。开发者模式未开启首次在真机上运行开发者应用需要在 iPhone 的设置 - 隐私与安全性 - 开发者模式中打开“开发者模式”并重启手机。5.3 Appium无法找到预安装的WDA问题现象日志提示Could not find pre-installed WDA with bundle id。排查思路确认WDA已安装用tidevice applist仔细核对Bundle ID。检查Capability拼写usePreinstalledWDA是true布尔值不是字符串true。updatedWDABundleId和updatedWDABundleIdSuffix的前缀是appium:。尝试提供prebuiltWDAPath即使WDA已安装也提供appium:prebuiltWDAPath路径。这会让Appium先尝试用这个路径的包去安装覆盖设备上的旧版本保证一致性。5.4 设备连接与通信问题问题现象tidevice list找不到设备或者Appium连接超时。排查思路信任此电脑iPhone连接Mac时屏幕上会弹出“信任此电脑吗”的提示必须点击“信任”。USB连接不稳定尝试更换数据线或USB端口。使用原装数据线最佳。端口占用确保没有其他进程占用4723端口。可以lsof -i :4723查看并结束相关进程。防火墙或安全软件临时关闭macOS的防火墙或任何可能拦截网络连接的安全软件。5.5 关于appium:prebuiltWDAPath的特别说明这个能力非常有用但它意味着每次启动新会话时Appium都会尝试用你提供的本地.app包重新安装WDA。这保证了版本统一但也会增加一点点会话启动时间安装时间。如果你的WDA包非常稳定且不需要频繁更新你可以选择不设置这个参数让Appium直接启动设备上已存在的WDA速度最快。我个人在持续集成CI环境中会使用prebuiltWDAPath确保每次测试都是从绝对干净的状态开始。在本地日常调试时则倾向于不设置以获得最快的启动速度。