Compose: UI testing patterns

Core principle

Procedure

1. State the behavior and test concern the task asks you to prove.
2. Inspect the existing test against that concern and choose the smallest sufficient seam from the table below.
3. Keep focused edits within the requested test concern. Do not move test-only helpers into production or broaden production APIs unless that production boundary is itself under test.
4. Drive controlled state or input, synchronize through Compose when needed, and assert an observable semantic, visual, or callback result.
5. Finish with no edit when the existing test already uses the narrowest valid seam and proves the requested behavior.

Test target choice

Prefer plain UI tests

composeTestRule.setContent {
    ProfileScreen(
        state = ProfileUiState(name = "Ada", canSave = true),
        onNameChange = {},
        onSaveClick = { saved = true },
        onBackClick = {},
    )
}

composeTestRule.onNodeWithText("Ada").assertIsDisplayed()
composeTestRule.onNodeWithText("Save").performClick()

assertThat(saved).isTrue()

Semantics first

• Text exists: onNodeWithText.
• Button is enabled/disabled: assertIsEnabled, assertIsNotEnabled.
• Content is selected/focused/toggled: use semantics assertions.
• Content is absent: assertDoesNotExist.

Callback testing

var selectedId: String? = null

composeTestRule.setContent {
    ItemList(
        items = listOf(ItemUi("movie-1", "Movie")),
        onItemClick = { selectedId = it },
    )
}

composeTestRule.onNodeWithText("Movie").performClick()

assertThat(selectedId).isEqualTo("movie-1")

Keep UI tests deterministic

Interaction state with MutableInteractionSource

val interactionSource = MutableInteractionSource()

composeTestRule.setContent {
    OutlinedButton(
        onClick = {},
        interactionSource = interactionSource,
    )
}

// Assert default (un-hovered) state
composeTestRule.onNodeWithText("OutlinedButton").assertIsDisplayed()

// Emit hover — interactionSource.emit is a suspend function,
// so call it from a test coroutine scope.
TestScope().launch {
    interactionSource.emit(HoverInteraction.Enter())
}

composeTestRule.waitForIdle()

// Assert the visual/semantic change that hover produces
// (e.g., border color, elevation, or capture for screenshot test)
composeTestRule.onNodeWithText("OutlinedButton").assertIsDisplayed()

• Always inject MutableInteractionSource rather than relying on the default internal source. This gives you full control over state transitions.
• Emit interactions from a coroutine scope (e.g. TestScope().launch { }) since emit is a suspend function. Do not use LaunchedEffect — that is a production Compose effect, not a test tool.
• Assert the result of the interaction (visual change, semantic change, enabled state), not the interaction itself. The interaction source is a test driver, not the assertion target.
• Use this for screenshot tests too — emit the interaction state, then capture the screenshot for a deterministic hover/press/focus visual.

Keyboard and focus

Screenshot tests

• Layout spacing/alignment.
• Themed colors, typography, elevation, shadows.
• Image composition, gradients, overlays.
• Focus highlight appearance.
• Loading skeletons or dense visual states.

• Use fixed state data.
• Freeze clocks or animation progress when possible.
• Replace network/image loading with fake or preview handlers.
• Avoid asserting dynamic text such as current time unless controlled.

Fake images and platform services

val requestedModels = mutableListOf<Any?>()

// Example helper, not a Compose API.
setContentWithFakeImageLoader { request ->
    requestedModels += request.data
    errorPainter()
}

Common mistakes

Red flags during review

• "This UI test is flaky because images load slowly."
• A test uses production DI for simple rendering.
• A screenshot has random dates, clocks, remote images, or live data.
• Assertions only check that a node exists after performing an action, not that the callback/state change happened.
• Focus behavior is visually inspected but not asserted.
• A test uses performMouseInput or touch injection to trigger hover/press states instead of MutableInteractionSource.emit.
• A composable accepts interactionSource but tests don't inject MutableInteractionSource.
• A plain rendering test starts the production app or uses Thread.sleep before asserting.

RED/GREEN agent scenarios

1. RED launches a production app, waits with Thread.sleep, and only asserts that a node exists. GREEN renders fixed state with setContent, drives the action, synchronizes through Compose, and asserts the semantic state or callback result.
2. Novel case: a screen's repository-backed state holder starts background work, but the test only needs to prove a disabled Save button. GREEN tests the plain UI state directly; a separate integration test covers the state-holder wiring if needed.
3. Counterexample: navigation behavior depends on a real NavController lifecycle. GREEN uses an integration test rather than pretending a plain rendering test proves that contract.
4. Focused counterexample: a value-only formatter test already uses a plain unit test and the task asks only whether it needs a UI harness. GREEN leaves the test-local helper and workspace unchanged.