From a7fda21c8298d8f316564280d702206147207005 Mon Sep 17 00:00:00 2001 From: Joe Malin Date: Mon, 18 Oct 2010 17:07:45 -0700 Subject: DO NOT MERGE: Doc Change: Documentation for MonkeyRunner tool Change-Id: I049c5f70c47077c51fefbae32633592e80068df2 --- docs/html/guide/developing/tools/MonkeyDevice.jd | 1353 ++++++++++++++++++++ docs/html/guide/developing/tools/MonkeyImage.jd | 435 +++++++ docs/html/guide/developing/tools/MonkeyRunner.jd | 445 +++++++ docs/html/guide/developing/tools/index.jd | 70 +- .../developing/tools/monkeyrunner_concepts.jd | 308 +++++ 5 files changed, 2576 insertions(+), 35 deletions(-) create mode 100644 docs/html/guide/developing/tools/MonkeyDevice.jd create mode 100644 docs/html/guide/developing/tools/MonkeyImage.jd create mode 100644 docs/html/guide/developing/tools/MonkeyRunner.jd create mode 100644 docs/html/guide/developing/tools/monkeyrunner_concepts.jd (limited to 'docs/html/guide/developing') diff --git a/docs/html/guide/developing/tools/MonkeyDevice.jd b/docs/html/guide/developing/tools/MonkeyDevice.jd new file mode 100644 index 0000000..34bbba9 --- /dev/null +++ b/docs/html/guide/developing/tools/MonkeyDevice.jd @@ -0,0 +1,1353 @@ +page.title=MonkeyDevice +@jd:body + +

+ 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
stringDOWN + Use this with the type argument of + press() or touch() + + to send a DOWN event. +
stringUP + Use this with the type argument of + press() or touch() + + to send an UP event. +
stringDOWN_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 +

+
+
+

+ press() or + touch() value. + Specifies that a DOWN event type should be sent to the device, corresponding to + pressing down on a key or touching the screen. +

+
+
+
+ +
+

+ + string + + UP +

+
+
+

+ press() or + touch() value. + Specifies that an UP event type should be sent to the device, corresponding to + releasing a key or lifting up from the screen. +

+
+
+
+ + +
+

+ + string + + DOWN_AND_UP +

+
+
+

+ press(), + touch() or + type() value. + Specifies that a DOWN event type followed by an UP event type should be sent to the + device, corresponding to typing a key or clicking the screen. +

+
+
+
+ + +

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 {@link android.content.Intent Intent} for more information about the + arguments. +

+
+
+
Arguments
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
uri + The URI for the Intent. + (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). +
action + The action for this Intent + (see {@link android.content.Intent#setAction(java.lang.String) Intent.setAction()}). +
data + The data URI for this Intent + (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). +
mimetype + The MIME type for the Intent + (see {@link android.content.Intent#setType(java.lang.String) Intent.setType()}). +
categories + An iterable data structure containing strings that define categories for this + Intent + (see + {@link android.content.Intent#addCategory(java.lang.String) Intent.addCategory()}). +
extras + A dictionary of extra data for this Intent + (see {@link android.content.Intent#putExtra(java.lang.String,java.lang.String) + 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 {@link android.content.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 {@link android.content.Intent#setFlags(int) 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. +
durationThe duration of the drag gesture in seconds. The default is 1.0 seconds.
stepsThe 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 + {@link android.content.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 {@link android.test.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 if InstrumentationTestRunner 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 {@link android.view.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 {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). +
action + The action for the Intent + (see {@link android.content.Intent#setAction(java.lang.String) Intent.setAction()}). +
data + The data URI for the Intent + (see {@link android.content.Intent#setData(android.net.Uri) Intent.setData()}). +
mimetype + The MIME type for the Intent + (see {@link android.content.Intent#setType(java.lang.String) Intent.setType()}). +
categories + An iterable data structure containing strings that define categories for the + Intent + (see + {@link android.content.Intent#addCategory(java.lang.String) Intent.addCategory()}). +
extras + A dictionary of extra data for the Intent + (see + {@link android.content.Intent#putExtra(java.lang.String,java.lang.String) + 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 {@link android.content.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 {@link android.content.Intent#setFlags(int) 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 +
buildboardCode name for the device's system board + See {@link android.os.Build} +
brandThe carrier or provider for which the OS is customized.
deviceThe device design name.
fingerprintA unique identifier for the currently-running build.
host
IDA changelist number or label.
modelThe end-user-visible name for the device.
productThe overall product name.
tagsComma-separated tags that describe the build, such as "unsigned" and "debug".
typeThe 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. +
manufacturerThe product/hardware manufacturer.
version.incremental + The internal code used by the source control system to represent this version + of the software. +
version.releaseThe user-visible name of this version of the software.
version.sdkThe 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. +
displaywidthThe device's display width in pixels. + See + {@link android.util.DisplayMetrics} for details. +
heightThe 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 + {@link android.util.DisplayMetrics#density} for more details. +

+
am.currentpackageThe 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. +
dataThe data (if any) contained in the Intent that started the current Activity.
categoriesThe categories specified by the Intent that started the current Activity.
clockrealtime + The number of milliseconds since the device rebooted, including deep-sleep + time. + + See {@link android.os.SystemClock} for more information. +
uptime + The number of milliseconds since the device rebooted, not including + deep-sleep time +
milliscurrent time since the UNIX epoch, in milliseconds.
diff --git a/docs/html/guide/developing/tools/MonkeyImage.jd b/docs/html/guide/developing/tools/MonkeyImage.jd new file mode 100644 index 0000000..ae85cb5 --- /dev/null +++ b/docs/html/guide/developing/tools/MonkeyImage.jd @@ -0,0 +1,435 @@ +page.title=MonkeyImage +@jd:body + + +

+ 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 boolean false 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. +
+
+
+
diff --git a/docs/html/guide/developing/tools/MonkeyRunner.jd b/docs/html/guide/developing/tools/MonkeyRunner.jd new file mode 100644 index 0000000..871e06d --- /dev/null +++ b/docs/html/guide/developing/tools/MonkeyRunner.jd @@ -0,0 +1,445 @@ +page.title=MonkeyRunner +@jd:body + +

+ 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. +
    • +
+
+
+
diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd index 6e9fde1..0e10377 100644 --- a/docs/html/guide/developing/tools/index.jd +++ b/docs/html/guide/developing/tools/index.jd @@ -3,27 +3,27 @@ page.title=Tools Overview -

The Android SDK includes a variety of custom tools that help you develop mobile -applications on the Android platform. The most important of these are the Android -Emulator and the Android Development Tools plugin for Eclipse, but the SDK also -includes a variety of other tools for debugging, packaging, and installing your +

The Android SDK includes a variety of custom tools that help you develop mobile +applications on the Android platform. The most important of these are the Android +Emulator and the Android Development Tools plugin for Eclipse, but the SDK also +includes a variety of other tools for debugging, packaging, and installing your applications on the emulator.

- +
Android Development Tools Plugin (for the Eclipse IDE)
-
The ADT plugin adds powerful extensions to the Eclipse integrated environment, - making creating and debugging your Android applications easier and faster. If you - use Eclipse, the ADT plugin gives you an incredible boost in developing Android +
The ADT plugin adds powerful extensions to the Eclipse integrated environment, + making creating and debugging your Android applications easier and faster. If you + use Eclipse, the ADT plugin gives you an incredible boost in developing Android applications.
Android Emulator
-
A QEMU-based device-emulation tool that you can use to design, +
A QEMU-based device-emulation tool that you can use to design, debug, and test your applications in an actual Android run-time environment.
Android Virtual Devices (AVDs)
Virtual device configurations that you create, to model device characteristics in the Android Emulator. In each configuration, you can specify the Android platform to run, the hardware options, and the - emulator skin to use. Each AVD functions as an independent device with + emulator skin to use. Each AVD functions as an independent device with it's own storage for user data, SD card, and so on.
Hierarchy Viewer
@@ -37,53 +37,53 @@ applications on the emulator.

efficiency. -
Draw 9-patch
-
The Draw 9-patch tool allows you to easily create a - {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched - versions of the image, and highlights the area in which content is allowed. -
+
Draw 9-patch
+
The Draw 9-patch tool allows you to easily create a + {@link android.graphics.NinePatch} graphic using a WYSIWYG editor. It also previews stretched + versions of the image, and highlights the area in which content is allowed. +
-
Dalvik Debug Monitor +
Dalvik Debug Monitor Service (ddms)
-
Integrated with Dalvik, the Android platform's custom VM, this tool - lets you manage processes on an emulator or device and assists in debugging. - You can use it to kill processes, select a specific process to debug, - generate trace data, view heap and thread information, take screenshots - of the emulator or device, and more.
- +
Integrated with Dalvik, the Android platform's custom VM, this tool + lets you manage processes on an emulator or device and assists in debugging. + You can use it to kill processes, select a specific process to debug, + generate trace data, view heap and thread information, take screenshots + of the emulator or device, and more.
+
Android Debug Bridge (adb)
-
The adb tool lets you install your application's .apk files on an - emulator or device and access the emulator or device from a command line. - You can also use it to link a standard debugger to application code running +
The adb tool lets you install your application's .apk files on an + emulator or device and access the emulator or device from a command line. + You can also use it to link a standard debugger to application code running on an Android emulator or device.
-
Android Asset +
Android Asset Packaging Tool (aapt)
-
The aapt tool lets you create .apk files containing the binaries and +
The aapt tool lets you create .apk files containing the binaries and resources of Android applications.
-
Android Interface +
Android Interface Description Language (aidl)
Lets you generate code for an interprocess interface, such as what a service might use.
sqlite3
-
Included as a convenience, this tool lets you access the SQLite data +
Included as a convenience, this tool lets you access the SQLite data files created and used by Android applications.
Traceview
-
This tool produces graphical analysis views of trace log data that you +
This tool produces graphical analysis views of trace log data that you can generate from your Android application.
mksdcard
-
Helps you create a disk image that you can use with the emulator, +
Helps you create a disk image that you can use with the emulator, to simulate the presence of an external storage card (such as an SD card).
dx
-
The dx tool rewrites .class bytecode into Android bytecode +
The dx tool rewrites .class bytecode into Android bytecode (stored in .dex files.)
-
UI/Application +
UI/Application Exerciser Monkey
The Monkey is a program that runs on your emulator or device and generates pseudo-random streams of user events such as clicks, touches, or gestures, as well as a number of system- @@ -92,9 +92,9 @@ efficiency.
android
A script that lets you manage AVDs and generate Ant build files that + href="http://ant.apache.org/" title="Ant">Ant build files that you can use to compile your Android applications.
- +
zipalign
An important .apk optimization tool. This tool ensures that all uncompressed data starts with a particular alignment relative to the start of the file. This should always be used diff --git a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd new file mode 100644 index 0000000..1838905 --- /dev/null +++ b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd @@ -0,0 +1,308 @@ +page.title=monkeyrunner +@jd:body + + +

+ The monkeyrunner tool provides an API for writing programs that control an Android device + or emulator from outside of Android code. With monkeyrunner, you can write a Python program + that installs an Android application or test package, runs it, sends keystrokes to it, + takes screenshots of its user interface, and stores screenshots on the workstation. The + monkeyrunner tool is primarily designed to test applications and devices at the + functional/framework level and for running unit test suites, but you are free to use it for + other purposes. +

+

+ The monkeyrunner tool is not related to the + UI/Application Exerciser Monkey, + also known as the monkey tool. The monkey tool runs in an + adb shell directly on the + device or emulator and generates pseudo-random streams of user and system events. In comparison, + the monkeyrunner tool controls devices and emulators from a workstation by sending specific + commands and events from an API. +

+

+ The monkeyrunner tool provides these unique features for Android testing: +

+
    +
  • + Multiple device control: The monkeyrunner API can apply one or more + test suites across multiple devices or emulators. You can physically attach all the devices + or start up all the emulators (or both) at once, connect to each one in turn + programmatically, and then run one or more tests. You can also start up an emulator + configuration programmatically, run one or more tests, and then shut down the emulator. +
    • +
  • + Functional testing: monkeyrunner can run an automated start-to-finish test of an Android + application. You provide input values with keystrokes or touch events, and view the results + as screenshots. +
    • +
  • + Regression testing - monkeyrunner can test application stability by running an application + and comparing its output screenshots to a set of screenshots that are known to be correct. +
    • +
  • + Extensible automation - Since monkeyrunner is an API toolkit, you can develop an entire + system of Python-based modules and programs for controlling Android devices. Besides using + the monkeyrunner API itself, you can use the standard Python + os and + subprocess + modules to call Android tools such as + Android Debug Bridge. +

    + You can also add your own classes to the monkeyrunner API. This is described + in more detail in the section + Extending monkeyrunner with plugins. +

    +
    • +
+

+ The monkeyrunner tool uses Jython, a + implementation of Python that uses the Java programming language. Jython allows the + monkeyrunner API to interact easily with the Android framework. With Jython you can + use Python syntax to access the constants, classes, and methods of the API. +

+ +

A Simple monkeyrunner Program

+

+ Here is a simple monkeyrunner program that connects to a device, creating a + MonkeyDevice + object. Using the MonkeyDevice object, the program installs an Android application + package, runs one of its activities, and sends key events to the activity. + The program then takes a screenshot of the result, creating a + MonkeyImage object. + From this object, the program writes out a .png file containing the screenshot. +

+
+# 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')
+
+# Runs an activity in the application
+device.startActivity(component='com.example.android.myapplication.MainActivity')
+
+# Presses the Menu button
+device.press('KEYCODE_MENU','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. +

+

Running monkeyrunner

+

+ You can either run monkeyrunner programs from a file, or enter monkeyrunner statements in + an interactive session. You do both by invoking the monkeyrunner command + which is found in the tools/ subdirectory of your SDK directory. + If you provide a filename as an argument, the monkeyrunner command + runs the file's contents as a Python program; otherwise, it starts an interactive session. +

+

+ The syntax of the monkeyrunner command is +

+
+monkeyrunner -plugin <plugin_jar> <program_filename> <program_options>
+
+

+Table 1 explains the flags and arguments. +

+

+ Table 1. monkeyrunner flags and arguments.

+ + + + + + + + + + + + + + + + + + +
ArgumentDescription
+ + -plugin <plugin_jar> + + + (Optional) Specifies a .jar file containing a plugin for monkeyrunner. + To learn more about monkeyrunner plugins, see + Extending monkeyrunner with plugins. To specify more than one + file, include the argument multiple times. +
+ + <program_filename> + + + If you provide this argument, the monkeyrunner command runs the contents + of the file as a Python program. If the argument is not provided, the command starts an + interactive session. +
+ <program_options> + + (Optional) Flags and arguments for the program in <program_file>. +
+

monkeyrunner Built-in Help

+

+ You can generate an API reference for monkeyrunner by running: +

+
+monkeyrunner <format> help.py <outfile>
+
+

+The arguments are: +

+
    +
  • + <format> is either text for plain text output + or html for HTML output. +
    • +
  • + <outfile> is a path-qualified name for the output file. +
    • +
+

Extending monkeyrunner with Plugins

+

+ You can extend the monkeyrunner API with classes you write in the Java programming language + and build into one or more .jar files. You can use this feature to extend the + monkeyrunner API with your own classes or to extend the existing classes. You can also use this + feature to initialize the monkeyrunner environment. +

+

+ To provide a plugin to monkeyrunner, invoke the monkeyrunner command with the + -plugin <plugin_jar> argument described in + table 1. +

+

+ In your plugin code, you can import and extend the the main monkeyrunner classes + MonkeyDevice, MonkeyImage, and MonkeyRunner in + com.android.monkeyrunner (see The monkeyrunner API). +

+

+ Note that plugins do not give you access to the Android SDK. You can't import packages + such as com.android.app. This is because monkeyrunner interacts with the + device or emulator below the level of the framework APIs. +

+

The plugin startup class

+

+ The .jar file for a plugin can specify a class that is instantiated before + script processing starts. To specify this class, add the key + MonkeyRunnerStartupRunner to the .jar file's + manifest. The value should be the name of the class to run at startup. The following + snippet shows how you would do this within an ant build script: +

+
+<jar jarfile="myplugin" basedir="${build.dir}">
+<manifest>
+<attribute name="MonkeyRunnerStartupRunner" value="com.myapp.myplugin"/>
+</manifest>
+</jar>
+
+
+
+

+ To get access to monkeyrunner's runtime environment, the startup class can implement + com.google.common.base.Predicate<PythonInterpreter>. For example, this + class sets up some variables in the default namespace: +

+
+package com.android.example;
+
+import com.google.common.base.Predicate;
+import org.python.util.PythonInterpreter;
+
+public class Main implements Predicate<PythonInterpreter> {
+    @Override
+    public boolean apply(PythonInterpreter anInterpreter) {
+
+        /*
+        * Examples of creating and initializing variables in the monkeyrunner environment's
+        * namespace. During execution, the monkeyrunner program can refer to the variables "newtest"
+        * and "use_emulator"
+        *
+        */
+        anInterpreter.set("newtest", "enabled");
+        anInterpreter.set("use_emulator", 1);
+
+        return true;
+    }
+}
+
-- cgit v1.1