# Environment Setup

# Node.js

Node.js (opens new window) v8.0 or higher.

# iOS


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

First, there are two concepts that we need to clarify:

  • Macaca depends on macaca-ios, and macaca-ios depends on XCTestWD which is installed on real device. Hence we need to ensure that the XCTestWD we are using is the XCTestWD installed on the real device.
  • The XCTestWD installed on real device needs the same signature (TEAM_ID) as the app that we are testing against.

Set TEAM_ID as an environmental variable when installing macaca-ios. XCTestWD will automatically use that TEAM_ID.

# Uninstall previously installed macaca-ios
$ npm uninstall -g macaca-ios

# Install macaca-ios with TEAM_ID
$ DEVELOPMENT_TEAM_ID=TEAM_ID npm i macaca-ios -g


If you don't know your TEAM_ID, you can find it or configure it inside your project in XCode (requires Apple account login) Click on "Other" when selecting Development Team to view the current TEAM_ID.

Configure udid, bundleId and app inside the testing script. Refer to desiredCaps (opens new window).

  • Leave out the app config if the app is already installed on the device.

If you manually installed or downloaded XCTestWD, or the project already comes with XCTestWD:

  • Open /XCTestWD/XCTestWD.xcodeproj with XCode
  • Configure TEAM_ID (Refer to steps above)
  • Run Test to install XCTestWDUITest into the real device:
  • Make sure that the correct XCTestWD is used by Macaca:
    • Use environmental variable MACACA_XCTESTWD_ROOT_PATH to set the location of XCTestWD, refer to XCTestWD docs (opens new window).
      • The location should contain XCTestWD folder outside XCTestWD.xcodeproj, instead of XCTestWD.xcodeproj directly.
      • For example, MACACA_XCTESTWD_ROOT_PATH=/path/to/macaca_xctest app-inspector -u xxx --verbose
    • XCTestWD location could be inside node_modules of another package, or globally installed at /usr/local/lib/node_modules/xctestwd

# Android

# 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

# Desktop

# 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 (opens new window)

# 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: 8/1/2019, 3:02:34 PM