diff options
3 files changed, 157 insertions, 113 deletions
diff --git a/monkeyrunner/src/com/android/monkeyrunner/MonkeyDevice.java b/monkeyrunner/src/com/android/monkeyrunner/MonkeyDevice.java index 87c54c2..d150c9b 100644 --- a/monkeyrunner/src/com/android/monkeyrunner/MonkeyDevice.java +++ b/monkeyrunner/src/com/android/monkeyrunner/MonkeyDevice.java @@ -57,14 +57,17 @@ public abstract class MonkeyDevice { */ public abstract void dispose(); - @MonkeyRunnerExported(doc = "Fetch the screenbuffer from the device and return it.", - returns = "The captured snapshot.") + @MonkeyRunnerExported(doc = + "Gets the device's screen buffer, yielding a screen capture of the entire display.", + returns = "A MonkeyImage object (a bitmap wrapper)") public abstract MonkeyImage takeSnapshot(); - @MonkeyRunnerExported(doc = "Get a MonkeyRunner property (like build.fingerprint)", + @MonkeyRunnerExported(doc = "Given the name of a variable on the device, " + + "returns the variable's value", args = {"key"}, - argDocs = {"The key of the property to return"}, - returns = "The value of the property") + argDocs = {"The name of the variable. The available names are listed in " + + "http://developer.android.com/guide/topics/testing/monkeyrunner.html."}, + returns = "The variable's value") public String getProperty(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -72,29 +75,30 @@ public abstract class MonkeyDevice { return getProperty(ap.getString(0)); } - @MonkeyRunnerExported(doc = "Get a system property (returns the same value as getprop).", + @MonkeyRunnerExported(doc = "Synonym for getProperty()", args = {"key"}, - argDocs = {"The key of the property to return"}, - returns = "The value of the property") + argDocs = {"The name of the system variable."}, + returns = "The variable's value.") public String getSystemProperty(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); return getSystemProperty(ap.getString(0)); } - @MonkeyRunnerExported(doc = "Enumeration of possible touch and press event types. This gets " + - "passed into a press or touch call to specify the event type.", - argDocs = {"Indicates the down part of a touch/press event", - "Indicates the up part of a touch/press event.", - "Indicates that the monkey should send a down event immediately " + - "followed by an up event"}) + @MonkeyRunnerExported(doc = "Enumerates the possible touch and key event types. Use this " + + "with touch() or press() to specify the event type.", + argDocs = {"Sends a DOWN event", + "Sends an UP event", + "Sends a DOWN event, immediately followed by an UP event"}) public enum TouchPressType { DOWN, UP, DOWN_AND_UP } - @MonkeyRunnerExported(doc = "Send a touch event at the specified location", + @MonkeyRunnerExported(doc = "Sends a touch event at the specified location", args = { "x", "y", "type" }, - argDocs = { "x coordinate", "y coordinate", "the type of touch event to send"}) + argDocs = { "x coordinate in pixels", + "y coordinate in pixels", + "touch event type as returned by TouchPressType()"}) public void touch(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -114,11 +118,11 @@ public abstract class MonkeyDevice { touch(x, y, type); } - @MonkeyRunnerExported(doc = "Simulate a drag on the screen.", + @MonkeyRunnerExported(doc = "Simulates dragging (touch, hold, and move) on the device screen.", args = { "start", "end", "duration", "steps"}, - argDocs = { "The starting point for the drag (a tuple of x,y)", - "The end point for the drag (a tuple of x,y)", - "How long (in seconds) should the drag take (default is 1.0 seconds)", + argDocs = { "The starting point for the drag (a tuple (x,y) in pixels)", + "The end point for the drag (a tuple (x,y) in pixels", + "Duration of the drag in seconds (default is 1.0 seconds)", "The number of steps to take when interpolating points. (default is 10)"}) public void drag(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); @@ -149,9 +153,11 @@ public abstract class MonkeyDevice { drag(startx, starty, endx, endy, steps, ms); } - @MonkeyRunnerExported(doc = "Send a key press event to the specified button", + @MonkeyRunnerExported(doc = "Send a key event to the specified key", args = { "name", "type" }, - argDocs = { "the name of the key to press", "the type of touch event to send"}) + argDocs = { "the keycode of the key to press (see android.view.KeyEvent)", + "touch event type as returned by TouchPressType(). To simulate typing a key, " + + "send DOWN_AND_UP"}) public void press(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -170,9 +176,10 @@ public abstract class MonkeyDevice { press(name, type); } - @MonkeyRunnerExported(doc = "Type the specified string on the keyboard.", + @MonkeyRunnerExported(doc = "Types the specified string on the keyboard. This is " + + "equivalent to calling press(keycode,DOWN_AND_UP) for each character in the string.", args = { "message" }, - argDocs = { "the message to type." }) + argDocs = { "The string to send to the keyboard." }) public void type(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -181,10 +188,10 @@ public abstract class MonkeyDevice { type(message); } - @MonkeyRunnerExported(doc = "Execute the given command on the shell.", + @MonkeyRunnerExported(doc = "Executes an adb shell command and returns the result, if any.", args = { "cmd"}, - argDocs = { "The command to execute" }, - returns = "The output of the command") + argDocs = { "The adb shell command to execute." }, + returns = "The output from the command.") public String shell(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -193,9 +200,9 @@ public abstract class MonkeyDevice { return shell(cmd); } - @MonkeyRunnerExported(doc = "Reboot the specified device", + @MonkeyRunnerExported(doc = "Reboots the specified device into a specified bootloader.", args = { "into" }, - argDocs = { "the bootloader to reboot into (bootloader, recovery, or None)"}) + argDocs = { "the bootloader to reboot into: bootloader, recovery, or None"}) public void reboot(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -205,10 +212,11 @@ public abstract class MonkeyDevice { reboot(into); } - @MonkeyRunnerExported(doc = "Install the specified apk onto the device.", + @MonkeyRunnerExported(doc = "Installs the specified Android package (.apk file) " + + "onto the device. If the package already exists on the device, it is replaced.", args = { "path" }, - argDocs = { "The path on the host filesystem to the APK to install." }, - returns = "True if install succeeded") + argDocs = { "The package's path and filename on the host filesystem." }, + returns = "True if the install succeeded") public boolean installPackage(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -217,10 +225,11 @@ public abstract class MonkeyDevice { return installPackage(path); } - @MonkeyRunnerExported(doc = "Remove the specified package from the device.", + @MonkeyRunnerExported(doc = "Deletes the specified package from the device, including its " + + "associated data and cache.", args = { "package"}, - argDocs = { "The name of the package to uninstall"}, - returns = "'True if remove succeeded") + argDocs = { "The name of the package to delete."}, + returns = "True if remove succeeded") public boolean removePackage(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -229,18 +238,22 @@ public abstract class MonkeyDevice { return removePackage(packageName); } - @MonkeyRunnerExported(doc = "Start the Activity specified by the intent.", + @MonkeyRunnerExported(doc = "Starts an Activity on the device by sending an Intent " + + "constructed from the specified parameters.", args = { "uri", "action", "data", "mimetype", "categories", "extras", "component", "flags" }, - argDocs = { "The URI for the intent", - "The action for the intent", - "The data URI for the intent", - "The mime type for the intent", - "The list of category names for the intent", - "A dictionary of extras to add to the intent. Types of these extras " + - "are inferred from the python types of the values", - "The component of the intent", - "A list of flags for the intent" }) + argDocs = { "The URI for the Intent.", + "The action for the Intent.", + "The data URI for the Intent", + "The mime type for the Intent.", + "A Python iterable containing the category names for the Intent.", + "A dictionary of extras to add to the Intent. Types of these extras " + + "are inferred from the python types of the values.", + "The component of the Intent.", + "An iterable of flags for the Intent." + + "All arguments are optional. The default value for each argument is null." + + "(see android.content.Intent)"}) + public void startActivity(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -258,18 +271,21 @@ public abstract class MonkeyDevice { startActivity(uri, action, data, mimetype, categories, extras, component, flags); } - @MonkeyRunnerExported(doc = "Start the specified broadcast intent on the device.", + @MonkeyRunnerExported(doc = "Sends a broadcast intent to the device.", args = { "uri", "action", "data", "mimetype", "categories", "extras", "component", "flags" }, - argDocs = { "The URI for the intent", - "The action for the intent", - "The data URI for the intent", - "The mime type for the intent", - "The list of category names for the intent", - "A dictionary of extras to add to the intent. Types of these extras " + - "are inferred from the python types of the values", - "The component of the intent", - "A list of flags for the intent" }) + argDocs = { "The URI for the Intent.", + "The action for the Intent.", + "The data URI for the Intent", + "The mime type for the Intent.", + "An iterable of category names for the Intent.", + "A dictionary of extras to add to the Intent. Types of these extras " + + "are inferred from the python types of the values.", + "The component of the Intent.", + "An iterable of flags for the Intent." + + "All arguments are optional. " + "" + + "The default value for each argument is null." + + "(see android.content.Context.sendBroadcast(Intent))"}) public void broadcastIntent(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -287,12 +303,21 @@ public abstract class MonkeyDevice { broadcastIntent(uri, action, data, mimetype, categories, extras, component, flags); } - @MonkeyRunnerExported(doc = "Instrument the specified package and return the results from it.", + @MonkeyRunnerExported(doc = "Run the specified package with instrumentation and return " + + "the output it generates. Use this to run a test package using " + + "InstrumentationTestRunner.", args = { "className", "args" }, - argDocs = { "The class name to instrument (like com.android.test/.TestInstrument)", - "A Map of String to Objects for the aruments to pass to this " + - "instrumentation (default value is None)" }, - returns = "A map of string to objects for the results this instrumentation returned") + argDocs = { "The class to run with instrumentation. The format is " + + "packagename/classname. Use packagename to specify the Android package " + + "to run, and classname to specify the class to run within that package. " + + "For test packages, this is usually " + + "testpackagename/InstrumentationTestRunner", + "A map of strings to objects containing the arguments to pass to this " + + "instrumentation (default value is None)." }, + returns = "A map of strings to objects for the output from the package. " + + "For a test package, contains a single key-value pair: the key is 'stream' " + + "and the value is a string containing the test output.") + public PyDictionary instrument(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); diff --git a/monkeyrunner/src/com/android/monkeyrunner/MonkeyImage.java b/monkeyrunner/src/com/android/monkeyrunner/MonkeyImage.java index 7cff67f..6e32b3d 100644 --- a/monkeyrunner/src/com/android/monkeyrunner/MonkeyImage.java +++ b/monkeyrunner/src/com/android/monkeyrunner/MonkeyImage.java @@ -70,10 +70,14 @@ public abstract class MonkeyImage { return img; } - @MonkeyRunnerExported(doc = "Encode the image into a format and return the bytes.", + @MonkeyRunnerExported(doc = "Converts the MonkeyImage into a particular format and returns " + + "the result as a String. Use this to get access to the raw" + + "pixels in a particular format. String output is for better " + + "performance.", args = {"format"}, - argDocs = { "The (optional) format in which to encode the image (PNG for example)" }, - returns = "A String containing the bytes.") + argDocs = { "The destination format (for example, 'png' for Portable " + + "Network Graphics format). The default is png." }, + returns = "The resulting image as a String.") public byte[] convertToBytes(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -91,13 +95,15 @@ public abstract class MonkeyImage { return os.toByteArray(); } - @MonkeyRunnerExported(doc = "Write out the file to the specified location. If no " + - "format is specified, this function tries to guess at the output format " + - "depending on the file extension given. If unable to determine, it uses PNG.", + @MonkeyRunnerExported(doc = "Write the MonkeyImage to a file. If no " + + "format is specified, this method guesses the output format " + + "based on the extension of the provided file extension. If it is unable to guess the " + + "format, it uses PNG.", args = {"path", "format"}, - argDocs = {"Where to write out the file", - "The format in which to encode the image (PNG for example)"}, - returns = "True if writing succeeded.") + argDocs = {"The output filename, optionally including its path", + "The destination format (for example, 'png' for " + + " Portable Network Graphics format." }, + returns = "boolean true if writing succeeded.") public boolean writeToFile(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -138,10 +144,13 @@ public abstract class MonkeyImage { return true; } - @MonkeyRunnerExported(doc = "Get a single ARGB pixel from the image", + @MonkeyRunnerExported(doc = "Get a single ARGB (alpha, red, green, blue) pixel at location " + + "x,y. The arguments x and y are 0-based, expressed in pixel dimensions. X increases " + + "to the right, and Y increases towards the bottom. This method returns a tuple.", args = { "x", "y" }, argDocs = { "the x offset of the pixel", "the y offset of the pixel" }, - returns = "A tuple of (A, R, G, B) for the pixel") + returns = "A tuple of (A, R, G, B) for the pixel. Each item in the tuple has the " + + "range 0-255.") public PyObject getRawPixel(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -156,10 +165,13 @@ public abstract class MonkeyImage { return new PyTuple(a, r, g ,b); } - @MonkeyRunnerExported(doc = "Get a single ARGB pixel from the image", + @MonkeyRunnerExported(doc = "Get a single ARGB (alpha, red, green, blue) pixel at location " + + "x,y. The arguments x and y are 0-based, expressed in pixel dimensions. X increases " + + "to the right, and Y increases towards the bottom. This method returns an Integer.", args = { "x", "y" }, argDocs = { "the x offset of the pixel", "the y offset of the pixel" }, - returns = "An integer for the ARGB pixel") + returns = "An unsigned integer pixel for x,y. The 8 high-order bits are A, followed" + + "by 8 bits for R, 8 for G, and 8 for B.") public int getRawPixelInt(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -197,12 +209,13 @@ public abstract class MonkeyImage { return true; } - @MonkeyRunnerExported(doc = "Compare this image to the other image.", + @MonkeyRunnerExported(doc = "Compare this MonkeyImage object to aother MonkeyImage object.", args = {"other", "percent"}, - argDocs = {"The other image.", - "A float from 0.0 to 1.0 indicating the percentage " + - "of pixels that need to be the same. Defaults to 1.0"}, - returns = "True if they are the same image.") + argDocs = {"The other MonkeyImage object.", + "A float in the range 0.0 to 1.0, indicating the percentage " + + "of pixels that need to be the same for the method to return 'true'. " + + "Defaults to 1.0."}, + returns = "boolean 'true' if the two objects contain the same image.") public boolean sameAs(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -257,10 +270,12 @@ public abstract class MonkeyImage { } - @MonkeyRunnerExported(doc = "Get a sub-image of this image.", + @MonkeyRunnerExported(doc = "Copy a rectangular region of the image.", args = {"rect"}, - argDocs = {"A Tuple of (x, y, w, h) representing the area of the image to extract."}, - returns = "The newly extracted image.") + argDocs = {"A tuple (x, y, w, h) describing the region to copy. x and y specify " + + "upper lefthand corner of the region. w is the width of the region in " + + "pixels, and h is its height."}, + returns = "a MonkeyImage object representing the copied region.") public MonkeyImage getSubImage(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -274,4 +289,4 @@ public abstract class MonkeyImage { BufferedImage image = getBufferedImage(); return new BufferedImageMonkeyImage(image.getSubimage(x, y, w, h)); } -}
\ No newline at end of file +} diff --git a/monkeyrunner/src/com/android/monkeyrunner/MonkeyRunner.java b/monkeyrunner/src/com/android/monkeyrunner/MonkeyRunner.java index cdab926..63ab9eb 100644 --- a/monkeyrunner/src/com/android/monkeyrunner/MonkeyRunner.java +++ b/monkeyrunner/src/com/android/monkeyrunner/MonkeyRunner.java @@ -47,13 +47,12 @@ public class MonkeyRunner { MonkeyRunner.backend = backend; } - @MonkeyRunnerExported(doc = "Wait for the specified device to connect.", + @MonkeyRunnerExported(doc = "Waits for the workstation to connect to the device.", args = {"timeout", "deviceId"}, - argDocs = {"The timeout in seconds to wait for the device to connect. (default " + - "is to wait forever)", - "A regular expression that specifies the device of for valid devices" + - " to wait for."}, - returns = "A MonkeyDevice representing the connected device.") + argDocs = {"The timeout in seconds to wait. The default is to wait indefinitely.", + "A regular expression that specifies the device name. See the documentation " + + "for 'adb' in the Developer Guide to learn more about device names."}, + returns = "A MonkeyDevice object representing the connected device.") public static MonkeyDevice waitForConnection(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -70,10 +69,11 @@ public class MonkeyRunner { ap.getString(1, ".*")); } - @MonkeyRunnerExported(doc = "Pause script processing for the specified number of seconds", + @MonkeyRunnerExported(doc = "Pause the currently running program for the specified " + + "number of seconds.", args = {"seconds"}, - argDocs = {"The number of seconds to pause processing"}) - public static void sleep(PyObject[] args, String[] kws) { + argDocs = {"The number of seconds to pause."}) + public static void sleep(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -88,11 +88,11 @@ public class MonkeyRunner { } } - @MonkeyRunnerExported(doc = "Simple help command to dump the MonkeyRunner supported " + - "commands", + @MonkeyRunnerExported(doc = "Format and display the API reference for MonkeyRunner.", args = { "format" }, - argDocs = {"The format to return the help text in. (default is text)"}, - returns = "The help text") + argDocs = {"The desired format for the output, either 'text' for plain text or " + + "'html' for HTML markup."}, + returns = "A string containing the help text in the desired format.") public static String help(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); @@ -102,14 +102,14 @@ public class MonkeyRunner { return MonkeyRunnerHelp.helpString(format); } - @MonkeyRunnerExported(doc = "Put up an alert dialog to inform the user of something that " + - "happened. This is modal dialog and will stop processing of " + - "the script until the user acknowledges the alert message", + @MonkeyRunnerExported(doc = "Display an alert dialog to the process running the current " + + "script. The dialog is modal, so the script stops until the user dismisses the " + + "dialog.", args = { "message", "title", "okTitle" }, argDocs = { - "The contents of the message of the dialog box", - "The title to display for the dialog box. (default value is \"Alert\")", - "The title to use for the acknowledgement button (default value is \"OK\")" + "The message to display in the dialog.", + "The dialog's title. The default value is 'Alert'.", + "The text to use in the dialog button. The default value is 'OK'." }) public static void alert(PyObject[] args, String[] kws) { ArgParser ap = JythonUtils.createArgParser(args, kws); @@ -122,14 +122,18 @@ public class MonkeyRunner { alert(message, title, buttonTitle); } - @MonkeyRunnerExported(doc = "Put up an input dialog that allows the user to input a string." + - " This is a modal dialog that will stop processing of the script until the user " + - "inputs the requested information.", + @MonkeyRunnerExported(doc = "Display a dialog that accepts input. The dialog is ," + + "modal, so the script stops until the user clicks one of the two dialog buttons. To " + + "enter a value, the user enters the value and clicks the 'OK' button. To quit the " + + "dialog without entering a value, the user clicks the 'Cancel' button. Use the " + + "supplied arguments for this method to customize the text for these buttons.", args = {"message", "initialValue", "title", "okTitle", "cancelTitle"}, argDocs = { - "The message to display for the input.", - "The initial value to supply the user (default is empty string)", - "The title of the dialog box to display. (default is \"Input\")" + "The prompt message to display in the dialog.", + "The initial value to supply to the user. The default is an empty string)", + "The dialog's title. The default is 'Input'", + "The text to use in the dialog's confirmation button. The default is 'OK'." + + "The text to use in the dialog's 'cancel' button. The default is 'Cancel'." }, returns = "The test entered by the user, or None if the user canceled the input;" ) @@ -144,14 +148,14 @@ public class MonkeyRunner { return input(message, initialValue, title); } - @MonkeyRunnerExported(doc = "Put up a choice dialog that allows the user to select a single " + - "item from a list of items that were presented.", + @MonkeyRunnerExported(doc = "Display a choice dialog that allows the user to select a single " + + "item from a list of items.", args = {"message", "choices", "title"}, argDocs = { - "The message to display for the input.", - "The list of choices to display.", - "The title of the dialog box to display. (default is \"Input\")" }, - returns = "The numeric offset of the choice selected.") + "The prompt message to display in the dialog.", + "An iterable Python type containing a list of choices to display", + "The dialog's title. The default is 'Input'" }, + returns = "The 0-based numeric offset of the selected item in the iterable.") public static int choice(PyObject[] args, String kws[]) { ArgParser ap = JythonUtils.createArgParser(args, kws); Preconditions.checkNotNull(ap); |