The following is the first few sections of a chapter from The Busy Coder's Guide to Android Development, plus headings for the remaining major sections, to give you an idea about the content of the chapter.

MonkeyRunner and the Test Monkey

Many GUI environments have some means or another of “fuzz” or “bash” testing, where some test driver executes a bunch of random input, in hopes of catching errors (e.g., missing validation logic). Android offers the Test Monkey for this.

Many GUI environments have some means or another of scripting GUI events from outside the application itself, to simulate button clicks or touch events. Android offers MonkeyRunner for this.

As the names suggest, there is a bit of commonality in their implementation. And, as you might expect, there is a bit of commonality in their coverage in this book — we will examine both MonkeyRunner and the Test Monkey in this chapter.


Understanding this chapter requires that you have read the core chapters of this book.


MonkeyRunner is a means of creating test suites for Android applications based on scripted UI input. Rather than write a series of JUnit test cases or the like, you create Jython (JVM implementation of Python) scripts that run commands to install apps, execute GUI events, and take screenshots of results.

Writing a MonkeyRunner Script

The primary object you will work with in a MonkeyRunner script is a MonkeyDevice, which represents your connection to the device or emulator that you are testing. You obtain a MonkeyDevice by calling waitForConnection() on MonkeyRunner; this will return once it has established a connection.

From there, MonkeyDevice lets you send events to the device or emulator:

The biggest limitation is in getting data out of the device, to determine if your test worked successfully. Your options are:

Unlike JUnit-based testing, you have no visibility into the activity beyond what appears on the screen — you cannot inspect widgets, call methods, or the like.

For example, here is a script that installs an app, runs an activity from it, and presses the down button on the D-pad three times:

from import MonkeyRunner, MonkeyDevice

device = MonkeyRunner.waitForConnection()
device.startActivity(component='')'KEYCODE_DPAD_DOWN', MonkeyDevice.DOWN_AND_UP)'KEYCODE_DPAD_DOWN', MonkeyDevice.DOWN_AND_UP)'KEYCODE_DPAD_DOWN', MonkeyDevice.DOWN_AND_UP)
# result = device.takeSnapshot()
# result.writeToFile('tests/monkey_sample_shots/test1.png', 'png')

Executing MonkeyRunner

To execute your MonkeyRunner script, have your device or emulator set up at a likely starting point (e.g., home screen), then execute the monkeyrunner command, passing it the path to your script (e.g., monkeyrunner You will see the script executing on the screen of your device or emulator, and your console will contain whatever output you might emit from your test script itself. For example, you might take screenshots, compare them against a master copy (using methods on MonkeyImage to help with this), and emit warnings if they differ unexpectedly.

Monkeying Around

The preview of this section left for Hollywood to appear in a reality TV show.