Loading...
Loading...
Use this skill to drive the Compose test clock by hand with MainTestClock — currentTime, autoAdvance, advanceTimeByFrame, advanceTimeBy(milliseconds, ignoreFrameDuration), and advanceTimeUntil. Explains the 16 ms frame delay used by TestMonotonicFrameClock, the per-frame ordering where withFrameNanos awaiters resume before recomposition, and how the recomposer and MainTestClock share one TestCoroutineScheduler. Covers v1 versus v2 entry-point dispatcher differences (UnconfinedTestDispatcher vs StandardTestDispatcher) and when an explicit runCurrent or advanceTimeBy(0) is required after migration. If the user mentions MainTestClock, mainClock.advanceTimeBy, mainClock.advanceTimeByFrame, mainClock.advanceTimeUntil, ComposeTimeoutException, frame delay, TestCoroutineScheduler, "test clock vs wall clock", or "v2 createComposeRule queues tasks", use this skill.
npx skill4agent add skydoves/android-testing-skills controlling-the-test-clockMainTestClockLaunchedEffectautoAdvancemainClock.advanceTimeBy(...)androidx.compose.ui.test.junit4.createComposeRuleandroidx.compose.ui.test.junit4.v2.createComposeRulemainClock.runCurrent()advanceTimeBy(0)MainTestClockTestCoroutineSchedulerTestMonotonicFrameClockComposeTimeoutExceptionadvanceTimeUntiladvanceTimeBy(5)playTime0autoAdvance = false../testing-animations-deterministically/SKILL.mdIdlingResource../synchronizing-with-idle/SKILL.mdsetContent../../patterns/structuring-a-compose-test/SKILL.mdcreateComposeRulerunComposeUiTest../../setup/choosing-test-rule-vs-runtest/SKILL.mdandroidx.compose.ui:ui-testandroidx.compose.ui:ui-test-junit4runComposeUiTestComposeContentTestRulecreateComposeRule()ComposeUiTestrunComposeUiTest { … }androidx.compose.ui.test.junit4.v2.createComposeRuleandroidx.compose.ui.test.v2.runComposeUiTest@Deprecated(level = WARNING)MainTestClockMonotonicFrameClockkotlinx.coroutines.test.TestCoroutineSchedulerTestMonotonicFrameClockwithFrameNanosdelay(frameDelayMillis)TestMonotonicFrameClock.jvmAndAndroid.kt:105-117delayonPerformTraversalsMainTestClock.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 writesautoAdvance = falsemainClock.advance*MainTestClock.kt:43-48compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/MainTestClock.kt| Member | Behavior |
|---|---|
| Test clock time in milliseconds. NOT wall clock. Reads |
| The scheduler the recomposer and clock share. Useful for |
| Default |
| Advances by exactly one frame (16 ms on Android/Desktop). Implemented as |
| Rounds up to the nearest multiple of frame duration unless |
| Advances frame-by-frame until |
runCurrent()AbstractMainTestClockAbstractMainTestClock.kt:96-98DefaultFrameDelay = 16_000_000LTestMonotonicFrameClock.jvmAndAndroid.kt:33performFramewithFrameNanosonPerformTraversalsMainTestClock.kt:49-60If 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.
advanceTimeByFrame()setContent0currentTime// 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.| Goal | Call |
|---|---|
| "Run exactly one frame." | |
| "Run N frames." | |
| "Run a known animation duration." | |
| "Step time without producing a new frame." | |
| "Wait until a Compose state condition becomes true." | |
createComposeRuleStandardTestDispatcherautoAdvance = falsewaitForIdlemainClock.runCurrent()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.advanceTimeUntilscheduler.runCurrent()isStandardTestDispatcherSupportEnabledAbstractMainTestClock.kt:59-61ComposeTimeoutExceptionadvanceTimeUntilComposeTimeoutException("Condition still not satisfied after $timeoutMillis ms")timeoutMilliscondition()trueAbstractMainTestClock.kt:65-68LaunchedEffect// WRONG
rule.mainClock.advanceTimeBy(milliseconds = 5)
// expectation: "1 frame ran"
// WRONG because: the framework rounds 5 ms UP to the next 16 ms multiple — i.e. 16 ms.
// One frame did run, but the developer is reading the API as if it could advance by 5 ms.
// Use ignoreFrameDuration = true if sub-frame stepping is genuinely required.// RIGHT
rule.mainClock.advanceTimeByFrame() // exactly 16 ms, exactly one frame
// or
rule.mainClock.advanceTimeBy(milliseconds = 5, ignoreFrameDuration = true) // 5 ms, 0 frames// WRONG
rule.mainClock.autoAdvance = false
rule.setContent { Crossfade(showFirst) { /* … */ } }
rule.mainClock.advanceTimeBy(300) // expect animation finished
rule.onNodeWithText("Second").assertExists()
// WRONG because: the toggle frame only schedules the animation; the animation's playTime is 0
// going into the next frame. The first 16 ms of the 300 are eaten by setup.// RIGHT — see CrossfadeTest.kt:70-93
rule.mainClock.autoAdvance = false
rule.setContent { Crossfade(showFirst) { /* … */ } }
rule.mainClock.advanceTimeByFrame() // kick off
rule.mainClock.advanceTimeBy(durationMillis = 300) // step
rule.onNodeWithText("Second").assertExists()// WRONG (v2)
val rule = androidx.compose.ui.test.junit4.v2.createComposeRule()
@Test fun foo() {
var counter by mutableStateOf(0)
rule.setContent { Text(counter.toString()) }
rule.runOnUiThread { counter = 1 }
rule.onNodeWithText("1").assertExists()
// WRONG because: with StandardTestDispatcher, the snapshot apply is queued.
// No frame has been produced. The composition still reads `0`.
}// RIGHT (v2)
@Test fun foo() {
var counter by mutableStateOf(0)
rule.setContent { Text(counter.toString()) }
rule.runOnUiThread { counter = 1 }
rule.mainClock.advanceTimeByFrame()
rule.onNodeWithText("1").assertExists()
}advanceTimeUntil// LESS PREFERRED — wall clock
rule.waitUntil(timeoutMillis = 5_000) { state.value == Phase.Done }// PREFERRED — test clock; framework iterates frame-by-frame and the timeout is in
// test clock time (no real wall-clock burn between iterations).
rule.mainClock.advanceTimeUntil(timeoutMillis = 5_000) { state.value == Phase.Done }autoAdvance == truewaitUntilmainClock.advanceTimeByFrame()Thread.sleep(10)ComposeUiTest.android.kt:899-902advanceTimeUntilAbstractMainTestClock.kt:54-72Thread.sleepMainTestClock.currentTimeSystem.currentTimeMillis()advanceTimeByFrame()advanceTimeBy(16)advanceTimeBy(milliseconds = N)frameDelayMillisignoreFrameDuration = trueAbstractMainTestClock.kt:44-52advanceTimeByFrame()advanceTimeBy(0)runCurrent()StandardTestDispatcherUnconfinedTestDispatcheradvanceTimeUntilJob.isCompletedOkHttpwaitUntilIdlingResource../synchronizing-with-idle/SKILL.mdMainTestClockMonotonicFrameClockMainTestClockTestMonotonicFrameClockkotlinx.coroutines.test.runTestcreateComposeRulerunComposeUiTestWARNINGadvanceTimeUntilwaitUntiladvanceTimeByFrame()advanceTimeBy(...)advanceTimeBy(milliseconds = X)X < 16ignoreFrameDuration = truemainClock.advanceTimeByFrame()advanceTimeBy(0)runCurrent()runOnIdle { … }advanceTimeUntilJob.isCompletedComposeTimeoutExceptioncompose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/MainTestClock.ktComposeTimeoutExceptioncompose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/AbstractMainTestClock.ktrunCurrentadvanceSchedulercompose/ui/ui-test/src/jvmAndAndroidMain/kotlin/androidx/compose/ui/test/TestMonotonicFrameClock.jvmAndAndroid.ktDefaultFrameDelay = 16_000_000Ldelaycompose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/MainTestClockImpl.android.ktcompose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeUiTest.android.ktwaitUntil../testing-animations-deterministically/SKILL.mdautoAdvance = false../synchronizing-with-idle/SKILL.mdwaitForIdlewaitUntiladvanceTimeUntil