| page.title=Testing UI for a Single App |
| page.tags=testing,espresso |
| trainingnavtop=true |
| |
| @jd:body |
| |
| <!-- This is the training bar --> |
| <div id="tb-wrapper"> |
| <div id="tb"> |
| <h2>Dependencies and Prerequisites</h2> |
| |
| <ul> |
| <li>Android 2.2 (API level 8) or higher |
| </li> |
| |
| <li> |
| <a href="{@docRoot}tools/testing-support-library/index.html">Android Testing Support |
| Library</a> |
| </li> |
| </ul> |
| |
| <h2> |
| This lesson teaches you to |
| </h2> |
| |
| <ol> |
| <li> |
| <a href="#setup">Set Up Espresso</a> |
| </li> |
| |
| <li> |
| <a href="#build">Create an Espresso Test Class</a> |
| </li> |
| |
| <li> |
| <a href="#run">Run Espresso Tests on a Device or Emulator</a> |
| </li> |
| </ol> |
| |
| <h2> |
| You should also read |
| </h2> |
| |
| <ul> |
| <li><a href="{@docRoot}reference/android/support/test/package-summary.html"> |
| Espresso API Reference</a></li> |
| </ul> |
| |
| <h2> |
| Try it out |
| </h2> |
| |
| <ul> |
| <li> |
| <a href="https://github.com/googlesamples/android-testing" |
| class="external-link">Espresso Code Samples</a> |
| </li> |
| </ul> |
| </div> |
| </div> |
| |
| <p> |
| Testing user interactions |
| within a single app helps to ensure that users do not |
| encounter unexpected results or have a poor experience when interacting with your app. |
| You should get into the habit of creating user interface (UI) tests if you need to verify |
| that the UI of your app is functioning correctly. |
| </p> |
| |
| <p> |
| The Espresso testing framework, provided by the |
| <a href="{@docRoot}tools/testing-support-library/index.html">Android Testing Support Library</a>, |
| provides APIs for writing UI tests to simulate user interactions within a |
| single target app. Espresso tests can run on devices running Android 2.2 (API level 8) and |
| higher. A key benefit of using Espresso is that it provides automatic synchronization of test |
| actions with the UI of the app you are testing. Espresso detects when the main thread is idle, |
| so it is able to run your test commands at the appropriate time, improving the reliability of |
| your tests. This capability also relieves you from having to adding any timing workarounds, |
| such as a sleep period, in your test code. |
| </p> |
| |
| <p> |
| The Espresso testing framework is an instrumentation-based API and works |
| with the |
| <a href="{@docRoot}reference/android/support/test/runner/AndroidJUnitRunner.html">{@code |
| AndroidJUnitRunner}</a> test runner. |
| </p> |
| |
| <h2 id="setup"> |
| Set Up Espresso |
| </h2> |
| |
| <p> |
| Before you begin using Espresso, you must: |
| </p> |
| |
| <ul> |
| <li> |
| <strong>Install the Android Testing Support Library</strong>. The Espresso API is |
| located under the {@code com.android.support.test.espresso} package. These classes allow |
| you to create tests that use the Espresso testing framework. To learn how to install the |
| library, see <a href="{@docRoot}tools/testing-support-library/index.html#setup"> |
| Testing Support Library Setup</a>. |
| </li> |
| |
| <li> |
| <strong>Set up your project structure.</strong> In your Gradle project, the source code for |
| the target app that you want to test is typically placed under the {@code app/src/main} |
| folder. The source code for instrumentation tests, including |
| your Espresso tests, must be placed under the <code>app/src/androidTest</code> folder. To |
| learn more about setting up your project directory, see |
| <a href="{@docRoot}tools/projects/index.html">Managing Projects</a>. |
| </li> |
| |
| <li> |
| <strong>Specify your Android testing dependencies</strong>. In order for the |
| <a href="{@docRoot}tools/building/plugin-for-gradle.html">Android Plug-in for Gradle</a> to |
| correctly build and run your Espresso tests, you must specify the following libraries in |
| the {@code build.gradle} file of your Android app module: |
| |
| <pre> |
| dependencies { |
| androidTestCompile 'com.android.support.test:testing-support-lib:0.1' |
| androidTestCompile 'com.android.support.test.espresso:espresso-core:2.0' |
| } |
| </pre> |
| </li> |
| |
| <li> |
| <strong>Turn off animations on your test device.</strong> Leaving system animations turned |
| on in the test device might cause unexpected results or may lead your test to fail. Turn |
| off animations from <em>Settings</em> by opening <em>Developing Options</em> and |
| turning all the following options off: |
| <ul> |
| <li> |
| <em>Window animation scale</em> |
| </li> |
| |
| <li> |
| <em>Transition animation scale</em> |
| </li> |
| |
| <li> |
| <em>Animator duration scale</em> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| |
| <h2 id="build"> |
| Create an Espresso Test Class |
| </h2> |
| |
| <p> |
| To create an Espresso test, create a Java class or an |
| {@link android.test.ActivityInstrumentationTestCase2} |
| subclass that follows this programming model: |
| </p> |
| |
| <ol> |
| <li>Find the UI component you want to test in an {@link android.app.Activity} (for example, a |
| sign-in button in the app) by calling the |
| <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)"> |
| {@code onView()}</a> method, or the |
| <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)"> |
| {@code onData()}</a> method for {@link android.widget.AdapterView} controls. |
| </li> |
| |
| <li>Simulate a specific user interaction to perform on that UI component, by calling the |
| <a href="{@docRoot}reference/android/support/test/espresso/ViewInteraction.html#perform(android.support.test.espresso.ViewAction...)">{@code ViewInteraction.perform()}</a> |
| or |
| <a href="{@docRoot}reference/android/support/test/espresso/DataInteraction.html#perform(android.support.test.espresso.ViewAction...)">{@code DataInteraction.perform()}</a> |
| method and passing in the user action (for example, click on the sign-in button). To sequence |
| multiple actions on the same UI component, chain them using a comma-separated list in your |
| method argument. |
| </li> |
| |
| <li>Repeat the steps above as necessary, to simulate a user flow across multiple |
| activities in the target app. |
| </li> |
| |
| <li>Use the |
| <a href="{@docRoot}reference/android/support/test/espresso/assertion/ViewAssertions.html">{@code ViewAssertions}</a> |
| methods to check that the UI reflects the expected |
| state or behavior, after these user interactions are performed. |
| </li> |
| </ol> |
| |
| <p> |
| These steps are covered in more detail in the sections below. |
| </p> |
| |
| <p> |
| The following code snippet shows how your test class might invoke this basic workflow: |
| </p> |
| |
| <pre> |
| onView(withId(R.id.my_view)) // withId(R.id.my_view) is a ViewMatcher |
| .perform(click()) // click() is a ViewAction |
| .check(matches(isDisplayed())); // matches(isDisplayed()) is a ViewAssertion |
| </pre> |
| |
| <h3 id="espresso-aitc2"> |
| Using Espresso with ActivityInstrumentationTestCase2 |
| </h3> |
| |
| <p> |
| If you are subclassing {@link android.test.ActivityInstrumentationTestCase2} |
| to create your Espresso test class, you must inject an |
| {@link android.app.Instrumentation} instance into your test class. This step is required in |
| order for your Espresso test to run with the |
| <a href="{@docRoot}reference/android/support/test/runner/AndroidJUnitRunner.html">{@code AndroidJUnitRunner}</a> |
| test runner. |
| </p> |
| |
| <p> |
| To do this, call the |
| {@link android.test.InstrumentationTestCase#injectInstrumentation(android.app.Instrumentation) injectInstrumentation()} |
| method and pass in the result of |
| <a href="{@docRoot}reference/android/support/test/InstrumentationRegistry.html#getInstrumentation()"> |
| {@code InstrumentationRegistry.getInstrumentation()}</a>, as shown in the following code |
| example: |
| </p> |
| |
| <pre> |
| import android.support.test.InstrumentationRegistry; |
| |
| public class MyEspressoTest |
| extends ActivityInstrumentationTestCase2<MyActivity> { |
| |
| private MyActivity mActivity; |
| |
| public MyEspressoTest() { |
| super(MyActivity.class); |
| } |
| |
| @Before |
| public void setUp() throws Exception { |
| super.setUp(); |
| injectInstrumentation(InstrumentationRegistry.getInstrumentation()); |
| mActivity = getActivity(); |
| } |
| |
| ... |
| } |
| </pre> |
| |
| <p class="note"><strong>Note:</strong> Previously, {@link android.test.InstrumentationTestRunner} |
| would inject the {@link android.app.Instrumentation} instance, but this test runner is being |
| deprecated.</p> |
| |
| <h3 id="accessing-ui-components"> |
| Accessing UI Components |
| </h3> |
| |
| <p> |
| Before Espresso can interact with the app under test, you must first specify the UI component |
| or <em>view</em>. Espresso supports the use of |
| <a href="http://hamcrest.org/" class="external-link">Hamcrest matchers</a> |
| for specifying views and adapters in your app. |
| </p> |
| |
| <p> |
| To find the view, call the <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)"> |
| {@code onView()}</a> |
| method and pass in a view matcher that specifies the view that you are targeting. This is |
| described in more detail in <a href="#specifying-view-matcher">Specifying a View Matcher</a>. |
| The <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)"> |
| {@code onView()}</a> method returns a |
| <a href="{@docRoot}reference/android/support/test/espresso/ViewInteraction.html"> |
| {@code ViewInteraction}</a> |
| object that allows your test to interact with the view. |
| However, calling the <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)"> |
| {@code onView()}</a> method may not work if you want to locate a view in |
| an {@link android.widget.AdapterView} layout. In this case, follow the instructions in |
| <a href="#locating-adpeterview-view">Locating a view in an AdapterView</a> instead. |
| </p> |
| |
| <p class="note"> |
| <strong>Note</strong>: The <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)"> |
| {@code onView()}</a> method does not check if the view you specified is |
| valid. Instead, Espresso searches only the current view hierarchy, using the matcher provided. |
| If no match is found, the method throws a |
| <a href="{@docRoot}reference/android/support/test/espresso/NoMatchingViewException.html"> |
| {@code NoMatchingViewException}</a>. |
| </p> |
| |
| <p> |
| The following code snippet shows how you might write a test that accesses an |
| {@link android.widget.EditText} field, enters a string of text, closes the virtual keyboard, |
| and then performs a button click. |
| </p> |
| |
| <pre> |
| public void testChangeText_sameActivity() { |
| // Type text and then press the button. |
| onView(withId(R.id.editTextUserInput)) |
| .perform(typeText(STRING_TO_BE_TYPED), closeSoftKeyboard()); |
| onView(withId(R.id.changeTextButton)).perform(click()); |
| |
| // Check that the text was changed. |
| ... |
| } |
| </pre> |
| |
| <h4 id="specifying-view-matcher"> |
| Specifying a View Matcher |
| </h4> |
| |
| <p> |
| You can specify a view matcher by using these approaches: |
| </p> |
| |
| <ul> |
| <li>Calling methods in the |
| <a href="{@docRoot}reference/android/support/test/espresso/matcher/ViewMatchers.html"> |
| {@code ViewMatchers}</a> class. For example, to find a view by looking for a text string it |
| displays, you can call a method like this: |
| <pre> |
| onView(withText("Sign-in")); |
| </pre> |
| |
| <p>Similarly you can call |
| <a href="{@docRoot}reference/android/support/test/espresso/matcher/ViewMatchers.html#withId(int)"> |
| {@code withId()}</a> and providing the resource ID ({@code R.id}) of the view, as shown in the |
| following example:</p> |
| |
| <pre> |
| onView(withId(R.id.button_signin)); |
| </pre> |
| |
| <p> |
| Android resource IDs are not guaranteed to be unique. If your test attempts to match to a |
| resource ID used by more than one view, Espresso throws an |
| <a href="{@docRoot}reference/android/support/test/espresso/AmbiguousViewMatcherException.html"> |
| {@code AmbiguousViewMatcherException}</a>. |
| </p> |
| </li> |
| <li>Using the Hamcrest |
| <a href="http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/Matchers.html" |
| class="external-link">{@code Matchers}</a> class. You can use the |
| {@code allOf()} methods to combine multiple matchers, such as |
| {@code containsString()} and {@code instanceOf()}. This approach allows you to |
| filter the match results more narrowly, as shown in the following example: |
| <pre> |
| onView(allOf(withId(R.id.button_signin), withText("Sign-in"))); |
| </pre> |
| <p>You can use the {@code not} keyword to filter for views that don't correspond to the matcher, as |
| shown in the following example:</p> |
| <pre> |
| onView(allOf(withId(R.id.button_signin), not(withText("Sign-out")))); |
| </pre> |
| <p>To use these methods in your test, import the {@code org.hamcrest.Matchers} package. To |
| learn more about Hamcrest matching, see the |
| <a href="http://hamcrest.org/" class="external-link">Hamcrest site</a>. |
| </p> |
| </li> |
| </ul> |
| |
| <p> |
| To improve the performance of your Espresso tests, specify the minimum matching information |
| needed to find your target view. For example, if a view is uniquely identifiable by its |
| descriptive text, you do not need to specify that it is also assignable from the |
| {@link android.widget.TextView} instance. |
| </p> |
| |
| <h4 id="#locating-adpeterview-view"> |
| Locating a view in an AdapterView |
| </h4> |
| |
| <p> |
| In an {@link android.widget.AdapterView} widget, the view is dynamically populated with child |
| views at runtime. If the target view you want to test is inside an |
| {@link android.widget.AdapterView} |
| (such as a {@link android.widget.ListView}, {@link android.widget.GridView}, or |
| {@link android.widget.Spinner}), the |
| <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onView(org.hamcrest.Matcher<android.view.View>)"> |
| {@code onView()}</a> method might not work because only a |
| subset of the views may be loaded in the current view hierarchy. |
| </p> |
| |
| <p> |
| Instead, call the <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)">{@code onData()}</a> |
| method to obtain a |
| <a href="{@docRoot}reference/android/support/test/espresso/DataInteraction.html"> |
| {@code DataInteraction}</a> |
| object to access the target view element. Espresso handles loading the target view element |
| into the current view hierarchy. Espresso also takes care of scrolling to the target element, |
| and putting the element into focus. |
| </p> |
| |
| <p class="note"> |
| <strong>Note</strong>: The |
| <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)">{@code onData()}</a> |
| method does not check if if the item you specified corresponds with a view. Espresso searches |
| only the current view hierarchy. If no match is found, the method throws a |
| <a href="{@docRoot}reference/android/support/test/espresso/NoMatchingViewException.html"> |
| {@code NoMatchingViewException}</a>. |
| </p> |
| |
| <p> |
| The following code snippet shows how you can use the |
| <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)">{@code onData()}</a> |
| method together |
| with Hamcrest matching to search for a specific row in a list that contains a given string. |
| In this example, the {@code LongListActivity} class contains a list of strings exposed |
| through a {@link android.widget.SimpleAdapter}. |
| </p> |
| |
| <pre> |
| onData(allOf(is(instanceOf(Map.class)), |
| hasEntry(equalTo(LongListActivity.ROW_TEXT), is(str)))); |
| </pre> |
| |
| <h3 id="perform-actions"> |
| Performing Actions |
| </h3> |
| |
| <p> |
| Call the <a href="{@docRoot}reference/android/support/test/espresso/ViewInteraction.html#perform(android.support.test.espresso.ViewAction...)">{@code ViewInteraction.perform()}</a> |
| or |
| <a href="{@docRoot}reference/android/support/test/espresso/DataInteraction.html#perform(android.support.test.espresso.ViewAction...)">{@code DataInteraction.perform()}</a> |
| methods to |
| simulate user interactions on the UI component. You must pass in one or more |
| <a href="{@docRoot}reference/android/support/test/espresso/ViewAction.html">{@code ViewAction}</a> |
| objects as arguments. Espresso fires each action in sequence according to |
| the given order, and executes them in the main thread. |
| </p> |
| |
| <p> |
| The |
| <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html">{@code ViewActions}</a> |
| class provides a list of helper methods for specifying common actions. |
| You can use these methods as convenient shortcuts instead of creating and configuring |
| individual <a href="{@docRoot}reference/android/support/test/espresso/ViewAction.html">{@code ViewAction}</a> |
| objects. You can specify such actions as: |
| </p> |
| |
| <ul> |
| <li> |
| <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html#click()">{@code ViewActions.click()}</a>: |
| Clicks on the view. |
| </li> |
| |
| <li> |
| <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html#typeText(java.lang.String)">{@code ViewActions.typeText()}</a>: |
| Clicks on a view and enters a specified string. |
| </li> |
| |
| <li> |
| <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html#scrollTo()">{@code ViewActions.scrollTo()}</a>: |
| Scrolls to the view. The |
| target view must be subclassed from {@link android.widget.ScrollView} |
| and the value of its |
| <a href="http://developer.android.com/reference/android/view/View.html#attr_android:visibility">{@code android:visibility}</a> |
| property must be {@link android.view.View#VISIBLE}. For views that extend |
| {@link android.widget.AdapterView} (for example, |
| {@link android.widget.ListView}), |
| the |
| <a href="{@docRoot}reference/android/support/test/espresso/Espresso.html#onData(org.hamcrest.Matcher<java.lang.Object>)">{@code onData()}</a> |
| method takes care of scrolling for you. |
| </li> |
| |
| <li> |
| <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html#pressKey(int)">{@code ViewActions.pressKey()}</a>: |
| Performs a key press using a specified keycode. |
| </li> |
| |
| <li> |
| <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html#clearText()">{@code ViewActions.clearText()}</a>: |
| Clears the text in the target view. |
| </li> |
| </ul> |
| |
| <p> |
| If the target view is inside a {@link android.widget.ScrollView}, perform the |
| <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html#scrollTo()">{@code ViewActions.scrollTo()}</a> |
| action first to display the view in the screen before other proceeding |
| with other actions. The |
| <a href="{@docRoot}reference/android/support/test/espresso/action/ViewActions.html#scrollTo()">{@code ViewActions.scrollTo()}</a> |
| action will have no effect if the view is already displayed. |
| </p> |
| |
| <h3 id="verify-results"> |
| Verifying Results |
| </h3> |
| |
| <p> |
| Call the |
| <a href="{@docRoot}reference/android/support/test/espresso/ViewInteraction.html#check(android.support.test.espresso.ViewAssertion)">{@code ViewInteraction.check()}</a> |
| or |
| <a href="{@docRoot}reference/android/support/test/espresso/DataInteraction.html#check(android.support.test.espresso.ViewAssertion)">{@code DataInteraction.check()}</a> |
| method to assert |
| that the view in the UI matches some expected state. You must pass in a |
| <a href="{@docRoot}reference/android/support/test/espresso/ViewAssertion.html"> |
| {@code ViewAssertion}</a> object as the argument. If the assertion fails, Espresso throws |
| an {@link junit.framework.AssertionFailedError}. |
| </p> |
| |
| <p> |
| The |
| <a href="{@docRoot}reference/android/support/test/espresso/assertion/ViewAssertions.html">{@code ViewAssertions}</a> |
| class provides a list of helper methods for specifying common |
| assertions. The assertions you can use include: |
| </p> |
| |
| <ul> |
| <li> |
| <a href="{@docRoot}reference/android/support/test/espresso/assertion/ViewAssertions.html#doesNotExist()">{@code doesNotExist}</a>: |
| Asserts that there is no view matching the specified criteria in the current view hierarchy. |
| </li> |
| |
| <li> |
| <a href="{@docRoot}reference/android/support/test/espresso/assertion/ViewAssertions.html#matches(org.hamcrest.Matcher<? super android.view.View>)">{@code matches}</a>: |
| Asserts that the specified view exists in the current view hierarchy |
| and its state matches some given Hamcrest matcher. |
| </li> |
| |
| <li> |
| <a href="{@docRoot}reference/android/support/test/espresso/assertion/ViewAssertions.html#selectedDescendantsMatch(org.hamcrest.Matcher<android.view.View>, org.hamcrest.Matcher<android.view.View>)">{@code selectedDescendentsMatch}</a> |
| : Asserts that the specified children views for a |
| parent view exist, and their state matches some given Hamcrest matcher. |
| </li> |
| </ul> |
| |
| <p> |
| The following code snippet shows how you might check that the text displayed in the UI has |
| the same value as the text previously entered in the |
| {@link android.widget.EditText} field. |
| </p> |
| <pre> |
| public void testChangeText_sameActivity() { |
| // Type text and then press the button. |
| ... |
| |
| // Check that the text was changed. |
| onView(withId(R.id.textToBeChanged)) |
| .check(matches(withText(STRING_TO_BE_TYPED))); |
| } |
| </pre> |
| |
| <h2 id="run">Run Espresso Tests on a Device or Emulator</h2> |
| |
| <p> |
| To run Espresso tests, you must use the |
| <a href="{@docRoot}reference/android/support/test/runner/AndroidJUnitRunner.html">{@code AndroidJUnitRunner}</a> |
| class provided in the |
| <a href="{@docRoot}tools/testing-support-library/index.html"> |
| Android Testing Support Library</a> as your default test runner. The |
| <a href="{@docRoot}tools/building/plugin-for-gradle.html">Android Plug-in for |
| Gradle</a> provides a default directory ({@code src/androidTest/java}) for you to store the |
| instrumented test classes and test suites that you want to run on a device. The |
| plug-in compiles the test code in that directory and then executes the test app using |
| the configured test runner class. |
| </p> |
| |
| <p> |
| To run Espresso tests in your Gradle project: |
| </p> |
| |
| <ol> |
| <li>Specify |
| <a href="{@docRoot}reference/android/support/test/runner/AndroidJUnitRunner.html">{@code AndroidJUnitRunner}</a> |
| as the default test instrumentation runner in |
| your {@code build.gradle} file: |
| |
| <pre> |
| android { |
| defaultConfig { |
| testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner" |
| } |
| }</pre> |
| </li> |
| <li>Run your tests from the command-line by calling the the {@code connectedCheck} |
| (or {@code cC}) task: |
| <pre> |
| ./gradlew cC</pre> |
| </li> |
| </ol> |
