Intro to Android MonkeyRunner MonkeyDevice and MonkeyImage Functions

Most software products usually have a programmatic automation of input and output interface, which facilitate the monkey test.

With these interface, the product can be fully tested under various user input conditions.

For Android development, there is a tool called monkey which can be executed in adb shell, that does pure random event generation.

Also, Android has a more flex framework called monkeyrunner for controllable user action.

Script used by monkeyrunner is based on Jython, which is friendly to both java and python. With monkeyrunner, we can connect to a device, execute commands, start app, send keystroke, or simulate touch event to the device/app, and take snapshot of the screen.

If functions provided by monkeyrunner and python are not good enough, we can also create our own custom extension.

Monkey Runner Function Introduction

There are three main classes: MonkeyRunner, MonkeyDevice, and MonkeyImage. Here we give a brief introduction to mainly used functions.

1. MonkeyRunner Function

• waitForConnection – A monkey device object is returned by this function. This should be called at the very beginning, and execution of the script will be blocked until a device is connected to the host machine.
• sleep – Sleep and pause the execution of script by seconds.
• alert – Show an alert message in host screen.
• choice – Show a list in host screen, and return the index selected by the user.
• loadImageFromFile – Load image from file into a MonekeyImage object. This method is not listed in the webpage.

2. MonkeyDevice Function

• getProperty/getSystemProperty – Get the content of system environment variable.
• installPackage/removePackage – Install or remove a package into the device.
• startActivity – Start an activity.
• shell – Execute a command in adb shell.
• type – Feed a sequence of key press events to the device.
• touch – Send a touch event to given coordinate of the device.
• drag – Send a drag gesture (press, move, and release) to the device.
• takeSnapshot – Take a snapshot of current screen and return as a MonkeyImage object.

Notice for touch and drag: For some unknown reason, when send event to some app (most likely graphic games), touch or drag may not be correctly recognized. In this case, we can manually send out these corresponding events: press (MonkeyDevice.DOWN), release (MonkeyDevice.UP), and move (MonkeyDevice.MOVE) via touch function.

3. MonkeyImage Function

• getRawPixel/getRawPixelInt – Get the color for given coordinate, return by a tuple of a, r, g, b or integer..
• getSubImage – Get a new MonkeyImage object for given sub image.
• sameAs – Determinate whether two MonkeyImage object have the same content. A percentage argument can be used to allow some difference pixel to be exist while considering two image to be the “same”. Please note that it is a pixel by pixel comparison routine, not a visual comparison. Do not use this function for object/pattern recognition, but only for pixel match.
• writeToFile – Write the content of image into file with provided encoding.

Run the Monkeyrunner

• Script for monkeyrunner exists in adt-bundle-path\sdk\tools.
• Just run user script with monkeyrunner myscript.py.
• There maybe connection (getProperty) or timeout (takeSnapShot) issue when running monkeyrunner, so please add try-catch when necessary.

Have fun with monkeyrunner

With monkeyrunner, we can do many interesting things as we can manipulate the phone from the side of host PC.

One of my favorite, I always enjoy creating agent/robot for puzzle solving games. As input and output function are covered by monkeyrunner, there is no equipment cost.

Also, snapshot quality is way better than that of camera’s, and this will facilitate the object recognition. Bad side of this is that, we can not do real time capture and feedback, and in order to lower the battery consumption, we usually need to slow down the capture frequency. In general, this a good place to implement and test the quality of AI/search algorithm.

As a final word, please do not do any evil things using monkeyrunner.