Controlling The Test Clock

Controlling the Test Clock — Frames, Time, and the Recomposer

MainTestClock is the only knob that drives recomposition, animations, and LaunchedEffects in a Compose test. This skill explains its surface, the 16 ms frame model behind it, and how autoAdvance flips the test from "framework drives the clock" to "the test drives the clock". The animation recipe and the idle/wait recipe live in sibling skills — this one establishes the mechanics they both depend on.

When to use this skill

• The developer asks what mainClock.advanceTimeBy(...) actually does, why it rounds up, or why the animation seems off by one frame.
• The developer is migrating from androidx.compose.ui.test.junit4.createComposeRule (v1) to androidx.compose.ui.test.junit4.v2.createComposeRule (v2) and tests now require an explicit mainClock.runCurrent() or advanceTimeBy(0).
• The developer mentions MainTestClock, TestCoroutineScheduler, TestMonotonicFrameClock, ComposeTimeoutException, advanceTimeUntil, or "test clock vs wall clock".
• The developer is writing a test that needs a particular frame count and is unsure whether advanceTimeBy(5) produces zero, one, or many frames.
• The developer asks why the animation's playTime is still 0 after one frame.

When NOT to use this skill

• The goal is a deterministic animation test (the autoAdvance = false recipe). Use ../testing-animations-deterministically/SKILL.md.
• The goal is to wait on IdlingResources, async work, or "the UI is settled". Use ../synchronizing-with-idle/SKILL.md.
• The goal is the higher-level test structure (rule wiring, setContent, JUnit lifecycle). Use ../../patterns/structuring-a-compose-test/SKILL.md.
• The goal is choosing between createComposeRule and runComposeUiTest. Use ../../setup/choosing-test-rule-vs-runtest/SKILL.md.

Prerequisites

• androidx.compose.ui:ui-test and androidx.compose.ui:ui-test-junit4 (or the JUnit-less runComposeUiTest) on the test source set.
• A ComposeContentTestRule from createComposeRule() or a ComposeUiTest receiver from runComposeUiTest { … }.
• PREFERRED: the v2 entry points (androidx.compose.ui.test.junit4.v2.createComposeRule, androidx.compose.ui.test.v2.runComposeUiTest). The v1 forms are @Deprecated(level = WARNING) (skydoves hot take #6).

The mental model

MainTestClock is not a MonotonicFrameClock — it is an interface whose advance methods drive a kotlinx.coroutines.test.TestCoroutineScheduler. The recomposer reads frames from a TestMonotonicFrameClock whose withFrameNanos is implemented by delay(frameDelayMillis) against the same scheduler (TestMonotonicFrameClock.jvmAndAndroid.kt:105-117). Advancing the scheduler causes the delay to fire, which causes a frame to be produced, which runs onPerformTraversals and triggers measure+layout on each compose root.

MainTestClock.advanceTimeBy(ms)
        │
        ▼  AbstractMainTestClock.advanceScheduler
TestCoroutineScheduler.advanceTimeBy(ms) → runCurrent()
        │
        ▼  delay(frameDelayMillis) inside TestMonotonicFrameClock fires
performFrame()  ── awaiters (withFrameNanos) resume FIRST
        │       ── then onPerformTraversals → recomposition → measure/layout
        ▼
Recomposer applies snapshot writes

This is why autoAdvance = false is enough to freeze the entire UI: nothing else ticks the scheduler unless an explicit mainClock.advance* call is made (MainTestClock.kt:43-48 KDoc).

The MainTestClock surface

Every entry comes from compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/MainTestClock.kt.

runCurrent() is exposed on AbstractMainTestClock (AbstractMainTestClock.kt:96-98) — it executes all tasks due at the current time without advancing the clock. Reach for it after toggling state in v2 if a queued task must run before the next assertion.

The frame model

• Frame duration: DefaultFrameDelay = 16_000_000L ns = 16 ms (TestMonotonicFrameClock.jvmAndAndroid.kt:33).
• Per-frame order inside performFrame:
  1. All withFrameNanos awaiters resume with the new frame time. Animations live here.
  2. onPerformTraversals runs — composition + measure + layout.
  3. Resumptions queued by the awaiters are dispatched.

Quoted from MainTestClock.kt:49-60:

If there is both a pending recomposition and an animation awaiting a frame time, ticking this clock will first send the new frame time to the animation, and then perform recomposition. … 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.

That last sentence is the reason every animation test does an extra advanceTimeByFrame() immediately after setContent to "kick off" the animation: the toggle frame schedules the animation; the next frame initializes its play time to 0 (skydoves hot take #3).

Workflow

1. Read currentTime only as a witness, never as a synchronization mechanism

// RIGHT — assert the clock advanced as much as the test asked
val before = rule.mainClock.currentTime
rule.mainClock.advanceTimeBy(durationMillis = 320)
assertEquals(320, rule.mainClock.currentTime - before)

// WRONG
while (rule.mainClock.currentTime < target) { /* spin */ }
// WRONG because: nothing in this loop drives the scheduler. The loop runs forever.

2. Choose the right advance method

3. After mutating state under v2, run pending tasks before asserting

The v2 createComposeRule uses a StandardTestDispatcher for composition; tasks are queued, not executed immediately. If autoAdvance = false, neither waitForIdle nor a node query will drain those tasks. The fix is mainClock.runCurrent() or mainClock.advanceTimeBy(0):

rule.mainClock.autoAdvance = false
rule.runOnUiThread { uiState = newValue }
// Under v2, the snapshot write is queued. Drain it before asserting.
rule.mainClock.advanceTimeByFrame()
rule.onNodeWithTag("status").assertTextEquals("Updated")

AbstractMainTestClock.advanceTimeUntil already calls scheduler.runCurrent() first when isStandardTestDispatcherSupportEnabled is true (AbstractMainTestClock.kt:59-61).