An brief introduction of using Macaca for running Appium tests
Latest commit b8da2d7 Oct 31, 2016 @chenchaoyi committed on GitHub Update
Failed to load latest commit information.
.gitignore Init commit Aug 8, 2016 Update Oct 31, 2016


For more of how to inspect iOS 10 app after upgrading to Appium 1.6, now you can refer to this article.


A brief introduction of

  • How to use Macaca to run Appium test
  • How to work around Appium to use XCUItest underlayer

This repo provides simple instructions on setup Macaca locally to run your existed Appium tests, as well as setup Appium to use XCUItest underlayer if you would like to stick with Appium.


Disconnect your VPN before starting Macaca or Appium XCUItest server, it confuses on network interfaces otherwise.


Appium has been around for 5 years, yet I couldn't find any alternative solution until Macaca was introduced last year.

  • The Automation instrument has been removed from Instruments since Xcode 8 beta 2. While Appium still struggles to migrate to XCUItest underlayer, Macaca has already done the switch.

  • Macaca supports multiple selenium sessions in single test.

The following instruction is for iOS for now.


$ mkdir macaca-tryout
$ cd macaca-tryout
  • Install macaca client locally:
$ npm install macaca-cli
  • Install macaca iOS driver locally
$ npm install macaca-ios

And that's it, all setup is done.


  • Start macaca server on Appium server port:
$ ./node_modules/.bin/macaca server --verbose -p 4723
  • Now you can run your Appium test just as it is. Macaca server replaces Appium server, and you are all set to see your tests running with XCUItest instead of the deprecated UIAutomator underlayer.

Macaca Inspector

Macaca provides a Web based inspector for you to locate App elements, just like the Appium UI inspector.

To try it out:

  • Create a new folder:
$ mkdir macaca-inspector
$ cd macaca-inspector
  • Install macaca client (I don't recommend to install it globally):
$ npm install app-inspector
  • Use it (for iOS)
# Get the UDID of your simulator
$ xcrun simctl list
# Start your selected simulator
$ open -a Simulator --args -CurrentDeviceUDID "${this.deviceId}"
# Start Macaca inspector, then point your browser to the address as showed in the terminal
$ ./node_modules/.bin/app-inspector -u "${this.deviceId}"

Setup Appium to use XCUItest

Start Appium from latest source

# Clone Appium repo and install node modules
$ git clone
$ cd appium
$ npm install
$ ./node_modules/.bin/gulp transpile
# Install webpack
$ npm install webpack-dev-server -g
# Start Appium server
$ node .

Run test with XCUItest

  • Add "automationName": "xcuitest" to capabilities, then you are ready to run your Appium test with XCUItest underlayer.
  • For XPath, the previous UIA class name needs to be changed to XCUIElementType class name.

Some mappings that need to pay attention:

  • UIATableCell -> XCUIElementTypeCell

For a full list of reference, please refer to this.