Scripting the Android Monkey Tool

The Android Monkey tool produces a pseudo-random stream of inputs, according to the configured parameters. Because of it’s ability to stream inputs to an Android device, the same tool can be used to stream a series of predetermined inputs. This produces a similar effect to the monkeyrunner tool or UI Automator APIs, but does not require writing any code.

This could be useful if you wanted to distribute a set of test inputs but still allow the input sequence to be easily editable.

Script Format

The script starts with a simple header:

type= raw events
count= 5
speed= 1.0
start data >>

The type field describes the type of events. For now, only raw events is used. count describes how many events are given. speed is the number of milliseconds between each event. start data >> completes the header and indicates that the following lines describe events

There is an optional header option, linebyline, which can be used to instruct the Monkey tool to read lines from the file sequentially, rather than loading them all into memory when the tool starts. This might be useful if the script is extremely long or if the events may be edited while the script is being executed. In this case, it is possible for more events to be executed than as described by count.

The next lines, until the end of the file, describe the input events themselves. The basic format of the event is:


The number of arguments is variable – events can have no arguments, a single argument or many arguments. If an event has no arguments, the brackets still need to be provided.

The possible EventKeywords are given below:

EventDescription# ArgsArguments
A touch or a trackball event12/13These arguments are the same as described by MotionEvent. If eventTime is given as zero, then this will be set automatically.

If a 13th argument is given, this is the PointerID – for touch, this describes which finger is touching.
RotateScreenRotates the screen21. At what angle to rotate. 0 for 0 degrees; 1 for 90 degrees; 2 for 180 degrees; 3 for 270 degrees.
2. Whether to persist the rotation (1), or not (0). If not persisted, the rotation will be immediately reset.
DispatchKeyA key up event8These arguments are the same as described by KeyEvent.

The source is always from the system keyboard.
DispatchFlipA keyboard flip event1Opens (1) or closes (0) the physical keyboard. This is equivalent to sliding open or close a keyboard on an old Android device that has a sliding keyboard, like on the HTC Desire, where the user would expect the screen to rotate.
DispatchPressPresses down a key and then immediately releases the key.1The key code. See the KeyEvent constants beginning with KEYCODE_ for the complete list.
LaunchActivityLaunches an activity2/31. The Android package name
2. The Activity’s class name
3. (Optional) the alarm time. This is only useful for simulating an alarm.
LaunchInstrumentationLaunches instrumentation, such as a test case.21. The test name
2. The runner name
UserWaitSleeps for a number of milliseconds11. The amount of time to wait, in milliseconds
LongPressA press-and-hold event. By default presses for 2 seconds0
PowerLogA special event for power measurement. Writes an event in the power log.1/21. The power log type
2. The test case status.
WriteLogWrites the power log to the SD card0
RunCmdExecutes a shell command11. The shell command
TapA tap event2/31. The X position
2. The Y position
3. (Optional) The duration to tap. This can convert the simple tap into a long press of any length.
ProfileWaitWaits for a preconfigured amount of time (default 5s)0
DeviceWakeUpTells the device to sleep and then wake up again0
DispatchStringInputs a string of text via the keyboard11. The text to input
PressAndHoldA press and hold event. This is like a Tap event but the duration is not optional.31. The X position
2. The Y position
3. The duration to hold
DragA drag event51. The starting X position
2. The starting Y position
3. The ending X position
4. The ending Y position
5. How many steps – this is how many intermediate moves there are between the start and the end positions.
PinchZoomA pinch to zoom event91. The first finger’s starting X position
2. The first finger’s starting Y position
3. The first finger’s ending X position
4. The first finger’s ending Y position
5. The second finger’s starting X position
6. The second finger’s starting Y position
7. The second finger’s ending X position
8. The second finger’s ending Y position
9. How many steps – this is how many intermediate moves there are between the start and the end positions.
StartCaptureFramerateCaptures the window framerate.
The system property viewancestor.profile_rendering must be set to true so that the window is rendered at 60hz.
EndCaptureFramerateEnds window framerate capturing11. The test case name
StartCaptureAppFramerateCaptures the framerate for a given app.
The system property viewancestor.profile_rendering must be set to true so that the window is rendered at 60hz.
11. The activity name
EndCaptureAppFramerateEnds app framerate capturing21. The activity name
2. The test case name

Executing the Script

Executing the script requires the use of the undocumented option -f. You first need to push the script to an accessible location on the device, e.g. /sdcard/. For example:

adb push myscript /sdcard/
adb shell monkey -f /sdcard/myscript 1

The ‘1’ argument at the end is the count option. It is required although it is ignored when running from a script, so you can substitute any positive number here.

Leave a Reply