Skip to content
Tutorials Center
My learning

Topics

Lesson 83 of 104 ยท Testing

Instrumented, Room and Navigation Tests

Learn when to use androidTest instead of local tests, how to test Room with an in-memory database, assert the back stack with TestNavHostController, and run tests on CI.

Local unit tests run on your computer's JVM and finish in milliseconds. They cannot, however, load SQLite, inflate a view or ask the Android framework for a Context. For code that touches the real platform you need instrumented tests: tests that are installed on an emulator or a physical device together with your app and executed there. They are slower and more fragile, so you write fewer of them, but some bugs only show up on a real Android runtime.

This lesson explains where each kind of test lives, how to test a Room database with an in-memory instance, how to check navigation with a TestNavHostController, what Espresso is, and how a team runs all this in CI. It follows Testing Compose UI and builds on Room Database Basics and Navigation Compose Basics. The real Android test code below is read-only, because the site has no emulator. The TryIt blocks are plain Kotlin stand-ins that model the same ideas, and each one says what is real and what is imitation.

test versus androidTest

An Android module has two test source sets, and the folder decides where the tests run:

Folder Runs on Typical content Speed
src/test Your computer's JVM ViewModels, mappers, use cases, reducers Milliseconds
src/androidTest Emulator or device Room, navigation, Compose UI on real framework classes, Espresso Seconds to minutes
flowchart LR
    A["Gradle task<br/>testDebugUnitTest"] --> B["JVM on your PC<br/>src/test"]
    C["Gradle task<br/>connectedDebugAndroidTest"] --> D["Emulator or device<br/>src/androidTest"]

Two source sets, two Gradle tasks, two very different execution environments.

A good rule is to push as much logic as possible into plain Kotlin that needs no framework, test it in src/test, and keep androidTest for the boundaries where your code meets the platform. Instrumented tests use the AndroidJUnit4 runner and dependencies declared with androidTestImplementation:

Kotlin
// read-only example: app/build.gradle.kts
android {
    defaultConfig {
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }
}

dependencies {
    androidTestImplementation(libs.androidx.test.ext.junit)
    androidTestImplementation(libs.androidx.test.runner)
    androidTestImplementation(libs.androidx.room.testing)
    androidTestImplementation(libs.androidx.navigation.testing)
    androidTestImplementation(libs.kotlinx.coroutines.test)
}

Testing a Room database

A DAO is mostly SQL, and SQL strings are checked by Room at compile time only for syntax and column names, not for behavior. Does ORDER BY sort the way you think? Does ON CONFLICT REPLACE overwrite the old row? Only a real SQLite engine can answer, and SQLite on Android is part of the platform, so these tests run on a device (or under Robolectric on the JVM, which is a separate, optional route).

The key trick is Room.inMemoryDatabaseBuilder. It creates a database that lives only in RAM and disappears when you close it, so each test starts from a blank slate and leaves nothing on disk:

Kotlin
// read-only example: src/androidTest, needs Room and AndroidX Test
@RunWith(AndroidJUnit4::class)
class NoteDaoTest {

    private lateinit var db: AppDatabase
    private lateinit var dao: NoteDao

    @Before
    fun createDb() {
        val context = ApplicationProvider.getApplicationContext<Context>()
        db = Room.inMemoryDatabaseBuilder(context, AppDatabase::class.java)
            .allowMainThreadQueries()   // fine in tests only
            .build()
        dao = db.noteDao()
    }

    @After
    fun closeDb() = db.close()

    @Test
    fun insertedNotesAreReturnedNewestFirst() = runTest {
        dao.insert(Note(title = "old", createdAt = 1))
        dao.insert(Note(title = "new", createdAt = 2))

        val titles = dao.observeAll().first().map { it.title }

        assertEquals(listOf("new", "old"), titles)
    }
}

Three habits make these tests reliable:

  • Fresh database per test. @Before builds it and @After closes it, so tests never depend on each other or on run order.
  • Assert on what the query returns, not on private details. For a Flow-returning query, take the first value with first() or use a flow-testing helper.
  • Test the interesting SQL: ordering, filters, conflict strategies, cascading deletes, joins. Do not test that Room can insert a row, because that is the library's job.

Migrations deserve instrumented tests too. MigrationTestHelper creates a database at an old version from the exported schema JSON, runs your Migration, and validates the result against the new schema. You met the idea in Room Relations and Migrations; a migration test is the only way to know it will not crash on a user's phone.

A stand-in DAO test

Room itself cannot run here, so this stand-in builds a small in-memory table with a DAO-style API and a tiny test harness. It copies the shape of the test above: a fresh database per test, then arrange, act, assert. It does not exercise SQLite, so it cannot catch SQL mistakes. That is exactly why the real test must run on Android.

Kotlin In-memory DAO with a fresh database per test (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The fourth test passes only because each test gets its own database, the same guarantee inMemoryDatabaseBuilder gives you in @Before. The last test fails on purpose so you can see how a failure is reported.

Testing navigation

Navigation bugs are usually wrong destinations or a wrong back stack: Back returns to login, a tab keeps a stale screen, an argument goes missing. The navigation-testing artifact provides TestNavHostController, a NavController that works without a real activity or screen transitions, so you can assert on currentBackStackEntry after driving your real NavHost:

Kotlin
// read-only example: src/androidTest, needs Navigation Compose and the Compose test rule
class AppNavigationTest {

    @get:Rule
    val composeRule = createComposeRule()

    private lateinit var navController: TestNavHostController

    @Before
    fun setUp() {
        composeRule.setContent {
            navController = TestNavHostController(LocalContext.current).apply {
                navigatorProvider.addNavigator(ComposeNavigator())
            }
            AppNavHost(navController = navController)
        }
    }

    @Test
    fun startsOnHome() {
        assertTrue(navController.currentDestination?.hasRoute<Home>() == true)
    }

    @Test
    fun tappingAnItemOpensItsDetail() {
        composeRule.onNodeWithText("Buy milk").performClick()

        val route = navController.currentBackStackEntry?.toRoute<Detail>()
        assertEquals(42L, route?.id)
    }

    @Test
    fun backFromDetailReturnsHome() {
        composeRule.onNodeWithText("Buy milk").performClick()
        composeRule.runOnUiThread { navController.popBackStack() }

        assertTrue(navController.currentDestination?.hasRoute<Home>() == true)
    }
}

Notice what these tests check: the destination and its arguments, not pixels. Your composables take a NavController only at the top (see Passing Arguments and Results), so everything below the host is easy to test with plain lambdas. For the effects of popUpTo and launchSingleTop from Back Stack, Launch Modes and Deep Links, assert on the back stack contents rather than only the top entry.

A stand-in back stack assertion

The real TestNavHostController needs the Android SDK. This stand-in is a small controller that records its back stack and offers the same style of assertions: the current route, the full stack, and the arguments of the top entry. It models the testing idea, not the library.

Kotlin Asserting on a back stack (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

The checks use the whole backStack list for the login case. That is the assertion that catches the classic "Back returns to the login screen" bug, which a check on the current route alone would miss.

Espresso at a glance

Espresso is the older instrumented UI testing library for the View system. You find views with matchers, act on them and assert on the result:

Kotlin
// read-only example: Espresso on an XML-based screen
onView(withId(R.id.email)).perform(typeText("[email protected]"), closeSoftKeyboard())
onView(withId(R.id.submit)).perform(click())
onView(withText("Welcome")).check(matches(isDisplayed()))

Espresso synchronizes with the main thread and AsyncTask-style work automatically, which makes it far less flaky than sleeping in a test. In a Compose app you use the Compose test rule instead, but Espresso remains useful for older XML screens, for AndroidView interop (see Views Interop and Legacy XML) and for system-level interactions. For a flow that spans several apps or the system UI, such as a permission dialog or a notification shade, Google's UI Automator library drives the device from outside your app.

The test pyramid

How many tests of each kind should you have? A common answer is a pyramid, with the cheapest, fastest tests at the bottom:

flowchart TB
    A["Few end-to-end UI tests<br/>slow, device needed"]
    B["Some integration tests<br/>Room, navigation, Compose"]
    C["Many local unit tests<br/>ViewModels, mappers, reducers"]
    A --- B --- C

Many fast JVM tests at the base, fewer device tests above, very few full-flow tests on top.

The base is wide because it is fast and stable, so you can run it on every save. Instrumented tests in the middle verify that the pieces fit together on real Android. The top is small: end-to-end tests are valuable for the two or three journeys that must never break, such as signing in and completing a purchase, but each one costs minutes and flakes more often.

Running on CI and device farms

Instrumented tests need a device, and CI servers have none by default. You have three common options:

  • An emulator on the CI runner. Hosted Linux runners can start an emulator with hardware acceleration. It is free but slow to boot and sometimes unstable, so cache the AVD and pin the API level.
  • Gradle managed devices. You declare virtual devices in build.gradle.kts, and Gradle creates, boots and shuts them down for you, which makes the same command work locally and in CI.
  • Cloud device farms. Services such as Firebase Test Lab run your APKs on many real and virtual devices in parallel and return reports, videos and logs. This is where you find the crash that happens only on one manufacturer's phones.
Kotlin
// read-only example: a managed device in app/build.gradle.kts
android {
    testOptions {
        managedDevices {
            localDevices {
                create("pixel6Api34") {
                    device = "Pixel 6"
                    apiLevel = 34
                    systemImageSource = "aosp"
                }
            }
        }
    }
}
// run with: ./gradlew pixel6Api34DebugAndroidTest

A practical setup is to run local unit tests on every push, run instrumented tests on an emulator for each pull request, and run the wider device farm matrix nightly or before a release. CI/CD for Android builds that pipeline step by step.

If an instrumented test is flaky, never "fix" it with Thread.sleep. Wait for a condition instead: Compose's waitUntil, Espresso's idling resources, or a test dispatcher that you control. Sleeping makes tests slow when they pass and still flaky when the device is busy.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which test needs a device or emulator because it uses real SQLite on Android?

    Room on Android sits on the platform's SQLite and needs a Context, so DAO tests normally live in androidTest. The other three are plain Kotlin and run on the JVM.
  2. 2. Why do Room tests use Room.inMemoryDatabaseBuilder together with @Before and @After?

    An in-memory database lives only in RAM. Building one per test and closing it afterward removes any dependence on test order or leftover data.
  3. 3. What does a TestNavHostController let you assert in a navigation test?

    It is a NavController made for tests, so you can drive navigation and inspect currentDestination, currentBackStackEntry and the stack, without checking visuals.
  4. 4. In the test pyramid, which kind of test should you have the most of?

    Fast local tests are cheap and stable, so they form the wide base. Instrumented and end-to-end tests are slower and flakier, so there are fewer of them.
  5. 5. What is the right way to deal with a flaky instrumented test that fails because the UI is not ready?

    Waiting for a condition ends as soon as the app is ready and still waits long enough on a slow device. A fixed sleep is both wasteful and unreliable.

Summary

  • src/test runs on your JVM in milliseconds; src/androidTest runs on an emulator or device and covers real platform behavior.
  • Push logic into plain Kotlin so most tests are local, and keep instrumented tests for the boundaries: Room, navigation, Compose UI and system interaction.
  • Test Room with Room.inMemoryDatabaseBuilder, a fresh database per test, and assertions on query results; test migrations with MigrationTestHelper.
  • TestNavHostController lets you assert on the destination, arguments and back stack without a real screen.
  • Espresso drives View-based screens; the Compose test rule drives Compose; UI Automator drives the system around your app.
  • Follow the test pyramid: many local tests, some integration tests, few end-to-end tests.
  • CI can use an emulator, Gradle managed devices or a cloud device farm; wait on conditions, never on fixed sleeps.
  • The Android test code is read-only here; the TryIts are plain-Kotlin stand-ins for the DAO test shape and for back stack assertions.

Next: Performance and Profiling