Appium XCUITest Driver 真机调试配置步骤

Created
Mar 15, 2021 5:07 AM

安装依赖

从 Appium 1.15.0 版本后,Appium 通过 appium-ios-device 与设备进行通信,不再需要安装其他依赖。

XCUITest driver 会在设备上安装一个叫做 WebDriverAgent-Runner 的程序,并控制被测 App。

尽管说起来很简单,但是在测试时可能会遇到签名和分发的各种问题,让人头疼。

当然,首先你要确保你的 Xcode 能够正常识别你的设备。你可以在 Window - Devices and Simulators 里检查设备是否连接上并被 Xcode 识别。

关于 XCUITest Driver 配置中需要的参数,可以参考 appium-xcuitest-driver.

基本配置

通过填写一些必要的配置文件,Appium XCUITest 即可自动帮您完成其他工作,快捷的开始测试。 有两种方法:

  • 使用 xcodeOrgIdxcodeSigningId 和 desired capabilities:
    {
      "xcodeOrgId": "<Team ID>",
      "xcodeSigningId": "iPhone Developer"
    }

  • 在系统中创建一个 .xcconfig 然后添加如下信息:
    DEVELOPMENT_TEAM = <Team ID>
    CODE_SIGN_IDENTITY = iPhone Developer

大体上,就是需要一个 Team ID,这是一个苹果分配给你的 10 位数字和字母组合的字段。你可以在 Apple Developer 官方找到。

登录 developer.apple.com/account,然后点击左侧的 Membership,就能看到你的 Team ID 了。 或者你可以在钥匙串 App 中通过搜索 Apple Development,双击找到的证书。

image

这个 组织单位 就是需要的 Team ID。

image

需要注意的是,上面说的两种方法是互斥的,只需要选择一种方法即可。

配置好后,就可以添加设备的 udid,开始测试了。

如果开始测试时出现 info XCUITest xcodebuild exited with code '65' and signal 'null' 错误,表示配置出现问题(这往往是因为你的 Apple ID 没有参加付费的 Apple Developer 计划)。可以参考后面的 手动测试。

如果 WebDriverAgentRunner 已经成功安装到了设备上,但是 Appium 出现了类似这样的 log:

2017-01-24 09:02:18.358 xcodebuild[30385:339674] Error Domain=com.apple.platform.iphoneos Code=-12 "Unable to launch com.apple.test.WebDriverAgentRunner-Runner" UserInfo={NSLocalizedDescription=Unable to launch com.apple.test.WebDriverAgentRunner-Runner, NSUnderlyingError=0x7fa839cadc60 {Error Domain=DTXMessage Code=1 "(null)" UserInfo={DTXExceptionKey=The operation couldn’t be completed. Unable to launch com.apple.test.WebDriverAgentRunner-Runner because it has an invalid code signature, inadequate entitlements or its profile has not been explicitly trusted by the user. : Failed to launch process with bundle identifier 'com.apple.test.WebDriverAgentRunner-Runner'}}}
2017-01-24 09:02:18.358 xcodebuild[30385:339674] Error Domain=IDETestOperationsObserverErrorDomain Code=5 "Early unexpected exit, operation never finished bootstrapping - no restart will be attempted" UserInfo={NSLocalizedDescription=Early unexpected exit, operation never finished bootstrapping - no restart will be attempted}

Testing failed:
	Test target WebDriverAgentRunner encountered an error (Early unexpected exit, operation never finished bootstrapping - no restart will be attempted)

这需要手动去信任开发者。实际上,如果你尝试手动去安装 WebDriverAgentRunner ,则会出现类似下面的提示:

image

在设置 - 通用 - 描述文件与设备管理 里信任开发者,允许 WebDriverAgentRunner 运行(参考 Apple documentation for more information)。

手动配置

按照上面的方法配置后,在启动测试时往往还是会遇到各种各样的问题。其中有很大一部分是因为你没有订阅付费的 Apple Developer 计划,这样就可能没法正常创建通配符分发配置文件(wildcard provisioning profile),同时由于免费订阅计划的证书数量限制,在测试这种需要多个证书的场景下也会出现问题。

创建 provisioning profile

首先,你需要创建一个 provisioning profile,最简单的方法就是创建一个空项目,然后确保能在机器上运行。或者你可以使用 Apple 官方提供的 UIKitCatalog,这个 App 对于调试 Appium 开发也很方便。

  1. 在下面这个链接里下载项目文件
  2. 编译并运行
  3. image

手动 Build WebDriverAgent

💡

如果使用免费开发者账号,由于证书7天过期,所以这一步的部分步骤每周要做一次,具体看下面的步骤

每周要做
  1. 打开 Window - Devices and Simulators
  2. image
  3. 把上周调试用的三个 app 在这里全部删掉
  4. image
  5. 打开 DriverAgentRunner 项目,并重新执行下面的命令。然后重新信任开发者
  6. xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test -allowProvisioningUpdates
  1. 找到项目路径,我这边是在这里 Applications/Appium.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent
  2. 进入该目录,分别执行下面两条命令更新依赖
  3. mkdir -p Resources/WebDriverAgent.bundle 
    ./Scripts/bootstrap.sh -d
    
  4. 双击项目文件打开项目
  5. image
  6. 更改 WebDriverAgentLib 的包名,随便起,改个不一样的
  7. image

    然后选择一个签名的 Team

    image
  8. 类似的,更改 DriverAgentRunner 的包名,随便起,改个不一样的
  9. image

    然后选择一个签名的 Team

    image
  10. Product - Build
  11. image

    显示 Build Success 即可

如果出现错误,就把IntegrationApp 也进行相同的操作

测试是否正常

  1. 插上手机后,在 Xcode 里选择目标设备
  2. image
  3. 然后在终端执行下面的命令,注意替换 udid 为手机的
  4. xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test
  5. 如果出现类似下面的错误,执行
  6. xcodebuild -project WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -destination 'id=<udid>' test -allowProvisioningUpdates
    image
  7. 如果出现下面的错误,WebDriverAgent 可能已经安装到手机上了,但是开发者尚未被信任
  8. image

    找到 App,点开,出现如下提示

    image

    在设置 - 通用 - 描述文件与设备管理 里信任开发者

  9. 手机上安装了 WebDriverAgentRunner 即可,测试 App 也应该能自动打开了。
    1. image

      此时,控制台里可能有类似这样的log

      Test Suite 'All tests' started at 2017-01-23 15:49:12.585
      Test Suite 'WebDriverAgentRunner.xctest' started at 2017-01-23 15:49:12.586
      Test Suite 'UITestingUITests' started at 2017-01-23 15:49:12.587
      Test Case '-[UITestingUITests testRunner]' started.
      	t =     0.00s     Start Test at 2017-01-23 15:49:12.588
      	t =     0.00s     Set Up
      
    2. 为了确认是否成功,你还可以通过执行下面的命令来检查手机上 WebDriverAgent server 的状态(注意:测试设备和电脑必须在同一个局域网下,要获取当前设备 IP 地址,可以在 设置 - Wi-Fi 里找到)
    3. export DEVICE_URL='http://<device IP>:8100'
      export JSON_HEADER='-H "Content-Type: application/json;charset=UTF-8, accept: application/json"'
      curl -X GET $JSON_HEADER $DEVICE_URL/status
      

      你应该能获得大概这样的log

          {
            "value" : {
              "state" : "success",
              "os" : {
                "name" : "iOS",
                "version" : "10.2"
              },
              "ios" : {
                "simulatorVersion" : "10.2",
                "ip" : "192.168.0.7"
              },
              "build" : {
                "time" : "Jan 23 2017 14:59:57"
              }
            },
            "sessionId" : "8951A6DD-F3AD-410E-A5DB-D042F42F68A7",
            "status" : 0
          }
      

被测 App 的配置

不仅 WebDriverAgent 需要仔细配置以确保能够正确安装在手机上,

Configuring the app under test

Not only does WebDriverAgent need to be configured to run on your device, but your app must also be able to run on your device. The central requirements are the same: to have a build of your app (an .ipa file) signed with a development provisioning profile. A good overview of the process can be found here and here.

In a little more detail, to get started on a real device, you will need the following:

  • An Apple Developer ID and a valid Developer Account with a configured development certificate and provisioning profile. (Please make sure the provisioning profile has iOS Distribution type)
  • A valid iOS Development Certificate and Provisioning Profile are necessary to test on a real device. Your app will also need to be signed. You can find information about this in the Apple documentation.
  • An iPad or iPhone. Make sure this has been set up for development in Xcode.
  • A signed .app or .ipa file of your app, or the source code to build one.
  • A Mac with Xcode and the Xcode Command Line Developer Tools.

Appium handles installing the application to the device, using ideviceinstaller (which is installed as part of libimobiledevice), but it is sometimes easier to pre-install your app using Xcode to ensure there are no problems (see again the Apple documentation for this).

Troubleshooting ideas

  1. Make sure UDID is correct by checking it in Xcode Organizer or iTunes. It is a long string (20+ chars).
  2. Make sure that you can run your tests against the Simulator.
  3. Make sure the following settings are enabled on your device:
    1. Settings -> Developer -> Enable UI Automation
    2. Settings -> Safari -> Advanced -> Web Inspector and Remote Automation
      1. Please read Automating mobile web apps for more details about WebView
  4. Consider generating a provisioning profile with .xctrunner identifier if you do not want to generate a wildcard one for manual configuration. The .xctrunner config support has been added since Xcode 11. A reference
  5. Make sure the device under test is not a jaibroken one
    • com.apple.mobile.installation_proxy service to manage Apps on the device does not work
  6. Make sure the provisioning profile has iOS Distribution certificate
    • An active Xcode/xcodebuild connection/session is necessary to interact with WebDriverAgentRunner because of Apple's security design. The certificate affects the limitation (issue)