<commit_before>`monkey_master` - A tool for conveniently employing Android adb monkeys.
================================================================

[![Build Status](https://travis-ci.org/j4zz/monkey_master.svg)](https://travis-ci.org/j4zz/monkey_master)

Android's adb offers the ui/application exerciser [monkey](http://developer.android.com/tools/help/monkey.html). 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 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](http://innovaptor.com/blog/2013/08/18/building-an-automated-testing-and-error-reporting-system-for-android-apps-with-monkey-master-and-crashlytics.html).

Installation
================================================================
`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
================================================================

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

Usage Examples
----------------------------------------------------------------
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:<commit_msg>docs(README): add gem version badge and add new helptext from bin/monkey_master to inform new users about the option to pass own adb arguments<commit_after>`monkey_master` - A tool for conveniently employing Android adb monkeys.
================================================================

[![Build Status](https://travis-ci.org/j4zz/monkey_master.svg)](https://travis-ci.org/j4zz/monkey_master) [![Gem Version](https://badge.fury.io/rb/monkey_master.svg)](http://badge.fury.io/rb/monkey_master)

Android's adb offers the ui/application exerciser [monkey](http://developer.android.com/tools/help/monkey.html). 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 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](http://innovaptor.com/blog/2013/08/18/building-an-automated-testing-and-error-reporting-system-for-android-apps-with-monkey-master-and-crashlytics.html).

Installation
================================================================
`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
================================================================

```
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.
```

Usage Examples
----------------------------------------------------------------
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:
{'fraction_non_alphanumeric': 0.16472403153925266, 'fraction_numerical': 0.00497086047308879, 'mean_word_length': 3.6605431309904155, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 13, 'https://': 5, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3643215', 'n_tokens_mistral': 1619, 'n_tokens_neox': 1490, 'n_words': 634}