1 page.title=UI/Application Exerciser Monkey 2 @jd:body 3 4 <p>The Monkey is a program that runs on your 5 <a href="{@docRoot}guide/developing/tools/emulator.html">emulator</a> or device and generates pseudo-random 6 streams of user events such as clicks, touches, or gestures, as well as a number of system-level 7 events. You can use the Monkey to stress-test applications that you are developing, in a random 8 yet repeatable manner.</p> 9 10 <a name="overview"></a> 11 <h2>Overview</h2> 12 13 <p>The Monkey is a command-line tool that that you can run on any emulator 14 instance or on a device. It sends a pseudo-random stream of 15 user events into the system, which acts as a stress test on the application software you are 16 developing.</p> 17 18 <p>The Monkey includes a number of options, but they break down into four primary 19 categories:</p> 20 21 <ul> 22 <li>Basic configuration options, such as setting the number of events to attempt.</li> 23 <li>Operational constraints, such as restricting the test to a single package.</li> 24 <li>Event types and frequencies.</li> 25 <li>Debugging options.</li> 26 </ul> 27 28 <p>When the Monkey runs, it generates events and sends them to the system. It also <i>watches</i> 29 the system under test and looks for three conditions, which it treats specially:</p> 30 31 <ul> 32 <li>If you have constrained the Monkey to run in one or more specific packages, it 33 watches for attempts to navigate to any other packages, and blocks them.</li> 34 <li>If your application crashes or receives any sort of unhandled exception, the Monkey 35 will stop and report the error.</li> 36 <li>If your application generates an <i>application not responding</i> error, the Monkey 37 will stop and report the error.</li> 38 </ul> 39 40 <p>Depending on the verbosity level you have selected, you will also see reports on the progress 41 of the Monkey and the events being generated.</p> 42 43 <a name="basics"></a> 44 <h2>Basic Use of the Monkey</h2> 45 46 <p>You can launch the Monkey using a command line on your development machine or from a script. 47 Because the Monkey runs in the emulator/device environment, you must launch it from a shell in 48 that environment. You can do this by prefacing <code>adb shell</code> to each command, 49 or by entering the shell and entering Monkey commands directly.</p> 50 <p>The basic syntax is: </p> 51 52 <pre>$ adb shell monkey [options] <event-count></pre> 53 54 <p>With no options specified, the Monkey will launch in a quiet (non-verbose) mode, and will send 55 events to any (and all) packages installed on your target. Here is a more typical command line, 56 which will launch your application and send 500 pseudo-random events to it:</p> 57 58 <pre>$ adb shell monkey -p your.package.name -v 500</pre> 59 60 <a name="reference"></a> 61 <h2>Command Options Reference</h2> 62 63 <p>The table below lists all options you can include on the Monkey command line.</p> 64 65 <table> 66 <tr> 67 <th>Category</th> 68 <th>Option</th> 69 <th>Description</th> 70 </tr> 71 72 <tr> 73 <td rowspan="2">General</td> 74 <td><code>--help</code></td> 75 <td>Prints a simple usage guide.</td> 76 </tr> 77 78 <tr> 79 <td><code>-v</code></td> 80 <td>Each -v on the command line will increment the verbosity level. 81 Level 0 (the default) provides little information beyond startup notification, test completion, and 82 final results. 83 Level 1 provides more details about the test as it runs, such as individual events being sent to 84 your activities. 85 Level 2 provides more detailed setup information such as activities selected or not selected for 86 testing.</td> 87 </tr> 88 89 <tr> 90 <td rowspan="10">Events</td> 91 <td><code>-s <seed></code></td> 92 <td>Seed value for pseudo-random number generator. If you re-run the Monkey with the same seed 93 value, it will generate the same sequence of events.</td> 94 </tr> 95 96 <tr> 97 <td><code>--throttle <milliseconds></code></td> 98 <td>Inserts a fixed delay between events. You can use this option to slow down the Monkey. 99 If not specified, there is no delay and the events are generated as rapidly as possible.</td> 100 </tr> 101 102 <tr> 103 <td><code>--pct-touch <percent></code></td> 104 <td>Adjust percentage of touch events. 105 (Touch events are a down-up event in a single place on the screen.)</td> 106 </tr> 107 108 <tr> 109 <td><code>--pct-motion <percent></code></td> 110 <td>Adjust percentage of motion events. 111 (Motion events consist of a down event somewhere on the screen, a series of pseudo-random 112 movements, and an up event.)</td> 113 </tr> 114 115 <tr> 116 <td><code>--pct-trackball <percent></code></td> 117 <td>Adjust percentage of trackball events. 118 (Trackball events consist of one or more random movements, sometimes followed by a click.)</td> 119 </tr> 120 121 <tr> 122 <td><code>--pct-nav <percent></code></td> 123 <td>Adjust percentage of "basic" navigation events. 124 (Navigation events consist of up/down/left/right, as input from a directional input device.)</td> 125 </tr> 126 127 <tr> 128 <td><code>--pct-majornav <percent></code></td> 129 <td>Adjust percentage of "major" navigation events. 130 (These are navigation events that will typically cause actions within your UI, such as 131 the center button in a 5-way pad, the back key, or the menu key.)</td> 132 </tr> 133 134 <tr> 135 <td><code>--pct-syskeys <percent></code></td> 136 <td>Adjust percentage of "system" key events. 137 (These are keys that are generally reserved for use by the system, such as Home, Back, Start Call, 138 End Call, or Volume controls.)</td> 139 </tr> 140 141 <tr> 142 <td><code>--pct-appswitch <percent></code></td> 143 <td>Adjust percentage of activity launches. At random intervals, the Monkey will issue a startActivity() call, as a way of maximizing 144 coverage of all activities within your package.</td> 145 </tr> 146 147 <tr> 148 <td><code>--pct-anyevent <percent></code></td> 149 <td>Adjust percentage of other types of events. This is a catch-all for all other types of events such as keypresses, other less-used 150 buttons on the device, and so forth.</td> 151 </tr> 152 153 <tr> 154 <td rowspan="2">Constraints</td> 155 <td><code>-p <allowed-package-name></code></td> 156 <td>If you specify one or more packages this way, the Monkey will <i>only</i> allow the system 157 to visit activities within those packages. If your application requires access to activities in 158 other packages (e.g. to select a contact) you'll need to specify those packages as well. 159 If you don't specify any packages, the Monkey will allow the system to launch activities 160 in all packages. To specify multiple packages, use the -p option multiple times — one -p 161 option per package.</td> 162 </tr> 163 164 <tr> 165 <td><code>-c <main-category></code></td> 166 <td>If you specify one or more categories this way, the Monkey will <i>only</i> allow the 167 system to visit activities that are listed with one of the specified categories. 168 If you don't specify any categories, the Monkey will select activities listed with the category 169 Intent.CATEGORY_LAUNCHER or Intent.CATEGORY_MONKEY. To specify multiple categories, use the -c 170 option multiple times — one -c option per category.</td> 171 </tr> 172 173 <tr> 174 <td rowspan="8">Debugging</td> 175 <td><code>--dbg-no-events</code></td> 176 <td>When specified, the Monkey will perform the initial launch into a test activity, but 177 will not generate any further events. 178 For best results, combine with -v, one or more package constraints, and a non-zero throttle to keep the Monkey 179 running for 30 seconds or more. This provides an environment in which you can monitor package 180 transitions invoked by your application.</td> 181 </tr> 182 183 <tr> 184 <td><code>--hprof</code></td> 185 <td>If set, this option will generate profiling reports immediately before and after 186 the Monkey event sequence. 187 This will generate large (~5Mb) files in data/misc, so use with care. See 188 <a href="{@docRoot}guide/developing/tools/traceview.html" title="traceview">Traceview</a> for more information 189 on trace files.</td> 190 </tr> 191 192 <tr> 193 <td><code>--ignore-crashes</code></td> 194 <td>Normally, the Monkey will stop when the application crashes or experiences any type of 195 unhandled exception. If you specify this option, the Monkey will continue to send events to 196 the system, until the count is completed.</td> 197 </tr> 198 199 <tr> 200 <td><code>--ignore-timeouts</code></td> 201 <td>Normally, the Monkey will stop when the application experiences any type of timeout error such 202 as a "Application Not Responding" dialog. If you specify this option, the Monkey will continue to 203 send events to the system, until the count is completed.</td> 204 </tr> 205 206 <tr> 207 <td><code>--ignore-security-exceptions</code></td> 208 <td>Normally, the Monkey will stop when the application experiences any type of permissions error, 209 for example if it attempts to launch an activity that requires certain permissions. If you specify 210 this option, the Monkey will continue to send events to the system, until the count is 211 completed.</td> 212 </tr> 213 214 <tr> 215 <td><code>--kill-process-after-error</code></td> 216 <td>Normally, when the Monkey stops due to an error, the application that failed will be left 217 running. When this option is set, it will signal the system to stop the process in which the error 218 occurred. 219 Note, under a normal (successful) completion, the launched process(es) are not stopped, and 220 the device is simply left in the last state after the final event.</td> 221 </tr> 222 223 <tr> 224 <td><code>--monitor-native-crashes</code></td> 225 <td>Watches for and reports crashes occurring in the Android system native code. If --kill-process-after-error is set, the system will stop.</td> 226 </tr> 227 228 <tr> 229 <td><code>--wait-dbg</code></td> 230 <td>Stops the Monkey from executing until a debugger is attached to it.</td> 231 </tr> 232 233 </table> 234 235 <!-- TODO: add a section called "debugging" that covers ways to use it, 236 need to clear data, use of the seed, etc. --> 237 238 <!-- TODO: add a section that lays down a contract for Monkey output so it can be 239 scripted safely. --> 240 241