iOS Automation With Appium Desktop for Real Devices/Simulators

This tutorial is to start/set up your environment for iOS Automation. Here, we will be doing it with an Appium desktop instead of appium as an npm package.

Why Appium Desktop? :

Appium Desktop is an app for Mac, Windows, and Linux which gives you the power of the Appium automation server in a beautiful and flexible UI. It is a combination of a few Appium-related tools:

• A graphical interface for the Appium Server. You can set options, start/stop the server, see logs, etc… You also don’t need to use Node/NPM to install Appium, as the Node runtime comes bundled with Appium Desktop.
• An Inspector that you can use to look at your app’s elements (Safari/Chrome browser, native or hybrid app), get basic information about them, and perform basic interactions with them. This is useful as a way to learn about Appium or as a way to learn about your app so you can write tests for it.

System Requirements :

1. Mac OS High Sierra (10.13) (or higher)
2. A 64 bit CPU

System setup :

Xcode

Xcode is an integrated development environment (IDE) for macOS containing a suite of software development tools developed by Apple for developing software for macOS, iOS, iPadOS, watchOS, and tvOS. You can install it from here.

Homebrew

Homebrew is a package management software that will make it much simpler for us to install a few other software. You can install it from here.

Carthage

Carthage builds your dependencies and provides you with binary frameworks, its needed by the WebDriverAgent. Use the following command to install :

brew install carthage

ios-deploy

ios-deploy is a utility to install and debug iPhone apps from the command line, without using Xcode. In terminal, run the following command :

brew install ios-deploy

ideviceinstaller

ideviceinstaller is a tool to interact with the installation_proxy
of an iOS device allowing to install, upgrade, uninstall, archive the iOS applications. In terminal, run the following command :

brew install ideviceinstaller

ios_webkit_debug_proxy

Appium uses this tool to access web views on real iOS devices. In terminal, run the following command :

brew install ios-webkit-debug-proxy

Optional : Node JS and npm

Installing node is completely optional beacuse node runtime comes bundled with Appium Desktop.

Node is a javascript run-time environment and npm is the node package manager. In terminal, run the following command :

brew install node

Appium Desktop

You can install the Appium desktop from here. You can read more about appium desktop from the following link : https://github.com/appium/appium-desktop

After you install all the above mentioned dependancies, we are good to start with the setting up the WebDriverAgent.

WebDriverAgent

WebDriverAgent is a WebDriver server implementation for iOS that can be used to remote control iOS devices. It allows you to launch & kill applications, tap & scroll views or confirm view presence on a screen. This makes it a perfect tool for application end-to-end testing or general purpose device automation. It works by linking XCTest.framework and calling Apple's API to execute commands directly on a device. WebDriverAgent is developed and used at Facebook for end-to-end testing and is successfully adopted by Appium.

In short WebDriverAgent is Mobile JSON wire protocol through which you can communicate with the iOS Device.

Before we continue with WebDriverAgent setup, make sure you have the Apple developer Accout. Without the developer account we may not be able to build the WebDriverAgent successfully.

Steps to build WebdriverAgent :

1. Lauch the appium desktop application.
2. Start the server.

Appium Desktop

3. Connect your iOS Device to your system through USB.

4. Click on the Appium inspector icon.

Appium Inspector Icon

You will see a screen that looks like this :

Appium Inspector

5. Choose “Automatic Server”.

6. Prepare the desired capability based on your device configuration :

{
  "deviceName": "iPhone",
  "platformName": "iOS",
  "platformVersion": "13.6",
  "automationName": "XCuiTest",
  "udid": "<YOUR-DEVICE-UDID>",
  "bundleId": "<YOUR-APPLICATION-BUNDLE-ID>",
  "xcodeOrgId": "<YOUR-XCODE-ORG-ID>",
  "xcodeSigningId": "iPhone Developer"
}

To get the xcodeOrgId follow the steps below :

1. Go to https://developer.apple.com/account
2. Login with you Apple developer account.
3. Click Membership in the sidebar.
4. Your Team ID appears in the Membership Information section under the team name.

Once you have the desired capability JSON ready :

1. Click on the edit icon in the JSON Representation section.
2. Replace “{}” with the JSON that you have prepared.
3. Click on the save button.
4. Your screen should look like this now :

Appium Inspector with Desired Capabilites

You can save these capabilites by clicking on the Save As button, before we continue with the next steps.

7. Click on the “Start Session” button, but there are going to be some failures lets fix them as we continue with the tutorial.

8. Notice you appium terminal, you will see some lines like below

[WebDriverAgent] Beginning test with command 'xcodebuild build-for-testing test-without-building -project
 /Applications/Appium.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj -scheme WebDriverAgentRunner -derivedDataPath /Users/bio-india/Library/Developer/Xcode/DerivedData/WebDriverAgent-alwvnomvwrdtzoaxbbkniqrpcdpp -destination id=13435433-000514680A83002E IPHONEOS_DEPLOYMENT_TARGET=13.6 -xcconfig /var/folders/g3/4bgm1zrj74z3chm8vwwrkpjw0000gp/T/2020719-9679-167r3lc.acxv/appium-temp.xcconfig GCC_TREAT_WARNINGS_AS_ERRORS=0 COMPILER_INDEX_STORE_ENABLE=NO' in directory '/Applications/Appium.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent'

9. From the above lines you can get the path to the WebDriverAgent.xcodeproj which is :

/Applications/Appium.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj

10. Open a terminal and run the following command :

open /Applications/Appium.app/Contents/Resources/app/node_modules/appium/node_modules/appium-webdriveragent/WebDriverAgent.xcodeproj

Now you will see Xcode starting with your WebDriverAgent.xcodeproj

Once the Xcode is launched, add you developer credentials to Xcode with the steps below :

1. Click on the Xcode Menu > Preferences, Alternatively you can also use the below shortcut to go to the preferences

Command + ,

2. Click on the Accounts tab

3. Click on the “+” icon and provide your developer credentials.

Once you have added your account you can then “Download your manual profiles”.

11. Configuring your WebDriverAgent

Now that, we have opened the WebDriverAgent project in the xcode and we have added our developer credentials to the Xcode. Lets configure the WebDriverAgent.

Your screen should look something like this now (You may have some errors as well, which will get fixed with the below steps) :

Xcode Intial Screen

1. Click on the WebDriverAgentRunner in the targets section, you can see that highlighted in the above screenshot.
2. Click on the “Signing & Capabilities” tab.
3. Check the “Automatically manage signing” checkbox.
4. Choose your Team in the Team dropdown.
5. Now, you will notice that the errors are gone.
6. The last step here is to change the bundle id for the WebDriverAgentRunner, Click on “Build Setting” tab.
7. Search for “Product Bundle Identifier” and replace the value with a bundle identifier of your choice. For ex : “com.<YOUR-ORG>.wda.runner”

We are now done with configuring the WebDriverAgent runner lets test this by building it.

Choose the WebDriverAgentRunner as the target application and choose your device as a target device. In this case I chose a simulator and click on the build button “Play Icon”.

Now you will see the message “Build Succeded”. With this the WebDriverAgentRunner setup is complete and you can try restarting the session from your Appium Desktop. (Repeat step 7)

Now you may see a new error in the Appium Console. “xcodebuild exited with code ‘65’”. This is because your device doesnt trust the developer.

To the trust the developer follow the below steps :

1. Click on the “Start Session” button on the Appium Inspector.
2. Notice your mobile launcher, you will see a new App called WebDriverAgent Installed.
3. Go to the phone Settings > General > Device Management.
4. You will see you developer account in the list,
5. Choose that and Click on “Trust the developer”.

Now you should see your application launched by the appium desktop and you can notice the same screen on the Appium Inspector as well.

Conclusion

You can use the same desired capabilities in you code to run the automated tests like below :

DesiredCapabilities iosCapabilities = new DesiredCapabilities();
iosCapabilities.setCapability(MobileCapabilityType.DEVICE_NAME, "");
iosCapabilities.setCapability(MobileCapabilityType.PLATFORM_NAME, "");
iosCapabilities.setCapability(MobileCapabilityType.PLATFORM_VERSION, "");
iosCapabilities.setCapability(MobileCapabilityType.AUTOMATION_NAME, "");
iosCapabilities.setCapability(MobileCapabilityType.UDID, "");
iosCapabilities.setCapability(MobileCapabilityType.NO_RESET, true);
iosCapabilities.setCapability("xcodeOrgId", "<YOUR-TEAM-ID>");
iosCapabilities.setCapability("xcodeSigningId", "iPhone Developer");
iosCapabilities.setCapability("bundleId", "");
driver = new IOSDriver(new URL("http://127.0.0.1:4723/wd/hub"), iosCapabilities);

Alternatively if you wish to install the application into your device through appium you can use the capability mentioned below :

iosCapabilities.setCapability(MobileCapabilityType.APP, "<IPA-FILE>");

Cheers.