Espresso review: Android UI testing tutorial and pitfalls

Espresso tests live in the module’s androidTest source set and build into a separate test APK. AndroidJUnitRunner, declared as the testInstrumentationRunner in Gradle, installs both APKs and runs the tests through Android instrumentation, in the same process as the app. That is the source of Espresso’s speed and of its limits. Tests can see the app’s classes, swap dependencies and check internal state, but they can only touch the app’s own windows. Permission dialogs, notifications, the launcher and other apps are outside its reach, which is what UI Automator, a separate AndroidX library that drives the device from outside the app, is for.

Every call to onView waits before acting or asserting until three conditions hold: the main thread’s message queue has nothing Espresso needs to process, no AsyncTask is running, and every registered idling resource reports idle. Layout passes, drawing and click handling all go through that queue, so a test that clicks a button and then checks the next screen needs no sleep. The same rule explains the most common timeout: an infinite animation or a constantly reposting handler keeps the queue busy, and Espresso waits for idleness that never comes until it fails.

Anything that runs off the main thread is invisible to Espresso by default, including coroutines on background dispatchers, executors, RxJava schedulers and network clients. An idling resource tells Espresso when such work is in flight. CountingIdlingResource is a counter, idle at zero; UriIdlingResource adds a quiet period between consecutive requests; IdlingThreadPoolExecutor wraps a thread pool. Resources are registered through IdlingRegistry, ideally in a @Before method and unregistered in @After. Google’s guidance is to wrap the app’s own async code rather than build the logic in the test, and to avoid Thread.sleep, retry loops and latches.

A test reads as onView(matcher).perform(action).check(assertion). Matchers are Hamcrest matchers such as withId, withText and isDisplayed, combined with allOf to narrow a match. A matcher must identify exactly one view in the hierarchy: zero matches fail with NoMatchingViewException and several with AmbiguousViewMatcherException, which is strict but makes tests precise. Lists need their own entry points, onData for AdapterView-based lists and RecyclerViewActions from espresso-contrib for RecyclerView, because off-screen rows do not exist as views until they are scrolled into place.

Keep UI tests in the androidTest source set of the module that owns the screen, and give every view a test reaches a stable resource id rather than matching on text that translators will change. A common way to keep tests readable is a robot per screen: a small class that wraps the onView calls for that screen and exposes intent-level methods, so the test says what the user does and the robot knows how. Because tests run in the app process, swap slow or flaky dependencies such as the network layer for fakes through your dependency injection setup, and keep a separate, smaller set of tests against a real backend.

The pattern Google recommends is to keep the idling logic in the app and only register it in tests. Add espresso-idling-resource as an implementation dependency, increment a CountingIdlingResource when background work starts and decrement it when it finishes, then register it with IdlingRegistry in @Before and unregister it in @After. Call decrement in a finally block, or a failed request leaves the counter above zero and every later test waits until it times out. Many teams with coroutines prefer to inject a test dispatcher instead, which runs the work in a way the test controls; either is better than sleeping.

A flow that picks a contact, takes a photo or opens a payment app leaves your process, and Espresso cannot follow. Stub it instead. Add espresso-intents and declare an IntentsRule, the current rule for initialising and releasing Espresso-Intents; the older IntentsTestRule is deprecated. intending matches outgoing intents and answers them with a canned ActivityResult, so the app receives a result without anything launching. intended verifies after the fact that the app sent the intent you expected. Together they test your side of the contract hermetically, and a separate UI Automator test can cover the real cross-app journey if it matters.

Gradle Managed Devices make CI emulators part of the build: declare a device profile, API level and system image source under testOptions, and Gradle provisions the emulator, runs the tests and tears it down with a task named after the device and build variant. On GitHub-hosted Linux runners enable KVM for acceleration, and pass -Pandroid.testoptions.manageddevices.emulator.gpu=swiftshader_indirect because those runners have no hardware rendering. Upload the reports folder when a run fails. Automated Test Device images, aosp-atd or google-atd, start faster, but Google documents them for API level 30 only and without hardware-rendered screenshots.

As a suite grows, three controls keep it fast and trustworthy. Android Test Orchestrator, enabled with execution set to ANDROIDX_TEST_ORCHESTRATOR in testOptions, the orchestrator artifact as androidTestUtil and the clearPackageData runner argument, gives every test a fresh process and fresh app data. Sharding splits the suite: AndroidJUnitRunner accepts numShards and shardIndex arguments for spreading tests across devices, and Gradle Managed Devices can provision several emulators per profile through the numManagedDeviceShards property. Size annotations, @SmallTest, @MediumTest and @LargeTest, let CI run a quick subset on every pull request with -Pandroid.testInstrumentationRunnerArguments.size=small and the full set nightly.