How to run Espresso tests locally

Local Espresso runs give an Android developer the quickest feedback on whether an instrumented UI test still passes on the emulator or device in front of them. A connected test run installs the app APK and test APK, executes the test package through AndroidJUnitRunner, and returns a Gradle result before the same suite moves into CI.

The Gradle connected Android test task uses every ready emulator or device that adb reports. A module-specific task such as :app:connectedDebugAndroidTest keeps the local loop on the app module and debug variant while still writing the connected HTML report and result files under that module's build directory.

Start from an app module that already declares Espresso dependencies, an AndroidJUnitRunner, and at least one test under androidTest. If adb shows no ready device, Gradle fails before any test result can prove the app behavior.

Related: How to configure an Android project for Espresso
Related: How to run Espresso tests in Android Studio
Related: How to run Espresso tests on Gradle managed devices

Steps to run Espresso tests locally:

  1. Confirm that adb sees a ready emulator or device. 
    $ adb devices
List of devices attached
emulator-5554    device

    Rows ending in device are ready for a connected test run. Fix unauthorized, offline, or an empty list before starting Gradle.

  2. Run the connected Espresso task for the app module and variant. 
    $ ./gradlew :app:connectedDebugAndroidTest
Task :app:connectedDebugAndroidTest
Starting 3 tests on Pixel_8_API_35
LoginTest > validLogin PASSED
SettingsTest > opensNotifications PASSED
CheckoutTest > showsReceipt PASSED
Finished 3 tests on Pixel_8_API_35

BUILD SUCCESSFUL in 42s

    Use the task printed by the project for its module and build variant, such as :mobile:connectedFreeDebugAndroidTest. The generic ./gradlew connectedAndroidTest task can run connected tests across all modules when that broader local pass is wanted.

  3. Treat a failed connected task as a test result, not only a build problem. 
    $ ./gradlew :app:connectedDebugAndroidTest
Task :app:connectedDebugAndroidTest

CheckoutTest > showsReceipt[emulator-5554] FAILED
    androidx.test.espresso.NoMatchingViewException: No views in hierarchy found matching: with text: "Receipt"

FAILURE: Build failed with an exception.
##### snipped #####

    Keep the failing class, method, device, and first failure message together before rerunning a narrower scope.
    Related: How to retry failed Espresso tests
    Related: How to view device logs for Espresso tests

  4. Confirm that Gradle wrote the connected HTML report. 
    $ ls app/build/reports/androidTests/connected/debug/index.html
app/build/reports/androidTests/connected/debug/index.html

    Replace app and debug with the module and variant used by the connected task. Open this file in a browser when the console summary is not enough.

  5. Confirm that the connected result directory contains machine-readable test output. 
    $ ls app/build/outputs/androidTest-results/connected/debug
Pixel_8_API_35 - 35
TEST-Pixel8.xml
test-result.pb

    The human report lives under build/reports/androidTests/connected/. JUnit-style XML for local tooling or CI import lives under build/outputs/androidTest-results/connected/.
    Related: How to generate a JUnit report from Espresso tests