1 page.title=uiautomator 2 parent.title=Tools 3 parent.link=index.html 4 @jd:body 5 6 <div id="qv-wrapper"> 7 <div id="qv"> 8 <h2>In this document</h2> 9 <ul> 10 <li><a href="#syntax">Syntax</a></li> 11 <li><a href="#options">Options</a></li> 12 <lI><a href="#api">uiautomator API</a> 13 <ul> 14 <li><a href="#classes">Classes</a></li> 15 <li><a href="#interfaces">Interfaces</a></li> 16 <li><a href="#exceptions">Exceptions</a></li> 17 </ul> 18 </lI> 19 </ul> 20 </div> 21 </div> 22 23 <p>The {@code uiautomator} testing framework lets you test your user interface (UI) efficiently by creating automated functional UI testcases that can be run against your app on one or more devices.</p> 24 <p>For more information on testing with the {@code uiautomator} framework, see <a href="{@docRoot}tools/testing/testing_ui.html">UI Testing</a>.</p> 25 26 <h2 id="syntax">Syntax</h2> 27 <p>To run your testcases on the target device, you can use the {@code adb shell} command to invoke the {@code uiautomator} tool. The syntax is: 28 <pre> 29 adb shell uiautomator runtest <JARS> -c <CLASSES> [options] 30 </pre> 31 </p> 32 <p>Heres an example:</p> 33 <pre>adb shell uiautomator runtest LaunchSettings.jar -c com.uia.example.my.LaunchSettings</pre> 34 35 <h2 id="options">Command-line Options</h2> 36 <p>The following table describes the subcommands and options for {@code uiautomator}.</p> 37 38 <p class="table-caption" id="table1"> 39 <strong>Table 1.</strong> Command-line options for {@code uiautomator}</p> 40 <table> 41 <tr> 42 <th>Subcommand</th> 43 <th>Option</th> 44 <th>Description</th> 45 </tr> 46 47 <tr> 48 <td rowspan="7"><code>runtest</code></td> 49 <td><nobr>{@code <JARS>}</nobr></td> 50 <td><strong>Required</strong>. The {@code <JARS>} argument is the name of one or more JAR files that you deployed to the target device which contain your uiautomator testcases. You can list more than one JAR file by using a space as a separator.</td> 51 </tr> 52 53 <tr> 54 <td><nobr><code>-c <CLASSES> </code></nobr></td> 55 <td><strong>Required (API 17 or lower)</strong>.The {@code <CLASSES>} 56 argument is a list of test classes or test methods in {@code <JARS>} to run. 57 <p>Each class or method must be fully 58 qualified with the package name, in one of these formats: 59 <ul> 60 <li>{@code package_name.class_name}</li> 61 <li>{@code package_name.class_name#method_name}</li> 62 </ul> 63 You can list multiple classes or methods by using a space as a separator.</p> 64 <p class="note"><strong>Note:</strong>This argument is not required for API 18 65 and higher. If not specified, all test cases in {@code <JARS>} will be run. 66 </p> 67 </td> 68 </tr> 69 70 <tr> 71 <td><nobr><code>--nohup</code></nobr></td> 72 <td>Runs the test to completion on the device even if its parent process is terminated (for example, if the device is disconnected).</td> 73 </tr> 74 75 <tr> 76 <td><nobr><code>-e <NAME> <VALUE></code></nobr></td> 77 <td><p>Specify other name-value pairs to be passed to test classes. May be repeated.</p><p class="note"><strong>Note: </strong>The {@code -e} options cannot be combined; you must prefix each option with a separate {@code -e} flag. </p></td> 78 </tr> 79 80 <tr> 81 <td><nobr><code>-e debug [true|false]</code></nobr></td> 82 <td>Wait for debugger to connect before starting.</td> 83 </tr> 84 85 <tr> 86 <td><code>dump [file]</code></td> 87 <td>Generate an XML file with a dump of the current UI hierarchy. If a filepath is not specified, by default, the generated dump file is stored on the device in this location {@code /storage/sdcard0/window_dump.xml}.</td> 88 </tr> 89 90 <tr> 91 <td><nobr><code>-e outputFormat simple | -s</code></nobr></td> 92 <td>Enables less verbose JUnit style output.</td> 93 </tr> 94 95 <tr> 96 <td><code>events</code></td> 97 <td> </td> 98 <td>Prints out accessibility events to the console until the connection to the device is terminated</td> 99 </tr> 100 </table> 101 102 <h2 id="api">uiautomator API</h2> 103 <p>The {@code uiautomator} API is bundled in the {@code uiautomator.jar} file under the {@code <android-sdk>/platforms/} directory. The API includes these key classes, interfaces, and exceptions that allow you to capture and manipulate UI components on the target app:</p> 104 105 <h3 id="classes">Classes</h3> 106 <table> 107 <tr> 108 <th>Class</th> 109 <th>Description</th> 110 </tr> 111 112 <tr> 113 <td><nobr><a href="{@docRoot}tools/help/uiautomator/UiCollection.html">{@code com.android.uiautomator.core.UiCollection}</a></nobr></td> 114 <td>Used to enumerate a container's user interface (UI) elements for the purpose of counting, or targeting a sub elements by a child's text or description.</td> 115 </tr> 116 117 <tr> 118 <td><nobr><a href="{@docRoot}tools/help/uiautomator/UiDevice.html">{@code com.android.uiautomator.core.UiDevice}</a></nobr></td> 119 <td>Provides access to state information about the device. You can also use this class to simulate user actions on the device, such as pressing the d-pad hardware button or pressing the Home and Menu buttons.</td> 120 </tr> 121 122 <tr> 123 <td><nobr><a href="{@docRoot}tools/help/uiautomator/UiObject.html">{@code com.android.uiautomator.core.UiObject}</a></nobr></td> 124 <td>Represents a user interface (UI) element.</td> 125 </tr> 126 127 <tr> 128 <td><nobr><a href="{@docRoot}tools/help/uiautomator/UiScrollable.html">{@code com.android.uiautomator.core.UiScrollable}</a></nobr></td> 129 <td>Provides support for searching for items in a scrollable UI container.</td> 130 </tr> 131 132 <tr> 133 <td><nobr><a href="{@docRoot}tools/help/uiautomator/UiSelector.html">{@code com.android.uiautomator.core.UiSelector}</a></nobr></td> 134 <td>Represents a query for one or more target UI elements on a device screen. </td> 135 </tr> 136 137 <tr> 138 <td><nobr><a href="{@docRoot}tools/help/uiautomator/Configurator.html">{@code com.android.uiautomator.core.Configurator}</a></nobr></td> 139 <td>Allows you to set key parameters for running uiautomator tests.</td> 140 </tr> 141 142 </table> 143 144 <h3 id="interfaces">Interfaces</h3> 145 146 <table> 147 <tr> 148 <th>Interface</th> 149 <th>Description</th> 150 </tr> 151 152 <tr> 153 <td><nobr><a href="{@docRoot}tools/help/uiautomator/UiWatcher.html">{@code com.android.uiautomator.core.UiWatcher}</a></nobr></td> 154 <td>Represents a conditional watcher on the target device.</td> 155 </tr> 156 157 <tr> 158 <td><nobr><a href="{@docRoot}tools/help/uiautomator/IAutomationSupport.html">{@code com.android.uiautomator.testrunner.IAutomationSupport}</a></nobr></td> 159 <td>Provides auxiliary support for running test cases.</td> 160 </tr> 161 162 <tr> 163 <td><nobr><a href="{@docRoot}tools/help/uiautomator/UiAutomatorTestCase.html">{@code com.android.uiautomator.testrunner.UiAutomatorTestCase}</a></nobr></td> 164 <td>Defines an environment for running multiple tests. All {@code uiautomator} test cases should extend this class.</td> 165 </tr> 166 167 </table> 168 169 <h3 id="exceptions">Exceptions</h3> 170 171 <table> 172 <tr> 173 <th>Exception</th> 174 <th>Description</th> 175 </tr> 176 177 <tr> 178 <td><nobr><a href="{@docRoot}tools/help/uiautomator/UiObjectNotFoundException.html">{@code com.android.uiautomator.core.UiObjectNotFoundException}</a></nobr></td> 179 <td>Indicates when a a <a href="{@docRoot}tools/help/uiautomator/UiSelector.html">{@code UiSelector}</a> could not be matched to any UI element displayed.</td> 180 </tr> 181 182 </table> 183 184 185 186 187 188 189
