Quick Start

If you are new to UI automation test or cross-platform automation tool, the basic idea is

  1. You have a test target, such as a website, or an mobile app.
  2. You need to write some test codes to validate the properties and state of UI elements of your target.
  3. Your test codes talk to Macaca, and Macaca talks to your target, execute what you have commanded in your test codes such as switching between screens, inputting text you predefined, return the UI element and properties you described in your test code, and generate a report about pass or failure. Watching the following videos will help you understand the concepts better.

If you have done some UI automation before, you probably have grasped what Macaca can do. You might want to jum right into what's capability. We prepare an example for you to get a taste.


Check out the sample located in this repo(sample-nodejs).

$ git clone https://github.com/macaca-sample/sample-nodejs.git --depth=1
$ cd sample-nodejs
$ npm i
$ npm run doctor
$ npm run test:ios

Run test tasks

# run test in current cwd
$ macaca run --verbose

# run test in a pointed directry and set a framework
# mocha, jasmine, tman, ava supported for Node.js env.
$ macaca run -d ./test -f mocha

# output log file as html code
$ macaca run -o

# run in silence, desktop only
$ macaca run --no-window

# custom mocha reporter
$ CUSTOM_DIR=path/to/screenshot macaca run -d ./test --reporter macaca-simple-reportor

Electron Desktop App Testing

If you wanna the Electron App testing, please check out the sample located in this repo(macaca-electron-app-sample).

# Install dependencies
$ npm i
$ npm run build
$ npm run dist

Run test tasks

# Mac
$ npm run mac-start
$ npm run test

# Windows
$ npm run win-start
$ npm run win-server
$ npm run test


describe('test electron.app', function() {

  before(function () {
    return driver
        platformName: 'desktop',    //Set support Desktop parameters
        browserName: 'chrome',      //Set support Eletron parameters
        chromeOptions: {            //Set chromeDriver chromeOptions object parameters
          binary: '/Applications/macaca-electron-builder.app/Contents/MacOS/macaca-electron-builder'  // Electron path
      .sleep(2 * 1000);

  it('click link', function() {
    return driver
      .waitForElementById('macacaId', 5000, 100)


Start webdriver server only

# normal usage
$ macaca server --verbose

# set a port
$ macaca server -p 3456

Environment doctor

$ macaca doctor

More Help

$ macaca -h

# helper for server
$ macaca server -h

# helper for how to run test
$ macaca run -h

Sample Video


Mobile Safari

Android APP

Android Browser

Desktop (Electron)

More Examples

more sample.

Last Updated: 9/25/2019, 2:39:18 AM