Espresso

Espresso is Android’s native UI testing framework for app-level interaction checks. It runs as an instrumentation test, executes inside the Android test environment, synchronizes with the app’s main thread, and lets you find views, perform actions, and assert UI state.

This tutorial explains Espresso as a general Android testing framework and then maps it to webmate cautiously. The repository documents webmate app testing and Appium automation; it does not document direct Espresso execution as a webmate automation capability.

Goal

By the end of this tutorial you will know how to create an Espresso test, choose matchers, perform actions, assert results, handle asynchronous work with idling resources, run the suite with Gradle, and decide when to use webmate for supporting mobile testing workflows.

Before You Start

You need an Android app project, Android Studio or a command-line Android build environment, and an emulator or device. Espresso tests live under the Android instrumentation test source set, commonly src/androidTest/java or src/androidTest/kotlin.

Espresso is strongest when the app code and test code are built together. That gives tests direct access to resources, activities, and AndroidX test APIs. It is different from Appium, which treats the app as a black-box WebDriver target.

Project Setup

A minimal Espresso test launches an activity, finds a view, performs an action, and checks the outcome.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

import androidx.test.ext.junit.rules.ActivityScenarioRule
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.espresso.Espresso.onView
import androidx.test.espresso.action.ViewActions.click
import androidx.test.espresso.action.ViewActions.typeText
import androidx.test.espresso.assertion.ViewAssertions.matches
import androidx.test.espresso.matcher.ViewMatchers.isDisplayed
import androidx.test.espresso.matcher.ViewMatchers.withId
import androidx.test.espresso.matcher.ViewMatchers.withText
import org.junit.Rule
import org.junit.Test
import org.junit.runner.RunWith

@RunWith(AndroidJUnit4::class)
class LoginTest {
    @get:Rule
    val activityRule = ActivityScenarioRule(MainActivity::class.java)

    @Test
    fun userCanOpenLogin() {
        onView(withId(R.id.login_button)).perform(click())
        onView(withText("Sign in")).check(matches(isDisplayed()))
    }
}

Keep the first test short. Prove the test environment launches the app before adding authentication, backend data, or complex navigation.

Step 1: Use Matchers to Find Views

Espresso uses matchers to locate views. Common matchers target IDs, text, hints, content descriptions, and display state.

1
2
3

onView(withId(R.id.email)).perform(typeText("tester@example.com"))
onView(withText("Continue")).perform(click())
onView(withText("Dashboard")).check(matches(isDisplayed()))

Prefer resource IDs for controls owned by the app. Use text assertions for user-visible outcomes. Avoid matching by position unless the position itself is the behavior under test.

Step 2: Perform Actions Like a User

View actions include clicking, typing, replacing text, scrolling, closing the keyboard, and pressing keys.

1
2
3
4
5

onView(withId(R.id.password))
    .perform(typeText("correct-horse-battery-staple"))

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

If an action fails, check whether the view is visible, enabled, and not covered by another view. Espresso intentionally fails when the UI state does not allow a real interaction.

Step 3: Assert Observable Results

Assertions should check stable UI outcomes.

1
2
3
4
5

onView(withId(R.id.dashboard_title))
    .check(matches(withText("Dashboard")))

onView(withId(R.id.error_message))
    .check(matches(isDisplayed()))

Do not assert every intermediate view in a journey. Assert the meaningful contract: the account is created, the dashboard is visible, the error is shown, or the form remains disabled.

Step 4: Handle Asynchronous Work

Espresso automatically waits for the main thread and AsyncTask-style work it knows about. For custom background work, register an idling resource so Espresso can wait for the app to become idle.

1
2
3
4
5
6
7

class NetworkIdlingResource : IdlingResource {
    override fun getName(): String = "network"
    override fun isIdleNow(): Boolean = networkClient.activeRequests == 0
    override fun registerIdleTransitionCallback(callback: IdlingResource.ResourceCallback?) {
        networkClient.onIdle = { callback?.onTransitionToIdle() }
    }
}

Use idling resources for real synchronization. Fixed sleeps slow the suite and still fail when the device or network is slower than expected.

Step 5: Run With Gradle

Run instrumentation tests from the command line:

1

./gradlew connectedAndroidTest

Run a specific test class or method when debugging:

1
2

./gradlew connectedAndroidTest \
  -Pandroid.testInstrumentationRunnerArguments.class=com.example.LoginTest

CI needs an emulator or connected device, the app APK, the test APK, and access to any backend services the test requires. Preserve test reports, screenshots, logs, and emulator output.

Step 6: Structure the Suite

Use small helpers for repeated screen interactions, but keep test intent visible.

1
2
3
4
5
6
7

class LoginScreen {
    fun signIn(email: String, password: String) {
        onView(withId(R.id.email)).perform(typeText(email))
        onView(withId(R.id.password)).perform(typeText(password))
        onView(withId(R.id.sign_in)).perform(click())
    }
}

Keep the app state predictable. Use test build variants, fake services, seeded data, or API setup helpers so each test starts from a known condition.

How This Maps to webmate

webmate documentation in this repository covers Android app upload, debugging, interactive testing, and Appium-based automation. It does not describe direct Espresso execution on webmate devices. Treat Espresso as an Android-native test suite that normally runs in the Android build and instrumentation environment.

webmate can still support related work. Use it to upload and inspect app builds, reproduce issues on devices, debug Android app behavior, and run Appium suites where WebDriver-based remote automation is required. If an Espresso failure reveals a device-specific issue, webmate can help reproduce and document the behavior manually.

Debugging

If a matcher cannot find a view, confirm the activity is launched, the view is in the current hierarchy, and the resource ID belongs to the build variant under test. If synchronization fails, add or fix an idling resource instead of increasing sleeps. If tests pass locally but fail in CI, compare emulator image, API level, animations, locale, network access, and backend state.

Verify the Result

A good Espresso setup runs through Gradle, launches the target activity, uses stable matchers, synchronizes with background work, and produces CI artifacts. The tests should be fast enough for regular development feedback and deterministic enough to trust.

Next Steps

Use Debugging Android App and Upload App for related webmate workflows. Use Appium when the requirement is remote WebDriver-based mobile automation through webmate.