http://developer.android.com/guide/developing/tools/monkeyrunner_concepts.html#APIClasses
A Simple monkeyrunner Program
# Imports the monkeyrunner modules used by this program
from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice
# Connects to the current device, returning a MonkeyDevice object
device = MonkeyRunner.waitForConnection()
# Installs the Android package. Notice that this method returns a boolean, so you can test
# to see if the installation worked.
device.installPackage('myproject/bin/MyApplication.apk')
# sets a variable with the package's internal name
package = 'com.example.android.myapplication'
# sets a variable with the name of an Activity in the package
activity = 'com.example.android.myapplication.MainActivity'
# sets the name of the component to start
runComponent = package + '/' + activity
# Runs the component
device.startActivity(component=runComponent)
# Presses the Menu button
device.press('KEYCODE_MENU', MonkeyDevice.DOWN_AND_UP)
# Takes a screenshot
result = device.takeSnapshot()
# Writes the screenshot to a file
result.writeToFile('myproject/shot1.png','png')
The monkeyrunner API
The monkeyrunner API is contained in three modules in the package com.android.monkeyrunner
:
MonkeyRunner
: A class of utility methods for monkeyrunner programs. This class provides a method for connecting monkeyrunner to a device or emulator. It also provides methods for creating UIs for a monkeyrunner program and for displaying the built-in help.MonkeyDevice
: Represents a device or emulator. This class provides methods for installing and uninstalling packages, starting an Activity, and sending keyboard or touch events to an application. You also use this class to run test packages.MonkeyImage
: Represents a screen capture image. This class provides methods for capturing screens, converting bitmap images to various formats, comparing two MonkeyImage objects, and writing an image to a file.
In a Python program, you access each class as a Python module. The monkeyrunner tool does not import these modules automatically. To import a module, use the Python from
statement:
from com.android.monkeyrunner import <module>
where <module>
is the class name you want to import. You can import more than one module in the same from
statement by separating the module names with commas.
MonkeyRunner
A monkeyrunner class that contains static utility methods.
Summary
Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
void | alert (string message, string title, string okTitle)
Displays an alert dialog to the process running the current program.
| ||||||||||
integer | choice (string message, iterable choices, string title)
Displays a dialog with a list of choices to the process running the current program.
| ||||||||||
void | help (string format)
Displays the monkeyrunner API reference in a style similar to that of Python's
pydoc tool, using the specified format.
| ||||||||||
string | input (string message, string initialValue, string title, string okTitle, string cancelTitle)
Displays a dialog that accepts input.
| ||||||||||
void | sleep (float seconds)
Pauses the current program for the specified number of seconds.
| ||||||||||
MonkeyDevice | waitForConnection (float timeout, string deviceId)
Tries to make a connection between the
monkeyrunner backend and the specified device or emulator.
|
Public Methods
string alert ( string message, string title, string okTitle)
Displays an alert dialog to the process running the current program. The dialog is modal, so the program pauses until the user clicks the dialog's button.
Arguments
message | The message to display in the dialog. |
---|---|
title | The dialog's title. The default value is "Alert". |
okTitle | The text displayed in the dialog button. The default value is "OK". |
integer choice (string message, iterable choices, string title)
Displays a dialog with a list of choices to the process running the current program. The dialog is modal, so the program pauses until the user clicks one of the dialog's buttons.
Arguments
message | The prompt message displayed in the dialog. |
---|---|
choices | A Python iterable containing one or more objects that are displayed as strings. The recommended form is an array of strings. |
title | The dialog's title. The default is "Input". |
Returns
- If the user makes a selection and clicks the "OK" button, the method returns the 0-based index of the selection within the iterable. If the user clicks the "Cancel" button, the method returns -1.
void help (string format)
Displays the monkeyrunner API reference in a style similar to that of Python's pydoc
tool, using the specified format.
Arguments
format | The markup format to use in the output. The possible values are "text" for plain text or "html" for HTML. |
---|
string input (string message string initialValue, string title, string okTitle, string cancelTitle)
Displays a dialog that accepts input and returns it to the program. The dialog is modal, so the program pauses until the user clicks one of the dialog's buttons.
The dialog contains two buttons, one of which displays the okTitle value and the other the cancelTitle value. If the user clicks the okTitle button, the current value of the input box is returned. If the user clicks the cancelTitle button, an empty string is returned.
Arguments
message | The prompt message displayed in the dialog. |
---|---|
initialValue | The initial value to display in the dialog. The default is an empty string. |
title | The dialog's title. The default is "Input". |
okTitle | The text displayed in the okTitle button. The default is "OK". |
cancelTitle | The text displayed in the cancelTitle button. The default is "Cancel". |
Returns
- If the user clicks the okTitle button, then the method returns the current value of the dialog's input box. If the user clicks the cancelTitle button, the method returns an empty string.
void sleep ( float seconds )
Pauses the current program for the specified number of seconds.
Arguments
seconds | The number of seconds to pause. |
---|
MonkeyDevice
waitForConnection (float timeout, string deviceId)
Tries to make a connection between the monkeyrunner
backend and the specified device or emulator.
Arguments
timeout | The number of seconds to wait for a connection. The default is to wait forever. |
---|---|
deviceId | A regular expression that specifies the serial number of the device or emulator. See the topic Android Debug Bridge for a description of device and emulator serial numbers. |
Returns
- A
MonkeyDevice
instance for the device or emulator. Use this object to control and communicate with the device or emulator.
MonkeyDevice
A monkeyrunner class that represents a device or emulator accessible by the workstation running monkeyrunner
.
This class is used to control an Android device or emulator. The methods send UI events, retrieve information, install and remove applications, and run applications.
You normally do not have to create an instance of MonkeyDevice
. Instead, you use MonkeyRunner.waitForConnection()
to create a new object from a connection to a device or emulator. For example, instead of using:
newdevice = MonkeyDevice()
you would use:
newdevice = MonkeyRunner.waitForConnection()
Summary
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
string | DOWN | Use this with the type argument of press() or touch() to send a DOWN event. | |||||||||
string | UP | Use this with the type argument of press() or touch() to send an UP event. | |||||||||
string | DOWN_AND_UP | Use this with the type argument of press() or touch() to send a DOWN event immediately followed by an UP event. |
Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
void | broadcastIntent (string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, iterable flags)
Broadcasts an Intent to this device, as if the Intent were coming from an application.
| ||||||||||
void | drag (tuple start, tuple end, float duration, integer steps)
Simulates a drag gesture (touch, hold, and move) on this device's screen.
| ||||||||||
object | getProperty (string key)
Given the name of a system environment variable, returns its value for this device. The available variable names are listed in the
detailed description of this method.
| ||||||||||
object | getSystemProperty (string key)
. The API equivalent of
adb shell getprop <key>. This is provided for use by platform developers.
| ||||||||||
void | installPackage (string path)
Installs the Android application or test package contained in packageFile onto this device. If the application or test package is already installed, it is replaced.
| ||||||||||
dictionary | instrument (string className, dictionary args)
Runs the specified component under Android instrumentation, and returns the results in a dictionary whose exact format is dictated by the component being run. The component must already be present on this device.
| ||||||||||
void | press (string name, dictionary type)
Sends the key event specified by type to the key specified by keycode.
| ||||||||||
void | reboot (string into)
Reboots this device into the bootloader specified by bootloadType.
| ||||||||||
void | removePackage (string package)
Deletes the specified package from this device, including its data and cache.
| ||||||||||
object | shell (string cmd)
Executes an
adb shell command and returns the result, if any.
| ||||||||||
void | startActivity (string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, flags)
Starts an Activity on this device by sending an Intent constructed from the supplied arguments.
| ||||||||||
MonkeyImage | takeSnapshot()
Captures the entire screen buffer of this device, yielding a
MonkeyImage object containing a screen capture of the current display.
| ||||||||||
void | touch (integer x, integer y, integer type)
Sends a touch event specified by type to the screen location specified by x and y.
| ||||||||||
void | type (string message)
Sends the characters contained in message to this device, as if they had been typed on the device's keyboard. This is equivalent to calling
press() for each keycode in
message using the key event type
DOWN_AND_UP .
| ||||||||||
void | wake ()
Wakes the screen of this device.
|
Constants
string DOWN
string UP
string DOWN_AND_UP
Public Methods
void broadcastIntent ( string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, iterable flags)
Broadcasts an Intent to this device, as if the Intent were coming from an application. See Intent
for more information about the arguments.
Arguments
uri | The URI for the Intent. (see Intent.setData() ). |
---|---|
action | The action for this Intent (see Intent.setAction() ). |
data | The data URI for this Intent (see Intent.setData() ). |
mimetype | The MIME type for the Intent (see Intent.setType() ). |
categories | An iterable data structure containing strings that define categories for this Intent (see Intent.addCategory() ). |
extras | A dictionary of extra data for this Intent (see Intent.putExtra() for an example). The key for each dictionary item should be a string. The item's value can be any simple or structured data type. |
component | The component for this Intent (see ComponentName ). Using this argument will direct the Intent to a specific class within a specific Android package. |
flags | An iterable data structure containing flags that control how the Intent is handled (see Intent.setFlags() ). |
void drag ( tuple start, tuple end, float duration, integer steps)
Simulates a drag gesture (touch, hold, and move) on this device's screen.
Arguments
start | The starting point of the drag gesture, in the form of a tuple (x,y) where x and y are integers. |
---|---|
end | The end point of the drag gesture, in the form of a tuple (x,y) where x and y are integers. |
duration | The duration of the drag gesture in seconds. The default is 1.0 seconds. |
steps | The number of steps to take when interpolating points. The default is 10. |
object getProperty (string key)
Given the name of a system environment variable, returns its value for this device.
Arguments
key | The name of the system environment variable. The available variable names are listed in Table 1. Property variable names at the end of this topic. |
---|
Returns
- The value of the variable. The data format varies according to the variable requested.
object getSystemProperty (string key)
Synonym for getProperty()
.
Arguments
key | The name of the system environment variable. The available variable names are listed in Table 1. Property Variable Names. |
---|
Returns
- The value of the variable. The data format varies according to the variable requested.
void installPackage (string path)
Installs the Android application or test package contained in packageFile onto this device. If the application or test package is already installed, it is replaced.
Arguments
path | The fully-qualified path and filename of the .apk file to install. |
---|
dictionary instrument ( string className, dictionary args)
Runs the specified component with Android instrumentation, and returns the results in a dictionary whose exact format is dictated by the component being run. The component must already be present on this device.
Use this method to start a test case that uses one of Android's test case classes. See Testing Fundamentals to learn more about unit testing with the Android testing framework.
Arguments
className | The name of an Android component that is already installed on this device, in the standard form packagename/classname, where packagename is the Android package name of a .apk file on this device, and classname is the class name of an Android component (Activity, ContentProvider, Service, or BroadcastReceiver) in that file. Both packagename and classname must be fully qualified. See ComponentName for more details. |
---|---|
args | A dictionary containing flags and their values. These are passed to the component as it is started. If the flag does not take a value, set its dictionary value to an empty string. |
Returns
-
A dictionary containing the component's output. The contents of the dictionary are defined by the component itself.
If you use
InstrumentationTestRunner
as the class name in the componentName argument, then the result dictionary contains the single key "stream". The value of "stream" is a string containing the test output, as ifInstrumentationTestRunner
was run from the command line. The format of this output is described in Testing in Other IDEs.
void press (string name, integer type)
Sends the key event specified by type
to the key specified by keycode
.
Arguments
name | The name of the keycode to send. See KeyEvent for a list of keycode names. Use the keycode name, not its integer value. |
---|---|
type | The type of key event to send. The allowed values are DOWN , UP , and DOWN_AND_UP . |
void reboot (string bootloadType)
Reboots this device into the bootloader specified by bootloadType
.
Arguments
into | The type of bootloader to reboot into. The allowed values are "bootloader", "recovery", or "None". |
---|
void removePackage (string package)
Deletes the specified package from this device, including its data and cache.
Arguments
package | The Android package name of an .apk file on this device. |
---|
object shell (string cmd)
Executes an adb
shell command and returns the result, if any.
Arguments
cmd | The command to execute in the adb shell. The form of these commands is described in the topic Android Debug Bridge. |
---|
Returns
- The results of the command, if any. The format of the results is determined by the command.
void startActivity ( string uri, string action, string data, string mimetype, iterable categories dictionary extras, component component, iterable flags)
Starts an Activity on this device by sending an Intent constructed from the supplied arguments.
Arguments
uri | The URI for the Intent. (see Intent.setData() ). |
---|---|
action | The action for the Intent (see Intent.setAction() ). |
data | The data URI for the Intent (see Intent.setData() ). |
mimetype | The MIME type for the Intent (see Intent.setType() ). |
categories | An iterable data structure containing strings that define categories for the Intent (see Intent.addCategory() ). |
extras | A dictionary of extra data for the Intent (see Intent.putExtra() for an example). The key for each dictionary item should be a string. The item's value can be any simple or structured data type. |
component | The component for the Intent (see ComponentName ). Using this argument will direct the Intent to a specific class within a specific Android package. |
flags | An iterable data structure containing flags that control how the Intent is handled (see Intent.setFlags() ). |
MonkeyImage
takeSnapshot ()
Captures the entire screen buffer of this device, yielding a screen capture of the current display.
Returns
- A MonkeyImage object containing the image of the current display.
void touch ( integer x, integer y, string type)
Sends a touch event specified by type to the screen location specified by x and y.
Arguments
x | The horizontal position of the touch in actual device pixels, starting from the left of the screen in its current orientation. |
---|---|
y | The vertical position of the touch in actual device pixels, starting from the top of the screen in its current orientation. |
type | The type of key event to send. The allowed values are DOWN , UP , and DOWN_AND_UP . |
void type (string message)
Sends the characters contained in message to this device, as if they had been typed on the device's keyboard. This is equivalent to calling press()
for each keycode in message
using the key event type DOWN_AND_UP
.
Arguments
message | A string containing the characters to send. |
---|
void wake ()
Wakes the screen of this device.
Appendix
Table 1.Property variable names used with getProperty() and getSystemProperty().
Property Group | Property | Description | Notes |
---|---|---|---|
build | board | Code name for the device's system board | See Build |
brand | The carrier or provider for which the OS is customized. | ||
device | The device design name. | ||
fingerprint | A unique identifier for the currently-running build. | ||
host | |||
ID | A changelist number or label. | ||
model | The end-user-visible name for the device. | ||
product | The overall product name. | ||
tags | Comma-separated tags that describe the build, such as "unsigned" and "debug". | ||
type | The build type, such as "user" or "eng". | ||
user | |||
CPU_ABI | The name of the native code instruction set, in the form CPU type plus ABI convention. | ||
manufacturer | The product/hardware manufacturer. | ||
version.incremental | The internal code used by the source control system to represent this version of the software. | ||
version.release | The user-visible name of this version of the software. | ||
version.sdk | The user-visible SDK version associated with this version of the OS. | ||
version.codename | The current development codename, or "REL" if this version of the software has been released. | ||
display | width | The device's display width in pixels. | See DisplayMetrics for details. |
height | The device's display height in pixels. | ||
density | The logical density of the display. This is a factor that scales DIP (Density-Independent Pixel) units to the device's resolution. DIP is adjusted so that 1 DIP is equivalent to one pixel on a 160 pixel-per-inch display. For example, on a 160-dpi screen, density = 1.0, while on a 120-dpi screen, density = .75. The value does not exactly follow the real screen size, but is adjusted to conform to large changes in the display DPI. See | ||
am.current | package | The Android package name of the currently running package. | The am.current keys return information about the currently-running Activity. |
action | The current activity's action. This has the same format as the name attribute of the action element in a package manifest. | ||
comp.class | The class name of the component that started the current Activity. See comp.package for more details. | ||
comp.package | The package name of the component that started the current Activity. A component is specified by a package name and the name of class that the package contains. | ||
data | The data (if any) contained in the Intent that started the current Activity. | ||
categories | The categories specified by the Intent that started the current Activity. | ||
clock | realtime | The number of milliseconds since the device rebooted, including deep-sleep time. | See SystemClock for more information. |
uptime | The number of milliseconds since the device rebooted, not including deep-sleep time | ||
millis | current time since the UNIX epoch, in milliseconds. |
MonkeyImage
A monkeyrunner class to hold an image of the device or emulator's screen. The image is copied from the screen buffer during a screenshot. This object's methods allow you to convert the image into various storage formats, write the image to a file, copy parts of the image, and compare this object to other MonkeyImage
objects.
You do not need to create new instances of MonkeyImage
. Instead, use MonkeyDevice.takeSnapshot()
to create a new instance from a screenshot. For example, use:
newimage = MonkeyDevice.takeSnapshot()
Summary
Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
string | convertToBytes (string format)
Converts the current image to a particular format and returns it as a
string that you can then access as an
iterable of binary bytes.
| ||||||||||
tuple | getRawPixel (integer x, integer y)
Returns the single pixel at the image location (x,y), as an a
tuple of
integer, in the form (a,r,g,b).
| ||||||||||
integer | getRawPixelInt (integer x, integer y)
Returns the single pixel at the image location (x,y), as a 32-bit
integer.
| ||||||||||
MonkeyImage | getSubImage (tuple rect)
Creates a new
MonkeyImage object from a rectangular selection of the current image.
| ||||||||||
boolean | sameAs (MonkeyImage other, float percent)
Compares this
MonkeyImage object to another and returns the result of the comparison. The
percent argument specifies the percentage difference that is allowed for the two images to be "equal".
| ||||||||||
void | writeToFile (string path, string format)
Writes the current image to the file specified by
filename , in the format specified by
format .
|
Public Methods
string convertToBytes ( string format)
Converts the current image to a particular format and returns it as a string that you can then access as an iterable of binary bytes.
Arguments
format | The desired output format. All of the common raster output formats are supported. The default value is "png" (Portable Network Graphics). |
---|
tuple getRawPixel (integer x, integer y)
Returns the single pixel at the image location (x,y), as an a tuple of integer, in the form (a,r,g,b).
Arguments
x | The horizontal position of the pixel, starting with 0 at the left of the screen in the orientation it had when the screenshot was taken. |
---|---|
y | The vertical position of the pixel, starting with 0 at the top of the screen in the orientation it had when the screenshot was taken. |
Returns
- A tuple of integers representing the pixel, in the form (a,r,g,b) where a is the alpha channel value, and r, g, and b are the red, green, and blue values, respectively.
tuple getRawPixelInt (integer x, integer y)
Returns the single pixel at the image location (x,y), as an an integer. Use this method to economize on memory.
Arguments
x | The horizontal position of the pixel, starting with 0 at the left of the screen in the orientation it had when the screenshot was taken. |
---|---|
y | The vertical position of the pixel, starting with 0 at the top of the screen in the orientation it had when the screenshot was taken. |
Returns
- The a,r,g, and b values of the pixel as 8-bit values combined into a 32-bit integer, with a as the leftmost 8 bits, r the next rightmost, and so forth.
MonkeyImage
getSubImage (tuple rect)
Creates a new MonkeyImage
object from a rectangular selection of the current image.
Arguments
rect | A tuple (x, y, w, h) specifying the selection. x and y specify the 0-based pixel position of the upper left-hand corner of the selection. w specifies the width of the region, and h specifies its height, both in units of pixels. The image's orientation is the same as the screen orientation at the time the screenshot was made. |
---|
Returns
- A new
MonkeyImage
object containing the selection.
boolean sameAs ( MonkeyImage
otherImage, float percent )
Compares this MonkeyImage
object to another and returns the result of the comparison. The percent
argument specifies the percentage difference that is allowed for the two images to be "equal".
Arguments
other | Another MonkeyImage object to compare to this one. |
---|---|
percent | A float in the range 0.0 to 1.0, inclusive, indicating the percentage of pixels that need to be the same for the method to return true . The default is 1.0, indicating that all the pixels must match. |
Returns
- Boolean
true
if the images match, or booleanfalse
otherwise.
void writeToFile (string filename, string format)
Writes the current image to the file specified by filename
, in the format specified by format
.
Arguments
path | The fully-qualified filename and extension of the output file. |
---|---|
format | The output format to use for the file. If no format is provided, then the method tries to guess the format from the filename's extension. If no extension is provided and no format is specified, then the default format of "png" (Portable Network Graphics) is used. |