Setup Guide for Appium Real iOS Device

Appium is a useful resource for cross-platform automation testing. By utilizing the underlying WebDriver protocol in conjunction with its platform specific automation drivers, Appium lets you run your tests on both virtual and real mobile devices. To drive a real iOS device, Appium utilizes the WebDriver-Agent library which exposes the XCUITest API provided by Apple. Appium manages the WebDriver-Agent API under the hood and reduces the barrier to entry to write automaton tests for real iOS devices.

The WebDriver-Agent library installs an app on the real device to expose the XCUITest API. Since the Appium XCUITest driver has to manage the independent Webdriver-Agent library, it can run into provisioning or code-signing issues. For that reason, I am writing this guide to walkthrough the setup process for using real iOS devices and what can be done when you run into issues.

💡 You can integrate your Appium iOS tests with Tauk! You can try it for free here: https://www.tauk.com/welcome

Requirements

Before getting started, we need to ensure that you have access to the following items

• Computer running macOS. This is necessary for a variety of reasons, but the most important one is due to the fact that Xcode is needed to compile the WebDriver-Agent app to be installed on the device to expose the XCUITest API.
• Latest version of Xcode needs to be installed on your system. The version of Xcode needed can depend upon the iOS version of the real iOS device that you are using for automation. For example, iOS 15 devices require Xcode 13 to be installed. It is therefore useful to install the latest version of Xcode. You can install Xcode from the Mac Apple Store.
• Xcode developer tools needs to be installed. You can install these by executing the xcode-select --install command in the terminal.
• The Mac device needs to be trusted by the connected real device. When you connect the iOS device to the Mac, you should see an alert on your iOS device asking to Trust this Computer?. By accepting this alert, you can meet this requirement.

Real Device Appium Capabilities

When creating the Appium driver, you need to ensure that the following capabilities are set.

• platformName needs to be set to iOS
• bundleId needs to be set to the bundleID of the app under automation. For example, to launch the System Preferences app, I would use com.apple.Preferences.
• automationName needs to be set to XCUITest
• udid needs to be set to the UDID of the connected real device. You can get this by executing the xcrun xctrace list devicese command in your terminal.

• xcodeSigningId needs to be set to iPhone Developer
• xcodeOrgId needs to be set to the Team ID of your developer account. The Team ID can be found in Keychain Access. Click on the login keychain on the sidebar. You should see an Apple Development certificate. The 10 digit ID in the bracket is the Team ID

After setting these capabilities and ensuring the requirements of the previous section are met, you can try running your test which creates the Appium driver. If the driver is created successfully, you can move forward with your automation. Otherwise, you may need to spend some time debugging the issue.

Debugging

When you encounter an error related to real iOS device setup, you will most likely see the following line in your Appium Server log:

xcodebuild exited with code '65' and signal 'null'

This means that Xcode failed to compile the WebDriver-Agent app.

• To understand why the Xcode build failed, it will be useful to see the Xcode logs of your build. Appium gives you a useful capability called showXcodeLog which will log all the build information logs from Xcode into your Appium Server logs.
• If these logs do not point you in a direction which can help fix the issue, you should open the the WebDriver-Agent project in Xcode.

WebDriverAgent Manual Setup

You can open WebDriver-Agent project in Xcode by locating it within the Appium installation. The following command should tell you where Appium is installed on your system.

ranvir@MacBook-Pro ~ % which appium
/Users/ranvir/.nvm/versions/node/v16.14.0/bin/appium

After you locate your Appium installation, you can change your directory to the corresponding parent directory and navigate to WebDriverAgent. The directory path should resemble the which appium path.

.../v16.14.0/lib/node_modules/appium/node_modules/appium-webdriveragent

Note: the which command is a terminal command to identify the location of a given executable, in this case Appium installed from npm.

After going to this directory, you need to execute the following command:

mkdir -p Resources/WebDriverAgent.bundle
open .

This should open the following Finder window. You can now open the WebDriverAgent.xcodeproj file by double clicking it.

In the left sidebar (the Xcode Inspector), select WebDriverAgent. This should open the project wide settings in the editor area. In the second sidebar on the left, click WebDriverAgentRunner under the TARGETS section. Now, here you should see something like the screenshot below. As you can see the status, WebDriverAgent is running into code signing issues.

• Make sure Automatically manage signing is selected.
• Set the Team to your Apple ID account’s developer team.

Modifying the Default Bundle ID

If the issue is still not resolved, you need to modify the the default bundle identifier for this target.

• In the top of this editor, click on the Build Settings tab.

• In the Packaging subsection, you will see a field called Project Bundle Identifier. You need to modify this to a different name as this name is already registered with another Apple ID. You can do something like com.<YOUR_NAME>.WebDriverAgentRunner.

• Now, navigate back to the Signing & Capabilties Tab. You should see that the error is fixed.

At this point, if you re-run your test case, the Appium driver should be created successfully. If you are still running into issue, you should go through the Xcode Logs again.

Conclusion

As you might have noticed, the Xcode setup for real iOS devices can be tricky for a first time user. However, this is still better than having to manage your own WebDriverAgent server to expose XCUITest API. Appium does that for you, but has to deal with a whole range of code signing and provisioning pitfalls during setup. Hopefully, this short guide will be handy whenever you want to setup a real iOS device for Appium Automation.

Lastly, if you have any questions on this blog post, you can reach out to us by joining our Discord server:

Join the Tauk Discord Server!