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:
EventKeyword(arg1,arg2,arg3,arg4,arg5,...)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:
| Event | Description | # Args | Arguments |
|---|---|---|---|
| DispatchPointer & DispatchTrackball | A touch or a trackball event | 12/13 | These 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. |
| RotateScreen | Rotates the screen | 2 | 1. 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. |
| DispatchKey | A key up event | 8 | These arguments are the same as described by KeyEvent. The source is always from the system keyboard. |
| DispatchFlip | A keyboard flip event | 1 | Opens (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. |
| DispatchPress | Presses down a key and then immediately releases the key. | 1 | The key code. See the KeyEvent constants beginning with KEYCODE_ for the complete list. |
| LaunchActivity | Launches an activity | 2/3 | 1. The Android package name 2. The Activity’s class name 3. (Optional) the alarm time. This is only useful for simulating an alarm. |
| LaunchInstrumentation | Launches instrumentation, such as a test case. | 2 | 1. The test name 2. The runner name |
| UserWait | Sleeps for a number of milliseconds | 1 | 1. The amount of time to wait, in milliseconds |
| LongPress | A press-and-hold event. By default presses for 2 seconds | 0 | |
| PowerLog | A special event for power measurement. Writes an event in the power log. | 1/2 | 1. The power log type 2. The test case status. |
| WriteLog | Writes the power log to the SD card | 0 | |
| RunCmd | Executes a shell command | 1 | 1. The shell command |
| Tap | A tap event | 2/3 | 1. 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. |
| ProfileWait | Waits for a preconfigured amount of time (default 5s) | 0 | |
| DeviceWakeUp | Tells the device to sleep and then wake up again | 0 | |
| DispatchString | Inputs a string of text via the keyboard | 1 | 1. The text to input |
| PressAndHold | A press and hold event. This is like a Tap event but the duration is not optional. | 3 | 1. The X position 2. The Y position 3. The duration to hold |
| Drag | A drag event | 5 | 1. 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. |
| PinchZoom | A pinch to zoom event | 9 | 1. 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. |
| StartCaptureFramerate | Captures the window framerate. The system property viewancestor.profile_rendering must be set to true so that the window is rendered at 60hz. | 0 | |
| EndCaptureFramerate | Ends window framerate capturing | 1 | 1. The test case name |
| StartCaptureAppFramerate | Captures 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. | 1 | 1. The activity name |
| EndCaptureAppFramerate | Ends app framerate capturing | 2 | 1. 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 1The ‘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