Appium and Protractor for real device automated testing (Mac OS/iOS 10.3+)

Appium and Protractor for real device automated testing (Mac OS/iOS 10.3+)

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

  1. 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.
  2. 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’.
  3. 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
  4. Next, install Homebrew by entering the following into the terminal:  ruby -e "$(curl -fsSL"
  5. Update our bash profile:  nano ~/.bash_profile and then enter  export JAVA_HOME=$(/usr/libexec/java_home) Save the file and exit.
  6. 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

  1. With Homebrew installed, we gain access to the helpful  brew  terminal command. Let’s update Homebrew by entering  brew update .
  2. Next, install Node:  brew install node
  3. 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.
  4. 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.
  5. 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.
  6. 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.
    1. cd /usr/local/lib/node_modules/appium/node_modules/appium-xcuitest-driver/WebDriverAgent
    2. brew install carthage
    3. npm i -g webpack
    4. ./Scripts/ -d
  7. 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

  1. 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
  2. Run appium doctor with  appium-doctor --ios
  3. 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

  1. 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
  2. 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

  1. For real (local) device testing, you need a valid  xcodeOrgId ,  xcodeSigningId and  udid in your protractor capabilities
    1. xcodeOrgId: APPLE TEAM ID
    2. xcodeSigningId: ‘iPhone Developer’
    3. autoWebview: true,
    4. udid: ‘auto’
  2. The Apple Team ID can be found on the Apple Developer page. Do not change the xcodeSigningId value.
  3. 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

  1. 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.
  2. Launch the iOS Debug Proxy  ios_webkit_debug_proxy -c null:27753,:27753-27853
  3. Run your Protractor tests:  protractor conf.ipad-dev.js --baseUrl="" --specs="path/to/my/test"
  4. For completeness, here are my protractor capabilities:


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).

  • sandeep

    I’ll appreciate you for whatever you have done which has helped me a lot for my configuration. However i’m still getting the error as No webview found and getting below error.

    [debug] [RemoteDebugger] Getting WebKitRemoteDebugger pageArray: localhost, 27753
    [debug] [RemoteDebugger] Sending request to: http://localhost:27753/json
    [debug] [RemoteDebugger] Page element JSON: []
    [debug] [iOS] No web frames found.

    I’m on real device iPad with 11.2.6 and MAC OS 10.13.4 and not able to figure out the actual issue.

    When i’m opening localhost:9222 in my Chrome browser(MAC) i’m able to inspect Safari(iPad) but Chrome(iPad) and my application is throwing [] as output.

    Please do reply and help me with this.

  • Tyler Deren

    Hey there,

    Which version of XCode and which version of Appium are you using? I often experience this problem after an iOS Update (I hate updating iOS because of it 😛 ) and the cause is usually caused by an incompatible version somewhere in the stack setup.

    In my case, the problem is usually an incompatible XCode version. If you scroll up further in the Appium server logs, keep a keen eye out for build errors or build failures. Sometimes I need to use beta versions of XCode to get all of the tests working on iPad again, which you can find in the Apple developer portal.

    So my advice is to comb the server logs and look for anything suspicious. Often the problem will get buried in the repeated “No web frames found” error and be tough to spot at an initial glance.

    • sandeep

      Thank you for the quick reply.

      XCode version: 9.3.1
      Appium version: 1.8.0

      This is what i’m getting in terminal
      [iOS] Could not find any webviews yet, refreshing/retrying
      [debug] [iOS] Retrieving contexts and views
      [debug] [iOS] Selecting by url: false
      [debug] [RemoteDebugger] Getting WebKitRemoteDebugger pageArray: localhost, 9222
      [debug] [RemoteDebugger] Sending request to: http://localhost:9222/json
      [debug] [RemoteDebugger] Page element JSON: []
      [debug] [iOS] No web frames found.

      If required i can post the whole log file as I have tried my best to understand the logs but not finding the actual cause for problem.

      • Tyler Deren

        Sure, if you can post the full Appium logs I can take a look. Be sure to check and black out any logs that contain your xcodeOrgId though!

        • sandeep

          hi, I have uploaded my log file

          • Tyler Deren


            It looks like you are using Appium to test a native app. I am not certain if this guide is valid for that set-up. I use Appium for automated testing of a web-application, and this guide was written more as a future reference for setting that stack up.

            There may be a dependency somewhere that you are missing, that I don’t mention in the article. Unfortunately, my use case doesn’t use Appium with a native app, so I’m afraid I can’t be of much help there 🙁

          • sandeep

            Hey Tyler, the developers are saying its an Hybrid application and more over i’m able to automate the application on web view and android.

            I’m using protractor to automate my application and followed your steps for configuration.

            If you can help me find out whether the application is hybrid that will help me for further steps.

  • sandeep

    Hi Tyler,
    I just tried executing some scripts on Amazon and Flipkart application but still getting the same error as No webview found. Please help me with this.

    • Tyler Deren

      The only thing I can suggest is to run:
      brew reinstall –HEAD libimobiledevice
      brew reinstall -s ios-webkit-debug-proxy

      And if that doesn’t work, verify you have the latest versions of all dependencies and they all work together. Make sure you use “safari” in the “browserName” capability for web-applications. I only use Appium for testing web-applications currently, and this guide was written with that target in mind. There may very well be different dependencies for testing hybrid-applications or dependencies I mention in the article are deprecated (Article is over a year old), and I won’t know what those are without doing some research.

      I won’t be doing any Appium upgrades for awhile, so I won’t have to go through the convoluted steps of upgrading everything anytime soon. If you do find the solution in your research attempts, feel free to comment what it was here 🙂

Comments are closed.