Conquer iOS Automation: Your Comprehensive Guide to Xcode, Appium, and WebDriverAgent Setup & Troubleshooting

In this article, we’ll show you how to configure Appium to run your app on an iOS Simulator and a real iOS device. Appium is an open-source test automation framework for use with native, hybrid, and mobile web apps. We’ll be using WebDriverAgent, a WebDriver server implementation for iOS, to remote control iOS devices.

Table of Contents:

1. Configure Appium for iOS Simulator
2. Configure Appium for iOS Real Device
3. Common Errors and Solutions

Configure Appium to run the app on iOS Simulator

WebDriverAgent is a WebDriver server implementation for iOS that can be used to remote control iOS devices.

We need to add an account to xCode (you can use your Apple Id or create new).

1. For that go to xCode — Preferences — Accounts:

Sign in with your Apple Id or create a new one

Once you are signed in — you account will appear at the left.

We need to add Signing Certificate to this account:

1. Click on Download Manual Profiles

2. Click on Manage Certificates — Plus icon — Apple Development. Once it is done — you will see a new certificate added to the list as per screenshot below

3. To make sure our certificate is placed — go to Keychain Access — Keys and check if this certificate is present. Example below

Open WebDriverAgent project in xCode.

• To find it please use the following path : /usr/local/lib/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj

(NOTE: If you do not see /urs folder — please use shortkeys “Shift”+”Command”+”.” to display hidden files in your Macintosh HD root)

• Click on Project name at the left navigation (WebDriverAgent)
• For both the WebDriverAgentLib and WebDriverAgentRunner targets, select "Automatically manage signing" in the "Signing & Capabilities" tab, and then select your Development Team(out Apple Id we included to the Accounts in xCode above). This should also auto select Signing Certificate. The outcome should look as shown below:

• If the error below appears we will need to change Bundle Identifier to something xCode can accept.

• Instead of com.facebook I usually put my app name (example myTestApp). It should be changed in the following places:

-WebDriverAgentLib target:

• On Signing & Capabilities tab — Bundle Identifier
• Build Settings tab — Packaging — Product Bundler Identifier

-WebDriverAgentRunner target:

• Build Settings tab — Packaging — Product Bundler Identifier

-IntegrationApp target:

• On Signing & Capabilities tab — Bundle Identifier
• Build Settings tab — Packaging — Product Bundler Identifier

Add an Apple Development option to Signing section

• WebDriverAgentLib target — Build Settings tab — Signing — Code Signing Identity — select Apple Development for all options

Build IntegrationApp to your simulator (the one you will use for testing)

1. If there is an error “RoutingHTTPServer/RoutingConnection.h’ file not found” then please do the following in your Terminal:

• cd /usr/local/lib/node_modules/appium/node_modules/appium-webdriveragent
• rm -rf Carthage
• brew uninstall carthage
• brew install carthage
• sh Scripts/bootstrap.sh -d

2. After it is done — build an IntegrationApp again — it should successfully built into your simulator

Build WebDriverAgentRunner to your simulator

1. Select a target “WebDriverAgentRunner” and build it to the same simulator we used to build IntegrationApp
2. Once build is successful check the following:

• go to /Users/<macName>/Library/Developer/Xcode/DerivedData/WebDriverAgent-<hash>/Build/Products/Debug-iphonesimulator/ — make sure WebDriverAgentRunner-Runner file is present

Now you can use Appium inspector and run your tests

1. In case you get an error “Original error: Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65 xcodebuild error message”…”The file “WebDriverAgentRunner-Runner.app” couldn’t be opened because there is no such file.” Basically Appium is looking for a WebDriverAgentRunner-Runner in a different folder. To fix it you can use this workaround :

• Go to /Users/<macName>/Library/Developer/Xcode/DerivedData/WebDriverAgent-<hash>/Build/
• Copy Products folder
• Paste it to the other WebDriverAgent-<hash from error> folder

After this point Appium should successfully run the simulator to inspect elements as well as successfully run your tests!

Configure Appium to run the app on iOS Real Device

Assuming we did all configuration for iOS Simulator and it is successfully done.

Now there are only few additional steps need to be taken to do the same for Real Device

Build IntegrationApp to your real device (the one you will use for testing)

If it can not be launched — click on it manually once installed. If you see something similar to “Untrusted developer” popup then do the following: You can go to

Settings — General — Device Management on the device to trust the developer. After that you can open the app successfully

Build WebDriverAgentRunner to your simulator

Once build is successful check the following: go to

/Users/<macName>/Library/Developer/Xcode/DerivedData/WebDriverAgent-<hash>/Build/Products/Debug-iphoneos/ — make sure WebDriverAgentRunner-Runner file is present

Add additional capabilities to your Appium (and tests too) as following:

• udid = udid of your device (can be found in iTunes when you connect the phone)
• xcodeSigningId = “iPhone Developer”
• xcodeOrgId = Can be found in developer.apple.com — Membership — Team ID ( or you can find it in your Keychain Access — Key — Developer certificate)

xcodeOrgId

• Now your appium capabilities in the Appium Inspector look like this:

Start a session to inspect the elements

1. In case you get an error “Unable to launch WebDriverAgent because of xcodebuild failure: xcodebuild failed with code 65 xcodebuild error message:…” + …”The file “WebDriverAgentRunner-Runner.app” couldn’t be opened because there is no such file.” UserInfo={NSFilePath=/Users/<yourname>/Library/Developer/Xcode/DerivedData/WebDriverAgent-akxhdiizyykdxefsthlnfyomlaiz/Build/Products/Debug-iphoneos/WebDriverAgentRunner-Runner.app”. Here we should do the same workround as with simulator by copying Products folder into desired WebDriverAgent folder

• Go to /Users/<macName>/Library/Developer/Xcode/DerivedData/WebDriverAgent-<hash>/Build/
• Copy Products folder
• Paste it to the other WebDriverAgent-<hash from error> folder

2. In case of error that “Unable to launch WebDriverAgent” — make sure you did accepted unknown developer on your real device

• You can go to Settings — General — Device Management on the device to trust the developer and allow the app to be run

3. After these workarounds it should successfully inspect your elements from real device

3. Common Errors and Solutions

In this section, we provide solutions to common errors encountered during the Appium setup process for iOS devices:

ENOENT: no such file or directory

• Solution: Run cd /Applications/Appium.app/Contents/Resources/app ; npm install in your terminal.

Unable to launch WebDriverAgent due to xcodebuild failure

• Solution: Add the xcodeOrgId and xcodeSigningId desired capabilities or manually set your team info in the WebDriverAgent Xcode project.

Could not connect to lockdownd

• Solution: Run sudo chmod -R 777 /var/db/lockdown/ and reinstall ios-webkit-debug-proxy if necessary.

Xcode9.1+IOS 11.1.2+APPIUM1.2.7 runtime throws exceptions,’11.1.2'does not exist in the list of simctl SDKs

• Solution: Run your tests with an available simulator version.

Unable to initialize ios-deploy

• Solution: Make sure to install ios-deploy (npm install -g ios-deploy) and enable UI Automation on your device (Settings > Developer > Enable UI Automation). Also, start the iOS debug proxy before starting the Appium server.

Script taking forever to load and launch on a real device

• Solution: Uninstall and reinstall the WebDriverAgent app from your real device or simulator, restart the phone, and try running your tests again.

After following these steps and resolving any errors, your Appium setup should be complete, and you can run your tests on both an iOS Simulator and a real iOS device. If you encounter any other issues, feel free to consult the Appium documentation or community forums for further assistance.

Run your tests on Real Device — yay they run successfully!

These workarounds helped me with my configuration of Mobile automation. I hope using them you will save plenty of your time. Please share your thoughts in case there is something more to be added