Friday, April 13, 2012

Android testing with Monkey tool – a comprehensive guide

If you are in the android scene for some time, you may have heard about this tool. Monkey tool is a simple but very important tool to test android applications for their stability. It is a command-line tool that you can run on any emulator instance or on a device. Basically it sends out random key events and clicks to the device or emulator. If you have done testing on WM devices, you may have used a similar testing tool called hopper. In this tutorial i am hoping to guide you through the basic operations you can do with monkey tool and also some more advance and specific tasks.
The Monkey includes a number of options, but they break down into four primary categories:
  • Basic configuration options – such as setting the number of events to attempt.
  • Operational constraints – such as restricting the test to a single package.
  • Event types and frequencies – such as key events, click events and time interval between events.
  • Debugging options.
When the Monkey runs, it generates events and sends them to the system. It also watches the system under test and looks for three conditions, which it treats specially:
  • If you have constrained the Monkey to run in one or more specific packages, it watches for attempts to navigate to any other packages, and blocks them.
  • If your application crashes or receives any sort of unhandled exception, the Monkey will stop and  report the error.
  • If your application generates an application not responding(ANR) error, the Monkey will stop and report the error.
Depending on the verbosity level you have selected, you will also see reports on the progress of the Monkey and the events being generated.
That’s enough …. where is the actual test? ….
How to run monkey?

As mentioned above, monkey is a command line tool. In a command line or in a linux terminal window, you can run your first monkey test with the following command.
$>adb shell monkey -v 100

adb - connect to the device
shell - start the terminal (command line) on the device/emulator
monkey - start the monkey tool
-v - verbose mode
100 - number of random events to be sent

You will see some messages displaying on your command line window and if you are fortunate you may experience that monkey tool exits before it completes 100 events due to some exception or ANR scenario. But that will depend on the random events it sends and the applications you have.
How to run monkey on my own application?

OK.. Now you know how to run monkey and what are things it can do up to some level. Let’s run this test entirely on your own application. Let’s you have installed the package” and you want to test this application against random clicks.
$>adb shell monkey -p -v 500

-p - This will specify the application package you need to test.

How to run the same event sequence again?

Sometimes you may want to check whether a particular failure always happens or randomly happens in an application. In a such scenario, you may need to run the exact same event sequence with monkey tool. You can achieve that goal like this.
Run your first test with
$>adb shell monkey -p -s 999 -v 500

Go back to the same status in the device and run the above command again

$>adb shell monkey -p -s 999 -v 500

-s - This will give the random seed value to generate the random events.

Note: It is essential to start both the tests with the same status in the device. Otherwise It will not give you the same result even though it sends the same events.

This tool has many more features and you can learn about these features from the android developer guide here

Cheers !!!!!!!


  1. Hey, can monkeyrunner.jar file impoerted into android project?

  2. You have provided an nice article, Thank you very much for this one. And i hope this will be useful for many people.. and i am waiting for your next post keep on updating these kinds of knowledgeable things...
    Mobile App Development Company
    Mobile App Development Companies