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
# local installation
$ npm i macaca-ios --save-dev
# global installation
$ npm i macaca-ios -g
  • debug log will be displayed when '--verbose' is set as an argument when initiating macaca.

iOS Real Device

  • Download XCTestWD
    • If XCTestWD is a dependency of another package, use environmental variable to pass in the location of XCTestWD, refer to the XCTestWD doc
      • For example, MACACA_XCTESTWD_ROOT_PATH=/path/to/macaca_xctest app-inspector -u xxx --verbose
    • Alternatively, find it in the relevant node_modules
    • For example, in the case of globally installed app-inspector, it is at /usr/local/lib/node_modules/app-inspector/node_modules/xctestwd
  • Open /XCTestWD/XCTestWD.xcodeproj with XCode
  • Import developer certificate
  • Execute Run Test to import XCTestWDUITest into the real device

  • Install macaca-ios with TEAM_ID, find TEAM_ID in XCode after importing XCTestWDUITest into the real device:

$ DEVELOPMENT_TEAM_ID=TEAM_ID npm i macaca-ios -g
  • If you need to run iOS tests, also remember to pass in relevant parameters for real device in desiredCaps, such as udid, bundleId and app.

More details

Refer to this issue for more details


  • Install the latest JDK 1.8 (Java 9 is not supported)
  • Set the JAVA_HOME environment variable in your ~/.bashrc, ~/.bash_profile, ~/.zshrc or whatever your shell uses:
# for example
export JAVA_HOME=path/to/your/Java/Home
# or
export JAVA_HOME="$(/usr/libexec/java_home -v 1.8)"
  • Install the Android SDK and Android Support Repository, using any of the versions within 18-25
  • Set the ANDROID_HOME environment variable in your ~/.bashrc, ~/.bash_profile, ~/.zshrc or whatever your shell uses:
# for example
export ANDROID_HOME=/usr/local/opt/android-sdk
# or
export ANDROID_HOME="/Users/<UserName>/Library/Android/sdk"
$ brew install gradle
# local installation
npm i macaca-android --save-dev
# global installation
npm i macaca-android -g
  • 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, please accept all Android SDK licenses uses command below, and retry install.
$ yes | $ANDROID_HOME/tools/bin/sdkmanager --licenses


# local installation
npm i macaca-electron --save-dev
# global installation
npm i macaca-electron -g
# local installation
npm i macaca-chrome --save-dev
# global installation
npm i macaca-chrome -g

Chrome driver 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

Environment Check

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: 6/1/2019, 3:58:40 AM