Recently, I had a client who requested their protractor integration tests for a Angular application be set-up so that they are capable of running on a local testing environment using real device hardware. After going through the official ‘Getting Started’ guides for Appium, I felt they did not provide enough detail to get things running smoothly with Protractor and a web application. This guide should provide a comprehensive one-stop solution if you are having problems setting up Appium and Protractor with a web application. This article will only focus on setting up a local test environment for Mac OS using Appium, Protractor and a iPad Mini connected to the Mac OS with a USB cable.
Java, XCode and Homebrew Setup Guide
- The first step is to install the Java JDK from the official Oracle page and only has to be done if you do not yet have the Java JDK installed. Go to the Java JDK page and select the Java SE Development Kit for your operating system. For this article, I will be using Mac OS X. Once the binary has finished downloading, install the Java JDK.
- The next step is to install XCode. Only follow this step if you do not have XCode installed. The easiest way to install this would be to go to the Mac App Store and search for ‘XCode’.
- Once XCode is installed, we need an optional component called XCode Command-line tools. You can install these by opening up the terminal and typing xcode-select --install
- Next, install Homebrew by entering the following into the terminal: ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
- Update our bash profile: nano ~/.bash_profile and then enter export JAVA_HOME=$(/usr/libexec/java_home) Save the file and exit.
- At this point, it might be a good idea to close your current terminal window and fire up a new instance of one.
Install Node and Appium
- With Homebrew installed, we gain access to the helpful brew terminal command. Let’s update Homebrew by entering brew update .
- Next, install Node: brew install node
- Once Node is installed, it also installs the Node Package Manager (NPM). Let’s update npm: npm install -g npm Note: If you receive an error like ‘npm command not found’, try closing your current terminal window and opening another.
- Once our initial dependencies are met, it’s time to install Appium. Enter npm install -g appium in the terminal window to install appium globally.
- Next, install wd.js with npm install wd wd is a library designed to be a maleable implementation of the webdriver protocol in Node, exposing functionality via a number of programming paradigms.
- Next we need Carthage, a web server and opinionated framework for building data manipulation-centric API services in Node.js for web, mobile or IoT apps.
- cd /usr/local/lib/node_modules/appium/node_modules/appium-xcuitest-driver/WebDriverAgent
- brew install carthage
- npm i -g webpack
- ./Scripts/bootstrap.sh -d
- Appium has another dependency when doing real-device testing, libimobiledevice, a cross-platform software library that talks the protocols to support iPhone®, iPod Touch®, iPad® and Apple TV® devices. Install it by entering brew install libimobiledevice into the terminal
Verify Prerequisites are met with Appium Doctor
- appium-doctor is a handy utility which verifies you have all of the necessary dependencies top properly run Appium against the environment you specify. npm install -g appium-doctor to install Appium Doctor
- Run appium doctor with appium-doctor --ios
- Examine the output. If Appium Doctor complains that you are missing something, verify you never missed a step.
Install iOS Deploy and iOS Debug Proxy
- At this point, we have all of the dependencies to run Appium. However, for automated testing on a iPad device we need additional dependencies in order to properly run our Protractor integration tests. The first of these is ios-deploy. Install it through npm: npm install -g ios-deploy
- Finally, we need the iOS WebKit Debug Proxy (iwdp) which proxies requests from usbmuxd daemon over a websocket connection, allowing developers to send commands to MobileSafari and UIWebViews on real and simulated iOS devices. Install it via brew install ios-webkit-debug-proxy
Setting up Protractor Capabilities
- For real (local) device testing, you need a valid
udid in your protractor capabilities
APPLE TEAM ID
- xcodeSigningId: ‘iPhone Developer’
- autoWebview: true,
- udid: ‘auto’
- The Apple Team ID can be found on the Apple Developer page. Do not change the xcodeSigningId value.
- The udid is the unique ID for the real iOS device you have connected to your Mac. Set the value to ‘auto’ for automatic detection
Putting it all together
- Once everything is installed, let’s start the appium REST server and the iOS Debug Proxy. First, appium can be started by entering appium in the terminal. Give it some time to boot up.
- Launch the iOS Debug Proxy ios_webkit_debug_proxy -c null:27753,:27753-27853
- Run your Protractor tests: protractor conf.ipad-dev.js --baseUrl="http://myUrl.com" --specs="path/to/my/test"
- For completeness, here are my protractor capabilities:
deviceName: 'iPad Pro (12.9 inch)',
xcodeOrgId: "<APPLE TEAM ID>",
xcodeSigningId: "iPhone Developer"
Note: If you get ‘cannot find webview, retrying.’ errors ad infinitum, do the following:
brew reinstall --HEAD libimobiledevice
brew reinstall -s ios-webkit-debug-proxy
That’s it! Your Protractor tests should now be running on a real device. I ran into a lot of trouble getting Appium set-up for real devices, and every source I found on the web only had pieces of the final solution. This article was written with the fabulous help of many people and I hope it can provide some measure of assistance if you are experiencing the same issues I was when trying to get Appium running with Protractor and a real iOS 10.3+ device (iPad Mini 2).