Environment Setup


Node.js v8.0 or higher.


Xcode v9 or higher is required.

  • usbmuxd is needed in order to testing real iOS device via USB.
$ brew install usbmuxd
$ brew install ideviceinstaller
$ brew install ios-webkit-debug-proxy
  • debug log will be displayed when '--verbose' is set as an argument when initiating macaca.

iOS Real Device

$ DEVELOPMENT_TEAM_ID=TEAM_ID npm i macaca-ios -g


  • Install the latest JDK 1.8 (Java 9 is not supported)
  • Install the Android SDK`
  • Set the ANDROID_HOME environment variable to your ~/.bashrc, ~/.bash_profile, ~/.zshrc or whatever your shell uses:
export ANDROID_HOME = /usr/local/opt/android-sdk

gradle is needed in order to build UIAutomatorWD and other package.(For Windows Users plz download gradle installer and set PATH environment variable.)

$ brew install gradle
  • If you got a error like [You have not accepted the license agreements of the following SDK components] on your install command [npm i macaca-android -g],plz accept all Android SDK licenses uses command below, and retry install.
$ yes | $ANDROID_HOME/tools/bin/sdkmanager --licenses


Default Version

Macaca Cli

Global Installation

$ npm i -g macaca-cli

If you saw the picture below, congratulations! Macaca has been installed successfully!

Local Installation

$ npm i macaca-cli --save-dev

# start Macaca
$ ./node_modules/.bin/macaca run --verbose

Driver Installation

# please run below for newer npm
$ npm i macaca-ios -g


Let's check the version and verify the environment.

# show version
$ macaca -v

# verify environment
$ macaca doctor

Prepare Application

iOS: An valid iOS application package suffixed with .app.

Android: An valid Android application package suffixed with .apk.

Desktop: All web application could be run with initial url.

Last Updated: 12/31/2018, 4:41:23 AM