1page.title=monkeyrunner 2@jd:body 3 4<div id="qv-wrapper"> 5 <div id="qv"> 6 <h2>In this document</h2> 7 <ol> 8 <li> 9 <a href="#SampleProgram">A Simple monkeyrunner Program</a> 10 </li> 11 <li> 12 <a href="#APIClasses">The monkeyrunner API</a> 13 </li> 14 <li> 15 <a href="#RunningMonkeyRunner">Running monkeyrunner</a> 16 </li> 17 <li> 18 <a href="#Help">monkeyrunner Built-in Help</a> 19 </li> 20 <li> 21 <a href="#Plugins">Extending monkeyrunner with Plugins</a> 22 </li> 23 </ol> 24 <h2>See Also</h2> 25 <ol> 26 <li> 27 <a href="{@docRoot}guide/topics/testing/testing_android.html">Testing Fundamentals</a> 28 </li> 29 </ol> 30 </div> 31</div> 32<p> 33 The monkeyrunner tool provides an API for writing programs that control an Android device 34 or emulator from outside of Android code. With monkeyrunner, you can write a Python program 35 that installs an Android application or test package, runs it, sends keystrokes to it, 36 takes screenshots of its user interface, and stores screenshots on the workstation. The 37 monkeyrunner tool is primarily designed to test applications and devices at the 38 functional/framework level and for running unit test suites, but you are free to use it for 39 other purposes. 40</p> 41<p> 42 The monkeyrunner tool is not related to the 43 <a href="{@docRoot}guide/developing/tools/monkey.html">UI/Application Exerciser Monkey</a>, 44 also known as the <code>monkey</code> tool. The <code>monkey</code> tool runs in an 45 <code><a href="{@docRoot}guide/developing/tools/adb.html">adb</a></code> shell directly on the 46 device or emulator and generates pseudo-random streams of user and system events. In comparison, 47 the monkeyrunner tool controls devices and emulators from a workstation by sending specific 48 commands and events from an API. 49</p> 50<p> 51 The monkeyrunner tool provides these unique features for Android testing: 52</p> 53<ul> 54 <li> 55 Multiple device control: The monkeyrunner API can apply one or more 56 test suites across multiple devices or emulators. You can physically attach all the devices 57 or start up all the emulators (or both) at once, connect to each one in turn 58 programmatically, and then run one or more tests. You can also start up an emulator 59 configuration programmatically, run one or more tests, and then shut down the emulator. 60 </li> 61 <li> 62 Functional testing: monkeyrunner can run an automated start-to-finish test of an Android 63 application. You provide input values with keystrokes or touch events, and view the results 64 as screenshots. 65 </li> 66 <li> 67 Regression testing - monkeyrunner can test application stability by running an application 68 and comparing its output screenshots to a set of screenshots that are known to be correct. 69 </li> 70 <li> 71 Extensible automation - Since monkeyrunner is an API toolkit, you can develop an entire 72 system of Python-based modules and programs for controlling Android devices. Besides using 73 the monkeyrunner API itself, you can use the standard Python 74 <code><a href="http://docs.python.org/library/os.html">os</a></code> and 75 <code><a href="http://docs.python.org/library/subprocess.html">subprocess</a></code> 76 modules to call Android tools such as 77 <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>. 78 <p> 79 You can also add your own classes to the monkeyrunner API. This is described 80 in more detail in the section 81 <a href="#Plugins">Extending monkeyrunner with plugins</a>. 82 </p> 83 </li> 84</ul> 85<p> 86 The monkeyrunner tool uses <a href="http://www.jython.org/">Jython</a>, a 87 implementation of Python that uses the Java programming language. Jython allows the 88 monkeyrunner API to interact easily with the Android framework. With Jython you can 89 use Python syntax to access the constants, classes, and methods of the API. 90</p> 91 92<h2 id="SampleProgram">A Simple monkeyrunner Program</h2> 93<p> 94 Here is a simple monkeyrunner program that connects to a device, creating a 95 <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code> 96 object. Using the <code>MonkeyDevice</code> object, the program installs an Android application 97 package, runs one of its activities, and sends key events to the activity. 98 The program then takes a screenshot of the result, creating a 99 <code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code> object. 100 From this object, the program writes out a <code>.png</code> file containing the screenshot. 101</p> 102<pre> 103# Imports the monkeyrunner modules used by this program 104from com.android.monkeyrunner import MonkeyRunner, MonkeyDevice 105 106# Connects to the current device, returning a MonkeyDevice object 107device = MonkeyRunner.waitForConnection() 108 109# Installs the Android package. Notice that this method returns a boolean, so you can test 110# to see if the installation worked. 111device.installPackage('myproject/bin/MyApplication.apk') 112 113# Runs an activity in the application 114device.startActivity(component='com.example.android.myapplication.MainActivity') 115 116# Presses the Menu button 117device.press('KEYCODE_MENU','DOWN_AND_UP') 118 119# Takes a screenshot 120result = device.takeSnapShot 121 122# Writes the screenshot to a file 123result.writeToFile('myproject/shot1.png','png') 124</pre> 125 126<h2 id="APIClasses">The monkeyrunner API</h2> 127<p> 128 The monkeyrunner API is contained in three modules in the package 129 <code>com.android.monkeyrunner</code>: 130</p> 131<ul> 132 <li> 133 <code><a href="{@docRoot}guide/developing/tools/MonkeyRunner.html">MonkeyRunner</a></code>: 134 A class of utility methods for monkeyrunner programs. This class provides a method for 135 connecting monkeyrunner to a device or emulator. It also provides methods for 136 creating UIs for a monkeyrunner program and for displaying the built-in help. 137 </li> 138 <li> 139 <code><a href="{@docRoot}guide/developing/tools/MonkeyDevice.html">MonkeyDevice</a></code>: 140 Represents a device or emulator. This class provides methods for installing and 141 uninstalling packages, starting an Activity, and sending keyboard or touch events to an 142 application. You also use this class to run test packages. 143 </li> 144 <li> 145 <code><a href="{@docRoot}guide/developing/tools/MonkeyImage.html">MonkeyImage</a></code>: 146 Represents a screen capture image. This class provides methods for capturing screens, 147 converting bitmap images to various formats, comparing two MonkeyImage objects, and 148 writing an image to a file. 149 </li> 150</ul> 151<p> 152 In a Python program, you access each class as a Python module. The monkeyrunner tool 153 does not import these modules automatically. To import a module, use the 154 Python <code>from</code> statement: 155</p> 156<pre> 157from com.android.monkeyrunner import <module> 158</pre> 159<p> 160 where <code><module></code> is the class name you want to import. You can import more 161 than one module in the same <code>from</code> statement by separating the module names with 162 commas. 163</p> 164<h2 id="RunningMonkeyRunner">Running monkeyrunner</h2> 165<p> 166 You can either run monkeyrunner programs from a file, or enter monkeyrunner statements in 167 an interactive session. You do both by invoking the <code>monkeyrunner</code> command 168 which is found in the <code>tools/</code> subdirectory of your SDK directory. 169 If you provide a filename as an argument, the <code>monkeyrunner</code> command 170 runs the file's contents as a Python program; otherwise, it starts an interactive session. 171</p> 172<p> 173 The syntax of the <code>monkeyrunner</code> command is 174</p> 175<pre> 176monkeyrunner -plugin <plugin_jar> <program_filename> <program_options> 177</pre> 178<p> 179Table 1 explains the flags and arguments. 180</p> 181<p class="table-caption" id="table1"> 182 <strong>Table 1.</strong> <code>monkeyrunner</code> flags and arguments.</p> 183 184<table> 185 <tr> 186 <th>Argument</th> 187 <th>Description</th> 188 </tr> 189 <tr> 190 <td> 191 <nobr> 192 <code>-plugin <plugin_jar></code> 193 </nobr> 194 </td> 195 <td> 196 (Optional) Specifies a <code>.jar</code> file containing a plugin for monkeyrunner. 197 To learn more about monkeyrunner plugins, see 198 <a href="#Plugins">Extending monkeyrunner with plugins</a>. To specify more than one 199 file, include the argument multiple times. 200 </td> 201 </tr> 202 <tr> 203 <td> 204 <nobr> 205 <code><program_filename></code> 206 </nobr> 207 </td> 208 <td> 209 If you provide this argument, the <code>monkeyrunner</code> command runs the contents 210 of the file as a Python program. If the argument is not provided, the command starts an 211 interactive session. 212 </td> 213 </tr> 214 <tr> 215 <td> 216 <code><program_options></code> 217 </td> 218 <td> 219 (Optional) Flags and arguments for the program in <program_file>. 220 </td> 221 </tr> 222</table> 223<h2 id="Help">monkeyrunner Built-in Help</h2> 224<p> 225 You can generate an API reference for monkeyrunner by running: 226</p> 227<pre> 228monkeyrunner <format> help.py <outfile> 229</pre> 230<p> 231The arguments are: 232</p> 233 <ul> 234 <li> 235 <code><format></code> is either <code>text</code> for plain text output 236 or <code>html</code> for HTML output. 237 </li> 238 <li> 239 <code><outfile></code> is a path-qualified name for the output file. 240 </li> 241 </ul> 242<h2 id="Plugins">Extending monkeyrunner with Plugins</h2> 243<p> 244 You can extend the monkeyrunner API with classes you write in the Java programming language 245 and build into one or more <code>.jar</code> files. You can use this feature to extend the 246 monkeyrunner API with your own classes or to extend the existing classes. You can also use this 247 feature to initialize the monkeyrunner environment. 248</p> 249<p> 250 To provide a plugin to monkeyrunner, invoke the <code>monkeyrunner</code> command with the 251 <code>-plugin <plugin_jar></code> argument described in 252 <a href="#table1">table 1</a>. 253</p> 254<p> 255 In your plugin code, you can import and extend the the main monkeyrunner classes 256 <code>MonkeyDevice</code>, <code>MonkeyImage</code>, and <code>MonkeyRunner</code> in 257 <code>com.android.monkeyrunner</code> (see <a href="#APIClasses">The monkeyrunner API</a>). 258</p> 259<p> 260 Note that plugins do not give you access to the Android SDK. You can't import packages 261 such as <code>com.android.app</code>. This is because monkeyrunner interacts with the 262 device or emulator below the level of the framework APIs. 263</p> 264<h3>The plugin startup class</h3> 265<p> 266 The <code>.jar</code> file for a plugin can specify a class that is instantiated before 267 script processing starts. To specify this class, add the key 268 <code>MonkeyRunnerStartupRunner</code> to the <code>.jar</code> file's 269 manifest. The value should be the name of the class to run at startup. The following 270 snippet shows how you would do this within an <code>ant</code> build script: 271</p> 272<pre> 273<jar jarfile="myplugin" basedir="${build.dir}"> 274<manifest> 275<attribute name="MonkeyRunnerStartupRunner" value="com.myapp.myplugin"/> 276</manifest> 277</jar> 278 279 280</pre> 281<p> 282 To get access to monkeyrunner's runtime environment, the startup class can implement 283 <code>com.google.common.base.Predicate<PythonInterpreter></code>. For example, this 284 class sets up some variables in the default namespace: 285</p> 286<pre> 287package com.android.example; 288 289import com.google.common.base.Predicate; 290import org.python.util.PythonInterpreter; 291 292public class Main implements Predicate<PythonInterpreter> { 293 @Override 294 public boolean apply(PythonInterpreter anInterpreter) { 295 296 /* 297 * Examples of creating and initializing variables in the monkeyrunner environment's 298 * namespace. During execution, the monkeyrunner program can refer to the variables "newtest" 299 * and "use_emulator" 300 * 301 */ 302 anInterpreter.set("newtest", "enabled"); 303 anInterpreter.set("use_emulator", 1); 304 305 return true; 306 } 307} 308</pre> 309
