1 page.title=Testing Support Library 2 page.metaDescription=The Android Testing Support Library provides an extensive framework for testing Android apps. 3 page.image=images/tools/studio-test-module.png 4 5 @jd:body 6 7 <div id="qv-wrapper"> 8 <div id="qv"> 9 <h2> 10 In this document 11 </h2> 12 13 <ol> 14 <li> 15 <a href="#features">Testing Support Library Features</a> 16 <ol> 17 <li> 18 <a href="#AndroidJUnitRunner">AndroidJUnitRunner</a> 19 </li> 20 21 <li> 22 <a href="#Espresso">Espresso</a> 23 </li> 24 25 <li> 26 <a href="#UIAutomator">UI Automator</a> 27 </li> 28 </ol> 29 </li> 30 31 <li> 32 <a href="#setup">Testing Support Library Setup</a> 33 </li> 34 </ol> 35 36 <h2>See also</h2> 37 <ol> 38 <li><a href="{@docRoot}reference/android/support/test/package-summary.html"> 39 Testing Support Library API Reference</a></li> 40 <li><a href="https://github.com/googlesamples/android-testing" class="external-link"> 41 Code Samples</a></li> 42 </ol> 43 </div> 44 </div> 45 46 <p> 47 The Android Testing Support Library provides an extensive framework for testing Android apps. 48 This library provides a set of APIs that allow you to quickly build and run test code for 49 your apps, including JUnit 4 and functional user interface (UI) tests. You can run tests 50 created using these APIs from the <a href= 51 "{@docRoot}tools/studio/index.html">Android Studio IDE</a> or from the command line. 52 </p> 53 54 <p>The Android Testing Support library is available through the Android SDK Manager. 55 For more information, see <a href="#setup">Testing Support Library Setup</a> 56 </p> 57 58 <p> 59 This page provides information about what tools are provided in the Android Testing Support 60 Library, how to use them in your testing environment, and information about library releases. 61 </p> 62 63 <h2 id="features"> 64 Testing Support Library Features 65 </h2> 66 67 <p> 68 The Android Testing Support Library includes the following test automation tools: 69 </p> 70 71 <ul> 72 <li> 73 <strong><a href="#AndroidJUnitRunner">AndroidJUnitRunner</a></strong>: JUnit 4-compatible 74 test runner for Android 75 </li> 76 77 <li> 78 <strong><a href="#Espresso">Espresso</a></strong>: UI testing framework; suitable for 79 functional UI testing within an app 80 </li> 81 82 <li> 83 <strong><a href="#UIAutomator">UI Automator</a></strong>: UI testing framework; suitable 84 for cross-app functional UI testing across system and installed apps 85 </li> 86 </ul> 87 88 <h3 id="AndroidJUnitRunner"> 89 AndroidJUnitRunner 90 </h3> 91 92 <p> 93 The 94 <a href="{@docRoot}reference/android/support/test/runner/AndroidJUnitRunner.html">{@code AndroidJUnitRunner}</a> 95 class is a <a href="http://junit.org/" class="external-link">JUnit</a> test runner that lets you 96 run JUnit 3 or JUnit 4-style test classes on Android devices, including those using the 97 <a href="#Espresso">Espresso</a> and <a href="#UIAutomator">UI Automator</a> testing frameworks. 98 The test runner handles loading your test package and the app under test 99 to a device, running your tests, and reporting test results. This class replaces the {@link 100 android.test.InstrumentationTestRunner} class, which only supports JUnit 3 tests. 101 </p> 102 103 <p> 104 The key features of this test runner include: 105 </p> 106 107 <ul> 108 <li><a href="#ajur-junit">JUnit support</a> 109 </li> 110 111 <li><a href="#ajur-instrumentation">Access to instrumentation information</a> 112 </li> 113 114 <li><a href="#ajur-filtering">Test filtering</a> 115 </li> 116 117 <li><a href="#ajur-sharding">Test sharding</a> 118 </li> 119 </ul> 120 121 <p>Requires Android 2.2 (API level 8) or higher.</p> 122 123 <h4 id="ajur-junit"> 124 JUnit support 125 </h4> 126 127 <p> 128 The test runner is compatible with your JUnit 3 and JUnit 4 (up to JUnit 129 4.10) tests. However, you should avoid mixing JUnit 3 and and JUnit 4 test code in the same 130 package, as this might cause unexpected results. If you are creating an instrumented JUnit 4 131 test class to run on a device or emulator, your test class must be prefixed with the 132 {@code @RunWith(AndroidJUnit4.class)} annotation. 133 </p> 134 135 <p>The following code snippet shows how you might write an instrumented JUnit 4 test to validate 136 that the <em>add</em> operation in the {@code CalculatorActivity} class works correctly. 137 </p> 138 139 <pre> 140 import android.support.test.runner.AndroidJUnit4; 141 import android.support.test.runner.AndroidJUnitRunner; 142 import android.test.ActivityInstrumentationTestCase2; 143 144 @RunWith(AndroidJUnit4.class) 145 public class CalculatorInstrumentationTest 146 extends ActivityInstrumentationTestCase2<CalculatorActivity> { 147 148 @Before 149 public void setUp() throws Exception { 150 super.setUp(); 151 152 // Injecting the Instrumentation instance is required 153 // for your test to run with AndroidJUnitRunner. 154 injectInstrumentation(InstrumentationRegistry.getInstrumentation()); 155 mActivity = getActivity(); 156 } 157 158 @Test 159 public void typeOperandsAndPerformAddOperation() { 160 // Call the CalculatorActivity add() method and pass in some operand values, then 161 // check that the expected value is returned. 162 } 163 164 @After 165 public void tearDown() throws Exception { 166 super.tearDown(); 167 } 168 } 169 </pre> 170 171 <h4 id="ajur-instrumentation"> 172 Access to instrumentation information 173 </h4> 174 175 <p> 176 You can use the 177 <a href="{@docRoot}reference/android/support/test/InstrumentationRegistry.html">{@code InstrumentationRegistry}</a> 178 class to access information related to your 179 test run. This class includes the {@link android.app.Instrumentation} object, target app {@link 180 android.content.Context} object, test app {@link android.content.Context} object, and the 181 command line arguments passed into your test. This data is useful when you are writing tests 182 using the UI Automator framework or when writing tests that have dependencies on the {@link 183 android.app.Instrumentation} or {@link android.content.Context} objects. 184 </p> 185 186 <h4 id="ajur-filtering"> 187 Test filtering 188 </h4> 189 190 <p> 191 In your JUnit 4.x tests, you can use annotations to configure the test run. This feature 192 minimizes the need to add boilerplate and conditional code in your tests. In addition to the 193 standard annotations supported by JUnit 4, the test runner also supports Android-specific 194 annotations, including: 195 </p> 196 197 <ul> 198 <li><a href="{@docRoot}reference/android/support/test/filters/RequiresDevice.html">{@code @RequiresDevice}</a>: 199 Specifies that the test should run only on physical devices, not on emulators. 200 </li> 201 202 <li><a href="{@docRoot}reference/android/support/test/filters/SdkSuppress.html">{@code @SdkSupress}</a>: 203 Suppresses the test from running on a lower Android API level than the given level. For 204 example, to suppress tests on all API levels lower than 18 from running, use the annotation 205 {@code @SDKSupress(minSdkVersion=18)}. 206 </li> 207 208 <li>{@link android.test.suitebuilder.annotation.SmallTest @SmallTest}, 209 {@link android.test.suitebuilder.annotation.MediumTest @MediumTest}, 210 and {@link android.test.suitebuilder.annotation.LargeTest @LargeTest}: Classify how long 211 a test should take to run, and consequently, how frequently you can run the test. 212 </li> 213 </ul> 214 215 <h4 id="ajur-sharding"> 216 Test sharding 217 </h4> 218 219 <p> 220 The test runner supports splitting a single test suite into multiple 221 <em>shards</em>, so you can easily run tests belonging to the same shard together as a group, 222 under the same {@link android.app.Instrumentation} instance. Each shard is identified by an 223 index number. When running tests, use the {@code -e numShards} option to specify the number 224 of separate shards to create and the {@code -e shardIndex} option to specify which shard to 225 run. 226 </p> 227 228 <p> 229 For example, to split the test suite into 10 shards and run only the tests grouped in the 230 second shard, use the following command: 231 </p> 232 233 <pre> 234 adb shell am instrument -w -e numShards 10 -e shardIndex 2</pre> 235 236 <p> 237 To learn more about using this test runner, see the 238 <a href="{@docRoot}reference/android/support/test/package-summary.html">API reference</a>. 239 </p> 240 241 <h3 id="Espresso"> 242 Espresso 243 </h3> 244 245 <p> 246 The Espresso testing framework provides a set of APIs to build UI tests to test user flows 247 within an app. These APIs let you write automated UI tests that are concise and that run 248 reliably. Espresso is well-suited for writing <em>white box</em>-style automated tests, where 249 the test code utilizes implementation code details from the app under test. 250 </p> 251 252 <p> 253 The key features of the Espresso testing framework include: 254 </p> 255 256 <ul> 257 <li>Flexible APIs for view and adapter matching in target apps. 258 For more information, see <a href="#espresso-matching">View matching</a>. 259 260 <li>An extensive set of action APIs to automate UI interactions. 261 For more information, see <a href="#espresso-actions">Action APIs</a>. 262 </li> 263 264 <li>UI thread synchronization to improve test reliability. 265 For more information, see <a href="#espresso-thread-sync">UI thread synchronization</a>. 266 </li> 267 </ul> 268 269 <p>Requires Android 2.2 (API level 8) or higher.</p> 270 271 <h4 id="espresso-matching"> 272 View matching 273 </h4> 274 275 <p> 276 The <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)">{@code Espresso.onView()}</a> 277 method lets you access a UI component in the target app and 278 interact with it. The method accepts a 279 <a href="http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/Matcher.html" 280 class="external-link">{@code Matcher}</a> argument and searches the view 281 hierarchy to locate a corresponding {@link android.view.View} instance that meets some given 282 criteria. You can refine searches by specifying such criteria as: 283 </p> 284 285 <ul> 286 <li>The class name of the view 287 </li> 288 289 <li>The content description of the view 290 </li> 291 292 <li>The {@code R.id} of the view 293 </li> 294 295 <li>Text displayed in the view 296 </li> 297 </ul> 298 299 <p> 300 For example, to target a button that has the ID value of {@code my_button}, you can specify 301 a matcher like this: 302 </p> 303 304 <pre> 305 onView(withId(R.id.my_button));</pre> 306 307 <p> 308 If the search is successful, the 309 <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)">{@code onView()}</a> 310 method returns a reference which lets you 311 perform user actions and test assertions against the target view. 312 </p> 313 314 <h4> 315 Adapter matching 316 </h4> 317 318 <p> 319 In an {@link android.widget.AdapterView} layout, the layout is dynamically populated with 320 children views at runtime. If the target view is inside a layout subclassed from {@link 321 android.widget.AdapterView} (such as a {@link android.widget.ListView} or {@link 322 android.widget.GridView}), the 323 <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)">{@code onView()}</a> 324 method might not work because only a subset of 325 the layouts views may be loaded in the current view hierarchy. 326 </p> 327 328 <p> 329 Instead, use the <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)">{@code Espresso.onData()}</a> 330 method to access a target view element. The <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)">{@code Espresso.onData()}</a> 331 method returns a reference which lets you perform user actions and test assertions against the 332 elements in an {@link android.widget.AdapterView}. 333 </p> 334 335 <h4 id="espresso-actions"> 336 Action APIs 337 </h4> 338 339 <p> 340 Typically, you test an app by performing some user interactions against the apps user 341 interface. You can easily automate these actions in your test by using the 342 <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html">{@code ViewActions}</a> 343 API. You can perform such UI interactions as: 344 </p> 345 346 <ul> 347 <li>View clicks 348 </li> 349 350 <li>Swipes 351 </li> 352 353 <li>Key and button presses 354 </li> 355 356 <li>Typing text 357 </li> 358 359 <li>Opening a link 360 </li> 361 </ul> 362 363 <p> 364 For example, to simulate entering a string value and pressing a button to submit the value, 365 you can write an automated test script like this. The 366 <a href="{@docRoot}reference/android/support/test/espresso/ViewInteraction.html#perform(android.support.test.espresso.ViewAction...)">{@code ViewInteraction.perform()}</a> 367 and <a href="{@docRoot}reference/android/support/test/espresso/DataInteraction.html#perform(android.support.test.espresso.ViewAction...)">{@code DataInteraction.perform()}</a> 368 methods take one or more 369 <a href="{@docRoot}reference/android/support/test/espresso/ViewAction.html">{@code ViewAction}</a> 370 arguments and run the actions in the order provided. 371 </p> 372 373 <pre> 374 // Type text into an EditText view, then close the soft keyboard 375 onView(withId(R.id.editTextUserInput)) 376 .perform(typeText(STRING_TO_BE_TYPED), closeSoftKeyboard()); 377 378 // Press the button to submit the text change 379 onView(withId(R.id.changeTextBt)).perform(click());</pre> 380 381 <h4 id="espresso-thread-sync"> 382 UI thread synchronization 383 </h4> 384 385 <p> 386 Tests on Android devices can fail randomly because of timing issues. This testing issue is 387 referred to as <em>test flakiness</em>. Prior to Espresso, the workaround was to insert a 388 sufficiently long sleep or timeout period into a test or to add code to keep retrying the 389 failing operation. The Espresso testing framework handles synchronization between the 390 {@link android.app.Instrumentation} and the UI thread; this removes the need for the previous 391 timing workarounds and ensures that your test actions and assertions run more reliably. 392 </p> 393 394 <p> 395 To learn more about using Espresso, see the 396 <a href="{@docRoot}reference/android/support/test/package-summary.html">API reference</a> and 397 <a href="{@docRoot}training/testing/ui-testing/espresso-testing.html"> 398 Testing UI for a Single App</a> training. 399 </p> 400 401 <h3 id="UIAutomator"> 402 UI Automator 403 </h3> 404 405 <p> 406 The UI Automator testing framework provides a set of APIs to build UI tests that perform 407 interactions on user apps and system apps. The UI Automator APIs allows you to perform 408 operations such as opening the Settings menu or the app launcher in a test device. The UI 409 Automator testing framework is well-suited for writing <em>black box</em>-style automated 410 tests, where the test code does not rely on internal implementation details of the target 411 app. 412 </p> 413 414 <p> 415 The key features of the UI Automator testing framework include: 416 </p> 417 418 <ul> 419 <li>A viewer to inspect layout hierarchy. 420 For more information, see <a href="#uia-viewer">UI Automator Viewer</a>. 421 </li> 422 <li>An API to retrieve state information and perform operations on the target device. 423 For more information, see <a href="#uia-device-state">Access to device state</a>. 424 </li> 425 <li>APIs that support cross-app UI testing. 426 For more information, see <a href="#uia-apis">UI Automator APIs</a> . 427 </li> 428 </ul> 429 430 <p>Requires Android 4.3 (API level 18) or higher.</p> 431 432 <h4 id="uia-viewer"> 433 UI Automator Viewer 434 </h4> 435 436 <p> 437 The {@code uiautomatorviewer} tool provides a convenient GUI to scan and analyze the UI 438 components currently displayed on an Android device. You can use this tool to inspect the 439 layout hierarchy and view the properties of UI components that are visible on the foreground 440 of the device. This information lets you create more fine-grained tests using UI Automator, 441 for example by creating a UI selector that matches a specific visible property. 442 </p> 443 444 <p> 445 The {@code uiautomatorviewer} tool is located in the {@code <android-sdk>/tools/} 446 directory. 447 </p> 448 449 <h4 id="uia-device-state"> 450 Access to device state 451 </h4> 452 453 <p> 454 The UI Automator testing framework provides a 455 <a href="{@docRoot}reference/android/support/test/uiautomator/UiDevice.html">{@code UiDevice}</a> 456 class to access and perform operations on the device on which the target app is running. You 457 can call its methods to access device properties such as current orientation or display size. 458 The <a href="{@docRoot}reference/android/support/test/uiautomator/UiDevice.html">{@code UiDevice}</a> 459 class also let you perform actions such as: 460 </p> 461 462 <ul> 463 <li>Change the device rotation 464 </li> 465 466 <li>Press a D-pad button 467 </li> 468 469 <li>Press the Back, Home, or Menu buttons 470 </li> 471 472 <li>Open the notification shade 473 </li> 474 475 <li>Take a screenshot of the current window 476 </li> 477 </ul> 478 479 <p> 480 For example, to simulate a Home button press, call the {@code UiDevice.pressHome()} method. 481 </p> 482 483 <h4 id="uia-apis"> 484 UI Automator APIs 485 </h4> 486 487 <p> 488 The UI Automator APIs allow you to write robust tests without needing to know about the 489 implementation details of the app that you are targeting. You can use these APIs to capture 490 and manipulate UI components across multiple apps: 491 </p> 492 493 <ul> 494 <li><a href="{@docRoot}reference/android/support/test/uiautomator/UiCollection.html">{@code UiCollection}</a>: 495 Enumerates a container's UI elements for the purpose of counting, 496 or targeting sub-elements by their visible text or content-description property. 497 </li> 498 499 <li><a href="{@docRoot}reference/android/support/test/uiautomator/UiObject.html">{@code UiObject}</a>: 500 Represents a UI element that is visible on the device. 501 </li> 502 503 <li><a href="{@docRoot}reference/android/support/test/uiautomator/UiScrollable.html">{@code UiScrollable}</a>: 504 Provides support for searching for items in a scrollable UI container. 505 </li> 506 507 <li><a href="{@docRoot}reference/android/support/test/uiautomator/UiSelector.html">{@code UiSelector}</a>: 508 Represents a query for one or more target UI elements on a device. 509 </li> 510 511 <li><a href="{@docRoot}reference/android/support/test/uiautomator/Configurator.html">{@code Configurator}</a>: 512 Allows you to set key parameters for running UI Automator tests. 513 </li> 514 </ul> 515 516 <p> 517 For example, the following code shows how you can write a test script that brings up the 518 default app launcher in the device: 519 </p> 520 521 <pre> 522 // Initialize UiDevice instance 523 mDevice = UiDevice.getInstance(getInstrumentation()); 524 525 // Perform a short press on the HOME button 526 mDevice.pressHome(); 527 528 // Bring up the default launcher by searching for 529 // a UI component that matches the content-description for the launcher button 530 UiObject allAppsButton = mDevice 531 .findObject(new UiSelector().description("Apps")); 532 533 // Perform a click on the button to bring up the launcher 534 allAppsButton.clickAndWaitForNewWindow();</pre> 535 536 <p> 537 To learn more about using UI Automator, see the 538 <a href="{@docRoot}reference/android/support/test/package-summary.html">API reference</a> and 539 <a href="{@docRoot}training/testing/ui-testing/uiautomator-testing.html"> 540 Testing UI for Multiple Apps</a> training. 541 </p> 542 543 <h2 id="setup"> 544 Testing Support Library Setup 545 </h2> 546 547 <p> 548 The Android Testing Support Library package is included with the latest version of the 549 Android Support Repository, which you can obtain as a supplemental download through the 550 Android SDK Manager. 551 </p> 552 553 <p> 554 To download the Android Support Repository through the SDK Manager: 555 </p> 556 557 <ol> 558 <li>Start the <a href="{@docRoot}tools/help/sdk-manager.html">Android SDK Manager</a>. 559 </li> 560 561 <li>In the SDK Manager window, scroll to the end of the <i>Packages</i> list, find the 562 <em>Extras</em> folder and, if necessary, expand to show its contents. 563 </li> 564 565 <li>Select the <strong>Android Support Repository</strong> item. 566 </li> 567 568 <li>Click the <strong>Install packages...</strong> button. 569 </li> 570 </ol> 571 572 <p> 573 After downloading, the tool installs the Support Repository files to your existing Android 574 SDK directory. The library files are located in the following subdirectory of your SDK: 575 {@code <sdk>/extras/android/m2repository} directory. 576 </p> 577 578 <p> 579 The Android Testing Support Library classes are located under the 580 {@code android.support.test} package. 581 </p> 582 583 <p> 584 To use the Android Testing Support Library in your Gradle project, add these dependencies in 585 your {@code build.gradle} file: 586 </p> 587 588 <pre> 589 dependencies { 590 androidTestCompile 'com.android.support.test:runner:0.4' 591 // Set this dependency to use JUnit 4 rules 592 androidTestCompile 'com.android.support.test:rules:0.4' 593 // Set this dependency to build and run Espresso tests 594 androidTestCompile 'com.android.support.test.espresso:espresso-core:2.2.1' 595 // Set this dependency to build and run UI Automator tests 596 androidTestCompile 'com.android.support.test.uiautomator:uiautomator-v18:2.1.2' 597 }</pre> 598 599 <p>To set 600 <a href="{@docRoot}reference/android/support/test/runner/AndroidJUnitRunner.html">{@code AndroidJUnitRunner}</a> 601 as the default test instrumentation runner in your Gradle project, specify this dependency in 602 your {@code build.gradle} file:</p> 603 604 <pre> 605 android { 606 defaultConfig { 607 testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner" 608 } 609 }</pre> 610 611 <p> 612 It is strongly recommended that you use the Android Testing Support Library together with the 613 Android Studio IDE. Android Studio offers capabilities that support test 614 development, such as: 615 </p> 616 617 <ul> 618 <li>Flexible Gradle-based build system that supports dependency management for your test code 619 </li> 620 621 <li>Single project structure to contain your unit and instrumented test code together with 622 your app source code 623 </li> 624 625 <li>Support for deploying and running tests on virtual or physical devices, from a 626 command line or graphical user interface 627 </li> 628 </ul> 629 630 <p> 631 For more information about Android Studio and to download it, see 632 <a href="{@docRoot}studio/index.html">Download Android Studio and SDK Tools</a>. 633 </p> 634
