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.