Testing Animations Deterministically

Testing Animations Deterministically — autoAdvance = false Or Bust

A Compose animation test that does not pause the clock is by definition flaky. With mainClock.autoAdvance = true (the default), the framework's InfiniteAnimationPolicy throws CancellationException as soon as an indeterminate animation starts, and finite animations finish in a single auto-advanced burst with no observable intermediate state. This skill teaches the five-line recipe that fixes that, plus the runOnUiThread-vs-runOnIdle gotcha that bites every developer who tries it for the first time.

When to use this skill

• The test asserts an intermediate frame of an animation (mid-fade alpha, mid-scroll offset, mid-Crossfade dispose).
• The composable contains an indeterminate animation (LinearProgressIndicator() with no progress argument, rememberInfiniteTransition, looping withFrameMillis).
• The developer reports CancellationException("Infinite animations are disabled on tests") and asks how to make it stop.
• The developer reaches for Thread.sleep(500) to "wait for the animation".
• The developer's animation test passes locally and fails on CI, or vice versa.
• The developer mentions autoAdvance, advanceTimeByFrame, advanceTimeBy, Crossfade, "flaky animation test", or InfiniteAnimationPolicy.

When NOT to use this skill

• The animation is a side effect; the test only cares about the final state. Default autoAdvance = true is faster — see ../synchronizing-with-idle/SKILL.md.
• The clock semantics themselves are unclear (frame model, rounding rules, v1 vs v2 dispatcher). Read ../controlling-the-test-clock/SKILL.md first.
• The condition under test is not Compose state (a Job.isCompleted, a Mockito.verify). Use waitUntil or an IdlingResource from ../synchronizing-with-idle/SKILL.md.
• The test uses screenshot comparison waiting on the RenderThread for ripple/elevation pixels. That is the one legitimate Thread.sleep site (skydoves hot take #7).

Prerequisites

• androidx.compose.ui:ui-test and androidx.compose.ui:ui-test-junit4 (or the JUnit-less runComposeUiTest).
• A ComposeContentTestRule from createComposeRule() (PREFERRED v2: androidx.compose.ui.test.junit4.v2.createComposeRule).
• Knowledge of the frame model from ../controlling-the-test-clock/SKILL.md. In particular: the toggle frame schedules an animation; the next frame initializes playTime = 0.

Why the default fails

When the test rule constructs its environment, it installs an InfiniteAnimationPolicy on the recomposer. Quoted from compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeUiTest.android.kt:567-575:

infiniteAnimationPolicy =
    object : InfiniteAnimationPolicy {
        override suspend fun <R> onInfiniteOperation(block: suspend () -> R): R {
            if (mainClockImpl.autoAdvance) {
                throw CancellationException("Infinite animations are disabled on tests")
            }
            return block()
        }
    }

Any call to withInfiniteAnimationFrameNanos (used by rememberInfiniteTransition, indeterminate progress, and a handful of looping APIs) routes through this policy. While autoAdvance == true, the policy throws — the framework would otherwise loop forever waiting for an animation that has no end.

The fix is to disable autoAdvance before setContent so the policy permits the animation, and then drive frames by hand. Skydoves hot take #3: animation tests require mainClock.autoAdvance = false. There is no other supported path.

The recipe (five lines)

@Test fun anyAnimation() {
    rule.mainClock.autoAdvance = false                     // 1. pause the clock FIRST
    rule.setContent { /* the composable */ }               // 2. set content
    rule.mainClock.advanceTimeByFrame()                    // 3. kick-off frame
    rule.mainClock.advanceTimeBy(durationMillis = 300)     // 4. step the animation
    rule.onNodeWithTag("…").assertIsDisplayed()            // 5. assert
}

The order matters. Setting autoAdvance = false after setContent is wrong: the very first composition can already kick off an indeterminate animation, and the framework will have begun auto-advancing before the test took control.

Why the kick-off frame

From MainTestClock.kt:53-60:

Because animations receive their frame time before recomposition, an animation will not get its start time in the first frame after kicking it off by toggling a state variable. … The animation gets its first frame time and initialize the play time to t=0 [in the next frame].

In other words: the toggle frame schedules. The next frame is playTime = 0. Without the kick-off advanceTimeByFrame(), the first 16 ms of the animation duration is consumed by setup and the test reads a state behind expectation. This is the root cause of "my animation is off by one frame".

Workflow

1. Pause the clock before setContent

val rule = androidx.compose.ui.test.junit4.v2.createComposeRule()

@Test fun crossfade_disposes_old_content() {
    rule.mainClock.autoAdvance = false                     // <-- before setContent
    var showFirst by mutableStateOf(true)
    var disposed = false
    rule.setContent {
        Crossfade(showFirst) {
            BasicText(if (it) "First" else "Second")
            DisposableEffect(Unit) { onDispose { disposed = true } }
        }
    }
    rule.mainClock.advanceTimeByFrame()                    // kick off
    rule.mainClock.advanceTimeBy(durationMillis = 300)
    rule.runOnUiThread { showFirst = false }
    rule.mainClock.advanceTimeUntil { disposed }           // test-clock wait
    rule.onNodeWithText("First").assertDoesNotExist()
    rule.onNodeWithText("Second").assertExists()
}

This is compose/animation/animation/src/androidDeviceTest/kotlin/androidx/compose/animation/CrossfadeTest.kt:70-93, the canonical Crossfade test.

2. Per-frame fraction assertions: the onAnimationFrame helper

For tests that need to assert at every frame of a fixed-duration animation, lift this helper from compose/foundation/foundation/integration-tests/lazy-tests/src/androidTest/kotlin/androidx/compose/foundation/lazy/list/LazyListItemPlacementAnimationTest.kt:1724-1738:

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)
        }
    }
}

Notes on this helper:

• FrameDuration is a const val 16L companion. Always pass durations that are multiples of 16 ms — it require(duration.mod(FrameDuration) == 0L) to keep the math honest.
• The leading waitForIdle() is allowed because autoAdvance = false blocks frame advancement; waitForIdle will wait only for measure/layout passes already triggered by setContent.

3. Indeterminate progress indicators

// compose/material3/material3/src/androidDeviceTest/.../ProgressIndicatorTest.kt:132-156
@Test fun indeterminateLinearProgressIndicator_Progress() {
    val tag = "linear"
    rule.mainClock.autoAdvance = false                     // 1
    rule.setMaterialContent(lightColorScheme()) {
        LinearProgressIndicator(modifier = Modifier.testTag(tag))
    }
    rule.mainClock.advanceTimeByFrame()                    // kick off the infinite animation
    rule.onNodeWithTag(tag).assertRangeInfoEquals(ProgressBarRangeInfo.Indeterminate)
}

Without autoAdvance = false this test fails immediately with CancellationException("Infinite animations are disabled on tests") — the indicator's looping rememberInfiniteTransition hits the policy on the first composition.

4. Mutating state during the paused-clock window

runOnIdle { … } calls waitForIdle() first. With autoAdvance = false, waitForIdle() ignores frame-clock awaiters and pending recomposition (MainTestClock.kt:107-115) — so it does NOT deadlock on a paused animation, but it still waits for measure / layout / draw and any registered IdlingResource. The net effect mid-animation is a redundant idle check that adds noise: any pending IdlingResource (the Espresso link, a custom resource) can stall the test mid-frame. Use runOnUiThread for state mutations during the paused-clock window — it skips the idle check entirely:

// CrossfadeTest.kt:86 — the canonical pattern
rule.runOnUiThread { showFirst = false }

runOnUiThread posts the lambda to the UI thread via Instrumentation.runOnMainSync (AndroidSynchronization.android.kt), without any idle observation. This is exactly what is needed mid-animation.