This document describes how to set up a variety of common Espresso tests.
Match a view next to another view
A layout could contain certain views that are not unique by themselves. For
example, a repeating call button in a table of contacts could have the same
R.id, contain the same text, and have the same properties as other call
buttons within the view hierarchy.
For example, in this activity, the view with text "7" repeats across multiple
rows:

Often, the non-unique view will be paired with some unique label that’s located
next to it, such as a name of the contact next to the call button. In this case,
you can use the hasSibling() matcher to narrow down your selection:
onView(allOf(withText("7"), hasSibling(withText("item: 0")))) .perform(click())
Match a view that is inside an action bar
The ActionBarTestActivity has two different action bars: a normal
action bar and a contextual action bar that is created from a options menu. Both
action bars have one item that is always visible and two items that are only
visible in overflow menu. When an item is clicked, it changes a TextView to the
content of the clicked item.
Matching visible icons on both of the action bars is straightforward, as shown in the following code snippet:
fun testClickActionBarItem() { // We make sure the contextual action bar is hidden. onView(withId(R.id.hide_contextual_action_bar)) .perform(click()) // Click on the icon - we can find it by the r.Id. onView(withId(R.id.action_save)) .perform(click()) // Verify that we have really clicked on the icon // by checking the TextView content. onView(withId(R.id.text_action_bar_result)) .check(matches(withText("Save"))) }

The code looks identical for the contextual action bar:
fun testClickActionModeItem() { // Make sure we show the contextual action bar. onView(withId(R.id.show_contextual_action_bar)) .perform(click()) // Click on the icon. onView((withId(R.id.action_lock))) .perform(click()) // Verify that we have really clicked on the icon // by checking the TextView content. onView(withId(R.id.text_action_bar_result)) .check(matches(withText("Lock"))) }

Clicking on items in the overflow menu is a bit trickier for the normal action bar as some devices have a hardware overflow menu button, which opens the overflowing items in an options menu, and some devices have a software overflow menu button, which opens a normal overflow menu. Luckily, Espresso handles that for us.
For the normal action bar:
fun testActionBarOverflow() { // Make sure we hide the contextual action bar. onView(withId(R.id.hide_contextual_action_bar)) .perform(click()) // Open the options menu OR open the overflow menu, depending on whether // the device has a hardware or software overflow menu button. openActionBarOverflowOrOptionsMenu( ApplicationProvider.getApplicationContext<Context>() ) // Click the item. onView(withText("World")) .perform(click()) // Verify that we have really clicked on the icon by checking // the TextView content. onView(withId(R.id.text_action_bar_result)) .check(matches(withText("World"))) }

This is how this looks on devices with a hardware overflow menu button:

For the contextual action bar it is really easy again:
fun testActionModeOverflow() { // Show the contextual action bar. onView(withId(R.id.show_contextual_action_bar)) .perform(click()) // Open the overflow menu from contextual action mode. openContextualActionModeOverflowMenu() // Click on the item. onView(withText("Key")) .perform(click()) // Verify that we have really clicked on the icon by // checking the TextView content. onView(withId(R.id.text_action_bar_result)) .check(matches(withText("Key"))) }

To see the full code for these samples, view the
ActionBarTest.java sample on GitHub.
Assert that a view is not displayed
After performing a series of actions, you will certainly want to assert the
state of the UI under test. Sometimes, this may be a negative case, such as when
something is not happening. Keep in mind that you can turn any hamcrest view
matcher into a ViewAssertion by using ViewAssertions.matches().
In the example below, we take the isDisplayed() matcher and reverse it using
the standard not() matcher:
// import androidx.test.espresso.Espresso.onView // import androidx.test.espresso.assertion.ViewAssertions.matches // import androidx.test.espresso.matcher.ViewMatchers.isDisplayed // import androidx.test.espresso.matcher.ViewMatchers.withId // import org.hamcrest.Matchers.not onView(withId(R.id.bottom_left)) .check(matches(not(isDisplayed())))
The above approach works if the view is still part of the hierarchy. If it is
not, you will get a NoMatchingViewException and you need to use
ViewAssertions.doesNotExist().
Assert that a view is not present
If the view is gone from the view hierarchy—which can happen when an
action caused a transition to another activity—you should use
ViewAssertions.doesNotExist():
// import androidx.test.espresso.Espresso.onView // import androidx.test.espresso.assertion.ViewAssertions.doesNotExist // import androidx.test.espresso.matcher.ViewMatchers.withId onView(withId(R.id.bottom_left)) .check(doesNotExist())
Assert that a data item is not in an adapter
To prove a particular data item is not within an AdapterView you have to do
things a little differently. We have to find the AdapterView we’re interested
in and interrogate the data its holding. We don’t need to use onData().
Instead, we use onView() to find the AdapterView and then use another
matcher to work on the data inside the view.
First the matcher:
private fun withAdaptedData(dataMatcher: Matcher<Any>): Matcher<View> { return object : TypeSafeMatcher<View>() { override fun describeTo(description: Description) { description.appendText("with class name: ") dataMatcher.describeTo(description) } public override fun matchesSafely(view: View): Boolean { if (view !is AdapterView<*>) { return false } val adapter = view.adapter for (i in 0 until adapter.count) { if (dataMatcher.matches(adapter.getItem(i))) { return true } } return false } } }
Then the all we need is onView() to find the AdapterView:
fun testDataItemNotInAdapter() { onView(withId(R.id.list)) .check(matches(not(withAdaptedData(withItemContent("item: 168"))))) }
And we have an assertion that will fail if an item that is equal to "item: 168" exists in an adapter view with the ID list.
For the full sample, look at the testDataItemNotInAdapter() method within the
AdapterViewTest.java
class on GitHub.
Use a custom failure handler
Replacing the default FailureHandler in Espresso with a custom one allows for
additional or different error handling, such as taking a screenshot or passing
along extra debug information.
The CustomFailureHandlerTest example demonstrates how to implement a custom
failure handler:
private class CustomFailureHandler(targetContext: Context) : FailureHandler { private val delegate: FailureHandler init { delegate = DefaultFailureHandler(targetContext) } override fun handle(error: Throwable, viewMatcher: Matcher<View>) { try { delegate.handle(error, viewMatcher) } catch (e: NoMatchingViewException) { throw MySpecialException(e) } } }
This failure handler throws a MySpecialException instead of a
NoMatchingViewException and delegates all other failures to the
DefaultFailureHandler. The CustomFailureHandler can be registered with
Espresso in the setUp() method of the test:
@Throws(Exception::class) override fun setUp() { super.setUp() getActivity() setFailureHandler( CustomFailureHandler( ApplicationProvider.getApplicationContext<Context>() ) ) }
For more information, see the
FailureHandler
interface and
Espresso.setFailureHandler().
Target non-default windows
Android supports multiple windows. Normally, this is transparent to the users
and the app developer, yet in certain cases multiple windows are visible, such
as when an auto-complete window gets drawn over the main application window in
the search widget. To simplify things, by default Espresso uses a heuristic to
guess which Window you intend to interact with. This heuristic is almost
always good enough; however, in rare cases, you’ll need to specify which window
an interaction should target. You can do this by providing your own root window
matcher, or Root matcher:
onView(withText("South China Sea")) .inRoot(withDecorView(not(`is`(getActivity().getWindow().getDecorView())))) .perform(click())
Similar to androidx.test.espresso.matcher.ViewMatchers, Espresso provides
built-in root matchers in androidx.test.espresso.matcher.RootMatchers, such as
withDecorView(), isDialog(), and isPlatformPopup(). For a quick visual
summary of built-in matchers, see the
Espresso cheat sheet, or implement your own
Matcher<Root> object.
Take a look at the MultipleWindowTest sample on GitHub.
Match a header or footer in a list view
Headers and footers are added to ListViews using the addHeaderView() and
addFooterView() methods. To ensure Espresso.onData() knows what data object
to match, make sure to pass a preset data object value as the second parameter
to addHeaderView() and addFooterView(). For example:
const val FOOTER = "FOOTER" // ... val footerView = layoutInflater.inflate(R.layout.list_item, listView, false) footerView.findViewById<TextView>(R.id.item_content).text = "count:" footerView.findViewById<TextView>(R.id.item_size).text = data.size.toString() listView.addFooterView(footerView, FOOTER, true)
Then, you can write a matcher for the footer:
// import org.hamcrest.Matchers.allOf // import org.hamcrest.Matchers.instanceOf // import org.hamcrest.Matchers.`is` fun isFooter(): Matcher<Any> { return allOf( `is`(instanceOf(String::class.java)), `is`(LongListActivity.FOOTER) ) }
And loading the view in a test is trivial:
// import androidx.test.espresso.Espresso.onData // import androidx.test.espresso.action.ViewActions.click // import androidx.test.espresso.sample.LongListMatchers.isFooter fun testClickFooter() { onData(isFooter()) .perform(click()) // ... }
Take a look at the full code sample, found in the testClickFooter() method of
AdapterViewTest.java
on GitHub.