Writing Espresso Tests

Writing Espresso Tests — The Idle-Then-Act Model for Android Views

Espresso is the canonical instrumentation-time UI test framework for Android Views (not Compose — for Compose, use the compose/ skill set; for cross-Compose-View interop see ../../../compose/interop/testing-with-espresso-interop/SKILL.md). Each onView(...).perform(...).check(...) call internally pumps the main looper to idle, finds exactly one matching view, runs the action, and pumps to idle again before checking. This skill encodes the full matcher/action/assertion catalog, the RootMatchers.DEFAULT trap, and the per-version gotchas.

When to use this skill

• The user is testing an Activity, Fragment, or Dialog whose UI is built with Android Views (XML layouts, AppCompat, Material View components).
• A test fails with NoMatchingViewException, AmbiguousViewMatcherException, or PerformException.
• A click on an AlertDialog button silently does nothing — RootMatchers.DEFAULT excludes dialogs.
• The user wants to stub Intent.startActivityForResult for camera, contacts, or share flows.
• The user wants to register an IdlingResource for a long-running task that Espresso can't see.
• The user is debugging a RecyclerView interaction.
• The user mentions BottomNavigationViewActions and is surprised it isn't on the classpath in Espresso 3.7.0 contrib.

When NOT to use this skill

• The UI is Jetpack Compose — use compose/ skills (../../../compose/finders/finding-nodes-by-tag-text-content/SKILL.md, etc.). Mixed Compose+View hosts: ../../../compose/interop/testing-with-espresso-interop/SKILL.md.
• The test crosses app boundaries (Settings, dialer, system UI) — InjectEventSecurityException from Espresso. Use ../../uiautomator/cross-app-tests-with-uiautomator/SKILL.md.
• The runner stack is not yet set up — start with ../../runner/running-instrumented-tests-with-androidjunit4/SKILL.md.
• The Activity has not been launched — pair with ../../scenarios/launching-activities-with-activityscenario/SKILL.md.

Prerequisites

• Runner stack from ../../runner/running-instrumented-tests-with-androidjunit4/SKILL.md.
• Espresso artifacts (3.7.0 GA per docs/CORPUS.md H.1):

dependencies {
    androidTestImplementation("androidx.test.espresso:espresso-core:3.7.0")
    androidTestImplementation("androidx.test.espresso:espresso-contrib:3.7.0")     // RecyclerViewActions, PickerActions
    androidTestImplementation("androidx.test.espresso:espresso-intents:3.7.0")     // Intents.intended/intending
    androidTestImplementation("androidx.test.espresso:espresso-accessibility:3.7.0")
    androidTestImplementation("androidx.test.espresso:espresso-web:3.7.0")         // WebView
    implementation("androidx.test.espresso:espresso-idling-resource:3.7.0")        // for production code that exposes IdlingResources
}

android.testOptions.animationsDisabled = true   // hermetic

• An Activity (or Fragment) launched via ActivityScenario / ActivityScenarioRule / FragmentScenario.

Workflow

• 1. Find views with onView(matcher). The matcher is a Hamcrest Matcher<View>. Identity-first matchers (most preferred): withId(R.id.button), withTagKey(int), withResourceName(String). Text/desc fallback: withText, withContentDescription, withHint. Source: androidx.test.espresso.matcher.ViewMatchers (lines 79-1000+, R3 lines 180-280):

import androidx.test.espresso.Espresso.onView
import androidx.test.espresso.matcher.ViewMatchers.*
import org.hamcrest.Matchers.allOf

onView(withId(R.id.submit_button))
onView(allOf(withText("Submit"), isEnabled()))
onView(withContentDescription("Open menu"))
onView(allOf(withId(R.id.subtitle), hasDescendant(withText("Hello"))))

• 2. Compose state-aware matchers. Common state matchers from ViewMatchers: isDisplayed, isCompletelyDisplayed, isDisplayingAtLeast(percent), isEnabled/isNotEnabled, isFocused, isChecked/isNotChecked, isSelected, withEffectiveVisibility(Visibility.VISIBLE|INVISIBLE|GONE), withAlpha(float). Hierarchy matchers: withParent, hasDescendant, withChild, isRoot, withClassName, isAssignableFrom(Class). Layout-relative: hasSibling, isDescendantOfA. Source: R3 lines 180-280.

• 3. Act with ViewActions via .perform(action). From androidx.test.espresso.action.ViewActions:

import androidx.test.espresso.action.ViewActions.*

onView(withId(R.id.email)).perform(typeText("test@example.com"), closeSoftKeyboard())
onView(withId(R.id.submit_button)).perform(click())
onView(withId(R.id.input)).perform(replaceText("new"), pressImeActionButton())
onView(withId(R.id.list)).perform(swipeUp())
onView(withId(R.id.scroller)).perform(scrollTo())   // requires single-direction ScrollView

Click family: click, longClick, doubleClick. Text: typeText, replaceText, clearText, pressKey, pressImeActionButton, closeSoftKeyboard. Gesture: swipeUp, swipeDown, swipeLeft, swipeRight, scrollTo. Source: androidx.test.espresso.action.ViewActions.

• 4. Assert with ViewAssertions via .check(...). From androidx.test.espresso.assertion.ViewAssertions:

import androidx.test.espresso.assertion.ViewAssertions.*
import androidx.test.espresso.matcher.ViewMatchers.*

onView(withId(R.id.title)).check(matches(withText("Welcome")))
onView(withId(R.id.banner)).check(matches(isDisplayed()))
onView(withId(R.id.banner)).check(doesNotExist())
onView(withId(R.id.list)).check(selectedDescendantsMatch(withId(R.id.row), isCompletelyDisplayed()))

matches(matcher) passes when the resolved view matches; doesNotExist() passes when the matcher resolved zero views (NOT when one was found and is invisible — use matches(not(isDisplayed())) for that). Source: R3 lines 290-311.

• 5. Recognize the implicit idle. Every onView(...).perform(...) and .check(...) call internally:
  1. Submits the action on the main thread via the dagger-injected mainThreadExecutor.
  2. Calls uiController.loopMainThreadUntilIdle() until: the main MessageQueue is empty, all IdlingResources registered with IdlingRegistry report isIdleNow == true, all registered non-main Loopers are idle, and the AsyncTask thread pool is idle.
  3. Resolves the view (viewMatcher against the current Root's hierarchy). 0 → NoMatchingViewException; 2+ → AmbiguousViewMatcherException.
  4. Checks viewAction.getConstraints().matches(view) → throws PerformException if false.
  5. Calls viewAction.perform(uiController, view) (or viewAssertion.check(view, null)).
  6. Loops the main thread to idle again before returning.

This is the idle-then-act model. Tests that work locally but fail on CI are usually missing an IdlingResource for a non-Looper-driven async path (custom ExecutorService, OkHttp's dispatcher, etc.). Source: R3 lines 165-178, 811-820.

• 6. For dialogs and popups, override the root with inRoot(...). RootMatchers.DEFAULT excludes dialogs, popups, and toasts (it matches "the focused activity window"). For an AlertDialog button:

import androidx.test.espresso.matcher.RootMatchers.*

onView(withText("Submit")).inRoot(isDialog()).perform(click())
onView(withText("Copy")).inRoot(isPlatformPopup()).perform(click())   // overflow menu, popup window
onView(withText("Saved")).inRoot(isPlatformPopup()).check(matches(isDisplayed()))   // toast

RootMatchers.DEFAULT is allOf(hasWindowLayoutParams(), allOf(anyOf(allOf(isDialog(), withDecorView(hasWindowFocus())), isSubwindowOfCurrentActivity()), isFocusable())) per R3 line 311 — that's why a generic dialog button click silently misses.

• 7. For RecyclerView, use RecyclerViewActions from contrib. onView(...).perform(...) against a RecyclerView's row directly does NOT work because the row may be off-screen (no view to find):

import androidx.test.espresso.contrib.RecyclerViewActions.*

onView(withId(R.id.list))
    .perform(scrollToPosition<RecyclerView.ViewHolder>(20))

onView(withId(R.id.list))
    .perform(actionOnItemAtPosition<RecyclerView.ViewHolder>(3, click()))

onView(withId(R.id.list))
    .perform(scrollTo<RecyclerView.ViewHolder>(hasDescendant(withText("Pikachu"))))

onView(withId(R.id.list))
    .perform(actionOnItem<RecyclerView.ViewHolder>(hasDescendant(withText("Pikachu")), click()))

All RecyclerViewActions require isAssignableFrom(RecyclerView.class) AND isDisplayed() constraint (R3 line 428).

• 8. For AdapterView (ListView, Spinner), use onData(...) not onView(...).

import androidx.test.espresso.Espresso.onData
import org.hamcrest.Matchers.allOf

onData(allOf(`is`(instanceOf(String::class.java)), `is`("Item 5")))
    .inAdapterView(withId(R.id.list))
    .perform(click())

onData scrolls the adapter to bring the item on-screen before resolving its view.

• 9. Stub and verify intents with Intents. Init in @Before, release in @After. The IntentsRule (3.5+) handles both:

import androidx.test.espresso.intent.rule.IntentsRule
import androidx.test.espresso.intent.Intents.*
import androidx.test.espresso.intent.matcher.IntentMatchers.*

@get:Rule val intentsRule = IntentsRule()

@Test
fun openCameraStub() {
    intending(hasAction(MediaStore.ACTION_IMAGE_CAPTURE))
        .respondWith(Instrumentation.ActivityResult(Activity.RESULT_OK, Intent()))

    onView(withId(R.id.take_photo)).perform(click())

    intended(allOf(
        hasAction(MediaStore.ACTION_IMAGE_CAPTURE),
        hasFlag(Intent.FLAG_GRANT_READ_URI_PERMISSION),
    ))
}

IntentsTestRule is @Deprecated per docs/CORPUS.md H.7 — use IntentsRule or call Intents.init() / Intents.release() manually.

• 10. Register IdlingResource for non-Looper async work. Espresso watches the main looper and the AsyncTask pool by default; for OkHttp, custom ExecutorService, or sensor pipelines you must surface idleness:

class CountingIdlingResource(private val name: String) : IdlingResource {
    private val counter = AtomicInteger(0)
    private var callback: IdlingResource.ResourceCallback? = null

    override fun getName() = name
    override fun isIdleNow() = counter.get() == 0
    override fun registerIdleTransitionCallback(cb: IdlingResource.ResourceCallback) { callback = cb }

    fun increment() { counter.incrementAndGet() }
    fun decrement() { if (counter.decrementAndGet() == 0) callback?.onTransitionToIdle() }
}

@Before fun setUp() = IdlingRegistry.getInstance().register(myIdler)
@After fun tearDown() = IdlingRegistry.getInstance().unregister(myIdler)

// Master policy default is 60 seconds; setIdlingResourceTimeout default is 26 seconds.
// For debugger sessions, opt out of timeouts entirely with
//   IdlingPolicies.setMasterPolicyTimeoutWhenDebuggerAttached(false)
// — there is no "-1 = infinite" magic value.
IdlingPolicies.setMasterPolicyTimeout(60, TimeUnit.SECONDS)
IdlingPolicies.setIdlingResourceTimeout(45, TimeUnit.SECONDS)

Wrap network calls / async work in increment() / decrement() from production code (the :espresso-idling-resource artifact is on implementation, not androidTestImplementation).

• 11. Read errors precisely.

  • NoMatchingViewException — the matcher resolved zero views in the current root. Confirm the view is currently displayed; if it is in a dialog, add .inRoot(isDialog()).
  • AmbiguousViewMatcherException — 2+ views matched. Tighten with allOf(...).
  • PerformException — the action's constraint failed (e.g. click() requires isDisplayingAtLeast(90)). The exception message includes the constraint description.
  • InjectEventSecurityException — an event would cross to a foreign window. The test reached system UI. Use UiAutomator instead.