Appium iOS UI自动化之环境搭建（Xcode15，iOS17，真机）_appium ios17

---

前言

盼了好几年，公司终于让我开始着手UI自动化的事情了，然后配了两部iOS17.2.1的手机。然后我发现光是搭建环境这一步，就变得跟几年前书里学习的内容有点不一样了。所以把这段时间搭环境及如何实现用例的事情都写一下，希望能帮助到其他人。

---

一、准备Xcode

因为配备的iOS17.2.1的设备，所以必须使用xcode15及以上版本才能在设备中安装WebDriverAgent，而电脑系统必须在14及以上才能安装xcode15。而我的电脑是2017年产的，不支持升级到14的系统，所以目前Mac系统是13.6.6。我特地查询了一下支持xcode版本的mac系统：

可以看到macOS13.6.6，最新可以安装Xcode15.2的版本，于是下载，安装。
下载链接中的xcode是xip结尾的压缩包，用xip命令解压到Applications文件夹里，就可以直接使用了。xip命令可以参照这篇文章 https://www.jianshu.com/p/0b372a4e18f2。

二、安装Appium

1.Appium1和Appium2

跟Appium1.x版本不一样的是，Appium2是用命令行的方式启动，所以如果想要查看元素，他们提供了一个专门的工具appium-inspector。
如果mac系统里安装的nodejs的话，那么执行命令即可安装Appium：

npm i --location=global appium
1

安装完毕之后输入命令启动Appium：

appium
1

如果看到以上信息，就说明Appium是安装成功了，截图中显示的plugins这些目前暂时是没有的，后续的文章会继续讲解怎么安装，以及有什么用。

2.安装appium-doctor

然后为了保证Appium的各种依赖也是齐全的，需要安装Appium doctor来检查依赖等：

npm install @appium/doctor --location=global
1

安装完毕之后执行doctor检查下安装情况：

appium-doctor --ios
1

只要基本需要的依赖安装好了，那么就可以使用Appium了，如果需要其他什么特殊功能，后面再来安装对应的依赖和插件就好。

3.安装Appium的driver

据说以前的版本，Appium是自带了driver的，但是2.5版本，要使用什么driver就必须自己安装，比如我们要操作iOS，需要安装XCUITest的driver：

appium driver install xcuitest
1

XCTest和XCUITest是苹果系统自己的UITest框架，Appium的原理是通过XCUITest的driver去驱动XCUITest，以实现自动化的目的，以后有空可以聊聊iOS的XCUITest如何写。

4.安装Appium-inspector

为了可以查看设备中元素，需要安装Appium-inspector，点击这里进入官网下载。
安装完毕之后打开inspector，可以发现和以前Appium1.X版本的样子差不多：

提示：安装中如何报错提示开发者没有被信任之类的，需要在mac的设置中去设置

5.安装WebDriverAgent的前期准备

市面上搜索WebDriverAgent，会有很多各种资料，最终，目前Appium2.5版本的情况是，Appium中自带了这个WebDriverAgent的源码，且启动appium-inspector时，会自动使用Appium中的WebDriverAgent，所以不需要单独去下载WebDriveragent。
在保证安装了xcode和XCUITest的driver的情况下，执行命令：

appium driver run xcuitest open-wda
1

xcode会自动启动，且同时打开Appium里WebDriverAgent的源码。

第一步：把WebDriverAgent的bundleId改成你自己的

如截图里的选中样子，最终⑥就是需要你修改的bundleId，默认是com.facebook.WebDirverAgentRunner，但是必须要改掉，所以我改成了我的域名。

第二步：给WebDriveragent签名

把上图的④，切换到标签“Signing and Capacities”：

勾选“Automatically manage signing”，同时在Team那个地方选择自己的个人免费账号的Personal Team。

第三步：给WebDriverAgentLib也签名

说实话这步我不晓得是不是多余的，反正看过很多文章，有的要，有的不要，我懒得去纠结了，安排。
将第二步图中的①，切换到第一个WebDriverAgentLib，然后重复同样的签名操作，那么签名就完成了。

因为这个WebDriverAgent是安装到设备中的，所以我们只签名iOS相关的，macOS，或者tvOS这些是多余的，不用管。

第四步：被测手机开启开发者模式

手机连接到mac电脑，进入设置页，拉到列表最底部，看到“开发者”，点击进入，勾选选项“启用UI自动化”，然后会重启设备。

6.安装WebDriverAgent

做好了前期准备工作，就可以给真实设备安装WebDriverAgent了，后文称wda。

第一种，带自动签名的安装

首先我们需要找到Appium中wda的路径，然后cd到那个路径下去安装，要找到这个路径，执行命令：

echo "$(dirname "$(find "$HOME/.appium" -name WebDriverAgent.xcodeproj)")"
1

通常返回的路径是这样的：
/Users/YOUR_NAME/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent

然后我们cd到这个目录下，先执行以下命令，用来生成些必要的应用文件：

mkdir -p Resources/WebDriverAgent.bundle
1

然后执行以下命令，以下命令是用xcode的命令行方式安装wda，id后的“000000000-000000000000”是你设备的udid。

xcodebuild build-for-testing test-without-building -allowProvisioningUpdates -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination id=000000000-000000000000
1

udid怎么查？打开xcode，选择Window->Devices and Simulators，打开的页面中，设备的identifer就是了。

如果没有意外，安装成功之后还是会报错，这是正常的，手机系统会提示你安装的应用需要信任开发者，这时需要打开手机里的‘设置->通用->VPN与设备管理’，然后在该页面点击信任开发者。

如果wda被卸载，然后重装，手机系统会重新提示需要手动信任开发者。如果不想再看到这个提示，解决的方案是，用xcode给设备安装wda源码里的IntegrationApp。这样一来，设备里一直信任这个开发者的IntegrationApp，安装该开发者其他应用就不会再弹出需要信任的提示。需要注意的是，免费账号最多只能在同一设备里安装3个App。

第二种，使用预安装的wda

刚开始我一直使用的第一种方案，但是每次执行用例的时候，设备都会重新安装wda，这我就忍了。但是执行一段时间之后，就再也连接不上了，要重启电脑重启设备等一系列操作浪费一两个小时，才莫名其妙又可以连接了。于是我专门申请了三天时间来看究竟。最终，大概模糊明白是怎么回事了，然后我的方案是，使用预安装的wda，每次执行不重新安装。

对于执行用例时，如何使用wda，其实Appium在XCUITest driver文档里写得很清楚，有三种方案，一种是使用已经安装好的wda，第二种是使用预编译好的wda，执行用例时直接用编译文件安装，另一种是直接第三方启动wda，执行用例时使用已经启动好的wda。而这些可以在这里看到。

页面目录里明确写了这三种方案，实际上，对于我现在的版本来说，一个都使用不了。使用预安装的文档里说，预安装的方案只支持iOS16及以上，但是目前仍旧有bug。
最终我在这个帖子里的评论里找到了临时解决方案，而这也是我决定写博客的原因：

翻译以上内容，大致步骤就是：

第一，在xcode中的DerivedData文件夹中，删除掉Frameworks文件夹中以XC开头的文件。

首先我们要找到这个文件夹在哪里，在截图中路径出现了一个DerivedData，这是xcode构建相关的文件夹，我们可以在xcode的设置里，点击location找到这个文件夹的路径：

路径找到了，那么要操作的文件夹也就好找了：

在找到Debug-iphoneos这一层，IntegrationApp是个不可点的图标，这时需要选中文件，右键，选择Show Package Contents才能进入下一层级：

然后把Framework文件夹里所有XC开头的文件都删除，下图中红框框中的：

第二，用xcrun命令安装这个app（其实就是wda）

xcrun devicectl device install app --device  00000000-00000000 /Users/YOUR_NAME/Library/Developer/Xcode/DerivedData/WebDriverAgent-XXXXXXXXXXXXXXXX/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app
1

以上命令，00000000-00000000为设备udid，然后带上你自己mac中wda.app的路径，然后进行安装。

截图中的3、4、5步，我们都可以不用管，因为3、4步我们已经处理好了，第五步，我们不用他这种启动方式。

完成以后，我们就可以使用Appium-inspector来试一试了。

7.设置desired_capabilities，启动Appium-inspector

打开Appium-inspector，然后输入一下desired_capabilities:
{
“platformName”: “iOS”,
“appium:platformVersion”: “17.2.1”,
“appium:automationName”: “XCUITest”,
“appium:udid”: “000000000-000000000”,
“appium:bundleId”: “com.baidu.example”,
“appium:xcodeSigningId”: “iPhone Developer”,
“appium:showXcodeLog”: “true”,
“appium:clearSystemFiles”: “true”,
“appium:autoAcceptAlerts”: “true”,
“appium:noReset”: “true”,
“appium:wdaLaunchTimeout”: “600000”,
“appium:usePreinstalledWDA”: “true”,
“appium:updatedWDABundleId”: “com.abrocks.WebDriverAgentRunner”,
“appium:updatedWDABundleIdSuffix”: “.xctrunner”
}

platformVersion可以只输入17.2，因为执行的时候会自动处理掉第三位。
automationName是你需要用到的Appium driver，iOS用的XCUITest。
udid是前面提到的identifier
bundleId是你需要测试的APP的bundleId，如果不知道，可以使用github上libimobiledevice工具，使用命令idevice_id -l来查看设备中所有APP的bundleId，libimobiledevice工具可以使用brew安装，不用make编辑那么麻烦。
xcodeSigningId这个不知道，随便写的。
showXcodeLog这是执行用例期间，xcode信息是否需要显示出来，debug的话，需要true。
clearSystemFiles不晓得是啥，感觉可以设置成true
autoAcceptAlerts说是设置成true可以自动允许权限弹窗，比如location、录音、相册等。
noReset启动时不需要清除原APP资源，保留登录信息等
wdaLaunchTimeout设置连接wda的时间，如果设备的wda超过这个时间无反馈，Appium会关闭session。
usePreinstalledWDA是否使用已经安装的wda，true，因为前面已经安装好了
updatedWDABundleId指明wda的bundleId，这个参数如果不设置，系统会默认使用com.facebook.WebDriverAgentRunner，导致老是报错说找不到wda，所以必须指定。
updatedWDABundleIdSuffix启动时，只要是wda，Appium会自动在bundleId后面加一个.xctrunner，设置或不设置都会加，这里写出来指明，是为了方便理解。

然后就可以在命令行中输入appium，启动Appium服务器：

appium
1

然后inspector点击start session连接手机了。

在Appium2.x版本中，remote path 应该只填写/，而不是/wd/hub

参考资料

https://appium.github.io/appium-xcuitest-driver/latest/reference/capabilities/
https://appium.github.io/appium-xcuitest-driver/latest/guides/run-preinstalled-wda/
https://discuss.appium.io/t/unable-to-launch-ios-webdriver-agent-manually-on-ios-17-x-devices/41492
https://medium.com/@yashwant-das/comprehensive-guide-to-manually-configuring-appium-2-1-for-ios-17-x-on-real-devices-7f2264717d76