Deprecation Notice: While this tool might functionally still work, it has not been kept in maintenance. It is left here as a basis for future projects.

Android's adb offers the ui/application exerciser monkey. Conveniently employing it can be cumbersome, though:

• It's inconvenient to kill a running monkey.
• You can't let it run unobserved for extended periods of time because it ends after a crash or a freeze.
• You either need to watch the log in your (running) sdk, or you manually handle logcat.
• Managing all of the above on multiple devices is a real pain.

monkey_master is a convenience tool for solving these issues. It can easily be combined with other tools, for example to build a fully automated build & test system.

Besides having convenience commands for starting and killing adb monkeys, it has multi-device support (simultaneously running monkeys on multiple devices) and automatically creates log files for each device.

For an example of a monkey_master test setup, and the reasoning behind the project, visit this blog post.

monkey_master is available as a ruby gem:

gem install monkey_master

adb needs to be in your PATH variable. To do this, you could add the following to your ~/.bashrc or ~/.profile for example:

export PATH=/YOUR/PATH/android-sdks/platform-tools:$PATH

Furthermore, you need to have a device in development mode connected. Currently, monkey_master is not tested with an emulator. For a list of connected devices, use adb devices.

Usage:
  monkey_master <app_id> [--devices <devices>] [--iterations <iterations>] [-k] [--adb <adb_args>]
  monkey_master -k
  monkey_master -h | --help
  monkey_master --version

Options:
  -h --help                   Show this screen.
  --version                   Show version.
  --iterations <iterations>   The number of monkeys that should be run consecutively.
                              It is preferable to run a high number of iterations of short-lived monkeys
                              in order to handle freezes better.
  --devices <devices>         Devices which should be used by monkey_master separated by a ','.
                              If the argument is not provided, all detected devices are used.
  --adb <adb_args>            Arguments for running the adb monkey passed as a String, e.g. "--throttle 500".
                              If not provided, reasonable defaults will be used.

An example for a test run could be:

monkey_master com.my.App --iterations 100

If you want to stop the monkeys, either SIGINT (keyboard interrupt) the monkey_master during execution, or call:

monkey_master -k

If you have multiple devices connected, and want to use monkey_master on some of them only, call:

monkey_master com.my.App --devices DEVICEID1,DEVICEID2 --iterations 100

You might want to use monkey_master with a crash reporting tool such as fabric. Simply integrate the crash reporting library of your choice in your Android App, and monkey_master’s crashes will get reported there.

Sometimes you encounter errors that only a monkey can generate, but that you can’t reasonably fix in your code. In case of such an error, you will want to exit gracefully if the user is a monkey (in order to suppress useless crash reports), but leave the error handling as it is for production.

Furthermore, you might want to disable certain network calls, or redirect them to a test server.

For such cases, there’s ActivityManager.isUserAMonkey():

if(ActivityManager.isUserAMonkey()) {
    // Work on the test server
} else {
    // Work on the production server
}

Code style or beauty fixes are just as welcome as pull requests, bug reports or ideas.