Testing Lazy Lists

Testing Lazy Lists — Tag the Container, Scroll by Semantics, Probe layoutInfo

LazyColumn / LazyRow / LazyVerticalGrid only compose items that are or were near the viewport. That breaks the naive "find by text and assert" flow because off-screen items may not exist, may exist as detached semantic nodes, or may exist with wrong bounds. This skill encodes the patterns androidx itself uses — tag the container, scroll via the semantic action or via testTag + a swipe gesture, verify with assertIsDisplayed, and read LazyListState.layoutInfo for ground truth.

When to use this skill

• The developer is writing a test for any Lazy* composable (LazyColumn, LazyRow, LazyVerticalGrid, LazyHorizontalGrid, LazyVerticalStaggeredGrid).
• A test asserts an item is "present" but the developer cannot tell whether it is on-screen.
• The developer wants to programmatically scroll to index 7, key "key_10", or by an offset.
• A test asserts on a per-item index/offset and needs the canonical state.layoutInfo shape.
• The developer is testing Modifier.animateItem() or any item placement animation.
• A reviewer asks why assertExists is wrong for a lazy item.

When NOT to use this skill

• The list under test is a non-lazy Column/Row/FlowRow. Use ../structuring-a-compose-test/SKILL.md plus ../../assertions/asserting-node-state-and-text/SKILL.md.
• The class skeleton itself is wrong; fix ../structuring-a-compose-test/SKILL.md first.
• The scroll action is a custom Modifier.scrollable (not LazyListState-backed); use ../../actions/injecting-touch-gestures/SKILL.md.
• The test is for animation timing; layer ../../synchronization/testing-animations-deterministically/SKILL.md.

Prerequisites

• Class skeleton from ../structuring-a-compose-test/SKILL.md (@MediumTest + @RunWith(AndroidJUnit4::class) + createComposeRule(StandardTestDispatcher())).
• A const tag for the container in production source (skydoves directive #1):

const val LazyListTag = "LazyListTag"

• Each item carries Modifier.testTag(it) where it is the stable item key (matches compose/foundation/foundation/integration-tests/lazy-tests/src/androidTest/kotlin/androidx/compose/foundation/lazy/list/LazyListTest.kt:285-296).

Workflow

• 1. Tag the container, tag each item by key. Tags belong in production source.

// production
LazyColumn(modifier = Modifier.testTag(LazyListTag), state = state) {
    items(snacks, key = { it.id }) { snack ->
        Row(Modifier.testTag(snack.id.toString())) { /* … */ }
    }
}

• 2. Scroll to an index via the semantic action. PREFERRED for tests that do not care which Lazy* composable is under test.

rule.onNode(hasScrollAction()).performScrollToIndex(7)

• 3. Scroll via the container tag. Use this when the test must disambiguate among multiple scrollable nodes.

rule.onNodeWithTag(LazyListTag).performScrollToIndex(7)

• 4. Scroll to a key. This is the most stable scrolling primitive — items can be added or reordered without breaking the test.

rule.onNode(hasScrollToKeyAction()).performScrollToKey("key_10")

Cited from compose/ui/ui-test/src/androidDeviceTest/kotlin/androidx/compose/ui/test/actions/ScrollToKeyTest.kt:70-80.

• 5. Scroll by raw gesture when the container has no scroll semantics. Fall back to a touch swipe.

rule.onRoot().performTouchInput { swipeUp() }
// or, scoped to the list container:
rule.onNodeWithTag(LazyListTag).performTouchInput { swipeUp() }

• 6. Verify visibility with assertIsDisplayed, not assertExists. Lazy items can be composed but off-screen, or removed from composition entirely depending on beyondBoundsItemCount. assertExists only proves the node is in the semantics tree.

• 7. Count visible children with .onChildren().assertCountEquals(N). This counts what the merged tree currently surfaces, NOT every backed item.

rule.onNodeWithTag(LazyListTag).onChildren().assertCountEquals(3)

• 8. For ground truth, read state.layoutInfo inside runOnIdle. This is the highest-signal probe.

rule.runOnIdle {
    val keys = state.layoutInfo.visibleItemsInfo.map { it.key }
    assertThat(keys).isEqualTo(listOf(0))
}

Cited from compose/foundation/foundation/integration-tests/lazy-tests/src/androidTest/kotlin/androidx/compose/foundation/lazy/list/LazyListRequestScrollTest.kt:155-184 (the requestScrollToItem test reads state.firstVisibleItemIndex, state.firstVisibleItemScrollOffset, and state.visibleKeys).

• 9. For animated item placement, set mainClock.autoAdvance = false and step frames manually. See skydoves directive #3.

@Before
fun before() {
    rule.mainClock.autoAdvance = false
}

@Test
fun reorderTwoItems() {
    var list by mutableStateOf(listOf(0, 1))
    rule.setContent { LazyList { items(list, key = { it }) { Item(it) } } }

    assertPositions(0 to 0f, 1 to itemSize)
    rule.runOnUiThread { list = listOf(1, 0) }

    onAnimationFrame { fraction ->
        assertPositions(
            0 to 0 + itemSize * fraction,
            1 to itemSize - itemSize * fraction,
            fraction = fraction,
        )
    }
}

private fun onAnimationFrame(duration: Long = Duration, onFrame: (fraction: Float) -> Unit) {
    require(duration.mod(FrameDuration) == 0L)
    rule.waitForIdle()
    rule.mainClock.advanceTimeByFrame()
    var expectedTime = rule.mainClock.currentTime
    for (i in 0..duration step FrameDuration) {
        val fraction = i / duration.toFloat()
        onFrame(fraction)
        if (i < duration) {
            rule.mainClock.advanceTimeBy(FrameDuration)
            expectedTime += FrameDuration
            assertThat(expectedTime).isEqualTo(rule.mainClock.currentTime)
        }
    }
}

Cited from compose/foundation/foundation/integration-tests/lazy-tests/src/androidTest/kotlin/androidx/compose/foundation/lazy/list/LazyListItemPlacementAnimationTest.kt:120-148, 1724-1738. Detail in ../../synchronization/testing-animations-deterministically/SKILL.md.

• 10. Parameterize vertical vs horizontal with a base class. Mirror BaseLazyListTestWithOrientation to share scrolling helpers between LazyColumn and LazyRow tests.

@RunWith(Parameterized::class)
class MyLazyTest(orientation: Orientation) : BaseLazyListTestWithOrientation(orientation) {
    companion object {
        @JvmStatic
        @Parameterized.Parameters(name = "{0}")
        fun params() = arrayOf(Orientation.Vertical, Orientation.Horizontal)
    }
}

Cited from compose/foundation/foundation/integration-tests/lazy-tests/src/androidTest/kotlin/androidx/compose/foundation/lazy/list/BaseLazyListTestWithOrientation.kt:55-114.