| page.title=monkeyrunner |
| @jd:body |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li> |
| <a href="#SampleProgram">A Simple monkeyrunner Program</a> |
| </li> |
| <li> |
| <a href="#APIClasses">The monkeyrunner API</a> |
| </li> |
| <li> |
| <a href="#RunningMonkeyRunner">Running monkeyrunner</a> |
| </li> |
| <li> |
| <a href="#Help">monkeyrunner Built-in Help</a> |
| </li> |
| <li> |
| <a href="#Plugins">Extending monkeyrunner with Plugins</a> |
| </li> |
| </ol> |
| <h2>See Also</h2> |
| <ol> |
| <li> |
| <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a> |
| </li> |
| </ol> |
| </div> |
| </div> |
| <p> |
| 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. |
| </p> |
| <p> |
| The monkeyrunner tool is not related to the |
| <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, |
| also known as the <code>monkey</code> tool. The <code>monkey</code> tool runs in an |
| <code><a href="{@docRoot}guide/developing/tools/adb.html">adb</a></code> 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. |
| </p> |
| <p> |
| The monkeyrunner tool provides these unique features for Android testing: |
| </p> |
| <ul> |
| <li> |
| 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. |
| </li> |
| <li> |
| 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. |
| </li> |
| <li> |
| 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. |
| </li> |
| <li> |
| 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 |
| <code><a href="http://docs.python.org/library/os.html">os</a></code> and |
| <code><a href="http://docs.python.org/library/subprocess.html">subprocess</a></code> |
| modules to call Android tools such as |
| <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>. |
| <p> |
| You can also add your own classes to the monkeyrunner API. This is described |
| in more detail in the section |
| <a href="#Plugins">Extending monkeyrunner with plugins</a>. |
| </p> |
| </li> |
| </ul> |
| <p> |
| The monkeyrunner tool uses <a href="http://www.jython.org/">Jython</a>, 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. |
| </p> |
| |
| <h2 id="SampleProgram">A Simple monkeyrunner Program</h2> |
| <p> |
| Here is a simple monkeyrunner program that connects to a device, creating a |
| <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code> |
| object. Using the <code>MonkeyDevice</code> 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 |
| <code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code> object. |
| From this object, the program writes out a <code>.png</code> file containing the screenshot. |
| </p> |
| <pre> |
| # 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') |
| </pre> |
| |
| <h2 id="APIClasses">The monkeyrunner API</h2> |
| <p> |
| The monkeyrunner API is contained in three modules in the package |
| <code>com.android.monkeyrunner</code>: |
| </p> |
| <ul> |
| <li> |
| <code><a href="{@docRoot}guide/developing/tools/MonkeyRunner.html">MonkeyRunner</a></code>: |
| 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. |
| </li> |
| <li> |
| <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>: |
| 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. |
| </li> |
| <li> |
| <code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code>: |
| 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. |
| </li> |
| </ul> |
| <p> |
| 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 <code>from</code> statement: |
| </p> |
| <pre> |
| from com.android.monkeyrunner import <module> |
| </pre> |
| <p> |
| where <code><module></code> is the class name you want to import. You can import more |
| than one module in the same <code>from</code> statement by separating the module names with |
| commas. |
| </p> |
| <h2 id="RunningMonkeyRunner">Running monkeyrunner</h2> |
| <p> |
| You can either run monkeyrunner programs from a file, or enter monkeyrunner statements in |
| an interactive session. You do both by invoking the <code>monkeyrunner</code> command |
| which is found in the <code>tools/</code> subdirectory of your SDK directory. |
| If you provide a filename as an argument, the <code>monkeyrunner</code> command |
| runs the file's contents as a Python program; otherwise, it starts an interactive session. |
| </p> |
| <p> |
| The syntax of the <code>monkeyrunner</code> command is |
| </p> |
| <pre> |
| monkeyrunner -plugin <plugin_jar> <program_filename> <program_options> |
| </pre> |
| <p> |
| Table 1 explains the flags and arguments. |
| </p> |
| <p class="table-caption" id="table1"> |
| <strong>Table 1.</strong> <code>monkeyrunner</code> flags and arguments.</p> |
| |
| <table> |
| <tr> |
| <th>Argument</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td> |
| <nobr> |
| <code>-plugin <plugin_jar></code> |
| </nobr> |
| </td> |
| <td> |
| (Optional) Specifies a <code>.jar</code> file containing a plugin for monkeyrunner. |
| To learn more about monkeyrunner plugins, see |
| <a href="#Plugins">Extending monkeyrunner with plugins</a>. To specify more than one |
| file, include the argument multiple times. |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <nobr> |
| <code><program_filename></code> |
| </nobr> |
| </td> |
| <td> |
| If you provide this argument, the <code>monkeyrunner</code> command runs the contents |
| of the file as a Python program. If the argument is not provided, the command starts an |
| interactive session. |
| </td> |
| </tr> |
| <tr> |
| <td> |
| <code><program_options></code> |
| </td> |
| <td> |
| (Optional) Flags and arguments for the program in <program_file>. |
| </td> |
| </tr> |
| </table> |
| <h2 id="Help">monkeyrunner Built-in Help</h2> |
| <p> |
| You can generate an API reference for monkeyrunner by running: |
| </p> |
| <pre> |
| monkeyrunner <format> help.py <outfile> |
| </pre> |
| <p> |
| The arguments are: |
| </p> |
| <ul> |
| <li> |
| <code><format></code> is either <code>text</code> for plain text output |
| or <code>html</code> for HTML output. |
| </li> |
| <li> |
| <code><outfile></code> is a path-qualified name for the output file. |
| </li> |
| </ul> |
| <h2 id="Plugins">Extending monkeyrunner with Plugins</h2> |
| <p> |
| You can extend the monkeyrunner API with classes you write in the Java programming language |
| and build into one or more <code>.jar</code> 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. |
| </p> |
| <p> |
| To provide a plugin to monkeyrunner, invoke the <code>monkeyrunner</code> command with the |
| <code>-plugin <plugin_jar></code> argument described in |
| <a href="#table1">table 1</a>. |
| </p> |
| <p> |
| In your plugin code, you can import and extend the the main monkeyrunner classes |
| <code>MonkeyDevice</code>, <code>MonkeyImage</code>, and <code>MonkeyRunner</code> in |
| <code>com.android.monkeyrunner</code> (see <a href="#APIClasses">The monkeyrunner API</a>). |
| </p> |
| <p> |
| Note that plugins do not give you access to the Android SDK. You can't import packages |
| such as <code>com.android.app</code>. This is because monkeyrunner interacts with the |
| device or emulator below the level of the framework APIs. |
| </p> |
| <h3>The plugin startup class</h3> |
| <p> |
| The <code>.jar</code> file for a plugin can specify a class that is instantiated before |
| script processing starts. To specify this class, add the key |
| <code>MonkeyRunnerStartupRunner</code> to the <code>.jar</code> 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 <code>ant</code> build script: |
| </p> |
| <pre> |
| <jar jarfile="myplugin" basedir="${build.dir}"> |
| <manifest> |
| <attribute name="MonkeyRunnerStartupRunner" value="com.myapp.myplugin"/> |
| </manifest> |
| </jar> |
| |
| |
| </pre> |
| <p> |
| To get access to monkeyrunner's runtime environment, the startup class can implement |
| <code>com.google.common.base.Predicate<PythonInterpreter></code>. For example, this |
| class sets up some variables in the default namespace: |
| </p> |
| <pre> |
| 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; |
| } |
| } |
| </pre> |