synchronizing-with-idle

name	synchronizing-with-idle
description	Use this skill to choose the right idle-synchronization primitive in Compose UI tests — waitForIdle, awaitIdle, waitUntil(conditionDescription, timeoutMillis, condition), waitUntilNodeCount, waitUntilExactlyOneExists, waitUntilAtLeastOneExists, waitUntilDoesNotExist, runOnIdle, runOnUiThread, runWhenIdle, awaitAndRunWhenIdle, hasPendingWork, and IdlingResource. Explains what "idle" means (no pending recomposition or draw, every IdlingResource isIdleNow), the wall-clock vs test-clock timeout split, the Espresso/Robolectric strategy bridge, and why direct state reads from the test thread race the recomposer. If the user mentions "test is flaky", "test passes locally fails on CI", "Thread.sleep waiting for state", "Espresso IdlingResource", "ComposeTimeoutException waitUntil", "AndroidComposeUiTestTimeoutException", waitUntilExactlyOneExists, runOnIdle, runWhenIdle, or "register IdlingResource", use this skill.
license	Apache-2.0. See LICENSE for complete terms.
metadata	{"author":"Jaewoong Eum (skydoves)","keywords":["jetpack-compose","ui-testing","wait-for-idle","wait-until","idling-resource","run-on-idle","run-on-ui-thread","flaky-test","espresso-bridge"]}

Synchronizing With Idle — Pick the Right Wait

A Compose test that waits on the wrong primitive is the #1 source of flakiness. This skill enumerates every idle/wait API on ComposeTestRule and ComposeUiTest, locks down what "idle" actually means, and gives a decision matrix for choosing among them. Animation-specific waits live in ../testing-animations-deterministically/SKILL.md; the underlying clock semantics live in ../controlling-the-test-clock/SKILL.md.

When to use this skill

• The test occasionally fails with "node not found" or "node count mismatch" but the production code is correct.
• The developer reaches for Thread.sleep(2000) to wait for a screen, a snackbar, a navigation transition, or an IO-backed state.
• A ViewModel posts state from a coroutine and the test needs to wait until the UI reflects it.
• The developer asks about IdlingResource, the Espresso bridge, runOnIdle vs runOnUiThread, or whether runWhenIdle is faster.
• The developer mentions waitUntil, waitUntilExactlyOneExists, waitUntilNodeCount, AndroidComposeUiTestTimeoutException, or IdlingPolicies.setMasterPolicyTimeout.
• The developer reads or mutates state from the test thread (e.g. state.firstVisibleItemIndex) and asks why it sometimes returns stale data.

When NOT to use this skill

• The condition is a paused-clock animation. Use ../testing-animations-deterministically/SKILL.md and mainClock.advanceTimeUntil.
• The mechanics of MainTestClock itself (frames, rounding, dispatchers) are unclear. Read ../controlling-the-test-clock/SKILL.md first.
• The test is failing because of test-tag/finder issues, not async timing. Use ../../debug/printing-the-semantics-tree/SKILL.md and ../../finders/finding-nodes-by-tag-text-content/SKILL.md.
• Espresso interop is the actual question. Use ../../interop/testing-with-espresso-interop/SKILL.md (sibling skill, separate scope).

Prerequisites

• androidx.compose.ui:ui-test and androidx.compose.ui:ui-test-junit4 (or runComposeUiTest).
• A ComposeContestTestRule from createComposeRule() (PREFERRED v2: androidx.compose.ui.test.junit4.v2.createComposeRule).
• For experimental waitUntilNodeCount/waitUntilExactlyOneExists/waitUntilAtLeastOneExists/waitUntilDoesNotExist: @OptIn(ExperimentalTestApi::class) on the test class or method.

What "idle" means

Three conditions, all true at once (compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/ComposeUiTest.kt:174-186):

1. No pending recompositions. No snapshot apply notifications outstanding, no recomposer pending work, no withFrameNanos awaiters on the test frame clock.
2. No pending draw call. Measure and layout passes have run; on Android the draw pass has been requested by the framework (Choreographer drives draw on Android, the test clock does not — MainTestClock.kt:36-41).
3. All registered IdlingResources report isIdleNow == true. This is how non-Compose async work (an OkHttp call, a Room query) participates in synchronization.

Compose's own work registers automatically through ComposeIdlingResource (compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeIdlingResource.android.kt), which drains the recomposer + snapshot + frame-clock awaiters in a loop capped at 100 frames per call (line 109). A test that needs more than 100 frames to settle is doing too much per waitForIdle.

The primitive surface

Every entry below is from ComposeUiTest.kt / ComposeTestRule.jvmAndAndroid.kt.

API	Effect	Timeout source
waitForIdle()	Blocks current thread until the three idle conditions hold. With autoAdvance = true, also auto-advances the clock to drain pending work.	Wall clock — IdlingPolicies.getMasterIdlingPolicy()
awaitIdle()	suspend variant of waitForIdle.	Same
waitUntil(conditionDescription, timeoutMillis = 1_000, condition)	Blocks until condition() returns true. Each iteration calls mainClock.advanceTimeByFrame() (when autoAdvance == true) AND Thread.sleep(10) wall clock (ComposeUiTest.android.kt:899-902). The timeout is measured against System.nanoTime(), so it expires on wall-clock time even though the test clock also advances.	Wall clock — per-call timeoutMillis
waitUntilNodeCount(matcher, count, timeoutMillis = 1_000L)	@ExperimentalTestApi. waitUntil over onAllNodes(matcher).fetchSemanticsNodes(atLeastOneRootRequired = false).size == count (ComposeUiTest.kt:275-285).	Wall clock
waitUntilExactlyOneExists(matcher, timeoutMillis = 1_000L)	@ExperimentalTestApi. Sugar for waitUntilNodeCount(matcher, 1, timeoutMillis).	Wall clock
waitUntilAtLeastOneExists(matcher, timeoutMillis = 1_000L)	@ExperimentalTestApi. (ComposeUiTest.kt:298-305)	Wall clock
waitUntilDoesNotExist(matcher, timeoutMillis = 1_000L)	@ExperimentalTestApi. Sugar for waitUntilNodeCount(matcher, 0, timeoutMillis).	Wall clock
runOnIdle { … }	waitForIdle() then runOnUiThread { … }. The default for state mutations and reads.	Wall clock (the inner waitForIdle)
runOnUiThread { … }	Posts a FutureTask via Instrumentation.runOnMainSync (AndroidSynchronization.android.kt). If already on the UI thread, runs in-place. Does NOT wait for idle.	None
runWhenIdle { … }	waitForIdle() then runOnUiThread { … }, but suppresses the implicit waitForIdle triggered by node queries inside the lambda. Faster for assert-only blocks. MUST NOT mutate state inside.	Wall clock
awaitAndRunWhenIdle { … }	suspend variant of runWhenIdle.	Wall clock
hasPendingWork(): Boolean	Passive snapshot: are there awaiters on the main clock, snapshot changes, or recomposer pending work? Reliable only when autoAdvance = false (ComposeUiTest.kt:251-256).	None
IdlingResource registration	rule.registerIdlingResource(myResource) / unregisterIdlingResource.	Wall clock

Timeout sources — do not mix them

API	Source	Default	Override
waitForIdle / awaitIdle	Wall clock — Espresso IdlingPolicies master timeout	26 s	IdlingPolicies.setMasterPolicyTimeout(...) in @Before
waitUntil(…) family	Wall clock	1000 ms per call	per-call timeoutMillis
MainTestClock.advanceTimeUntil(…)	Test clock	1000 ms per call	per-call timeoutMillis
runComposeUiTest(testTimeout = …)	Wall clock	60.seconds	runComposeUiTest(testTimeout = 5.minutes) { … }; throws AndroidComposeUiTestTimeoutException

Skydoves hot take #4: waitUntil timeouts are wall clock; advanceTimeUntil is test clock. Always prefer mainClock.advanceTimeUntil when the awaited condition is observable through Compose state. Reserve waitUntil for conditions outside Compose's snapshot system — a Job.isCompleted, a counter incremented from a LaunchedEffect, an external service.

RobolectricIdlingStrategy reads the same Espresso IdlingPolicies.getMasterIdlingPolicy(), so a global setMasterPolicyTimeout lift applies to host (Robolectric) and device tests alike.

Espresso bridge

Espresso has its own androidx.test.espresso.IdlingResource interface, which is not the same as Compose's androidx.compose.ui.test.IdlingResource. The bridge is EspressoLink (compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/EspressoLink.android.kt):

Espresso (instrumentation tests)
        │ withStrategy { … }
        ▼
EspressoLink   ──implements──>  androidx.test.espresso.IdlingResource
        │
        │  delegates isIdleNow() to ──>  IdlingResourceRegistry
        ▼
IdlingResourceRegistry — Compose's registry
        │
        ├── ComposeIdlingResource   (recomposer + snapshot + frame-clock awaiters)
        └── any rule.registerIdlingResource(...)

The same registry is read by RobolectricIdlingStrategy for host tests. The developer registers a Compose IdlingResource; the framework does the bridging.

interface IdlingResource {
    val isIdleNow: Boolean
    fun getDiagnosticMessageIfBusy(): String? = null
}

(From compose/ui/ui-test/src/jvmAndAndroidMain/kotlin/androidx/compose/ui/test/IdlingResource.kt:37-52.) Override getDiagnosticMessageIfBusy() to surface a useful message when a wait times out — it is appended to the timeout exception text.

Decision matrix

Need to wait for…                         | Use
------------------------------------------|----------------------------------------------
A node count to stabilize                 | waitUntilNodeCount / waitUntilExactlyOneExists
A node to appear                          | waitUntilAtLeastOneExists
A node to disappear                       | waitUntilDoesNotExist
A Compose state condition                 | mainClock.advanceTimeUntil { state }
A non-Compose condition (Job, counter)    | waitUntil(conditionDescription) { condition }
"Just settle the UI"                      | waitForIdle()  (or runOnIdle for read+act)
External async work (HTTP, DB)            | rule.registerIdlingResource(MyIdlingResource)
A paused-clock animation frame            | mainClock.advanceTimeBy(...)  -- different skill
A particular state.value to read safely   | rule.runOnIdle { state.value }

Workflow

1. Default to runOnIdle for state interaction

Reading or mutating Compose state from the test thread races the recomposer. The recomposer applies snapshot writes on the main thread; the test thread can observe a half-applied state. runOnIdle solves this by waiting for idle then dispatching to the UI thread:

val firstVisibleIndex = rule.runOnIdle { state.firstVisibleItemIndex }

(skydoves hot take #5 — funnel state mutations through runOnIdle or runOnUiThread.)

2. Reach for runWhenIdle for read-only assertion blocks

rule.runWhenIdle {
    val node = rule.onNodeWithTag("counter").fetchSemanticsNode()
    assertEquals("3", node.config[SemanticsProperties.Text].first().text)
    val rect = node.boundsInRoot
    // ... more reads ...
}

Each node query inside a normal runOnIdle re-runs waitForIdle(). Inside runWhenIdle, those implicit waits are suppressed because the block already entered with idle witnessed. This matters for tests that step frames manually — node queries inside runOnIdle would call waitForIdle() repeatedly, which (under autoAdvance = true) auto-advances the clock and undoes the test's manual control. MUST NOT mutate state inside runWhenIdle.

3. Reach for the experimental waitUntilExactlyOneExists / friends for "wait until N nodes match"

@OptIn(ExperimentalTestApi::class)
@Test fun snackbarAppears() {
    rule.setContent { /* … triggers a snackbar after 200 ms … */ }
    rule.onNodeWithTag("trigger").performClick()
    rule.waitUntilExactlyOneExists(hasTestTag("snackbar"), timeoutMillis = 2_000)
    rule.onNodeWithTag("snackbar").assertTextEquals("Saved")
}

The default 1000 ms timeout (ComposeUiTest.kt:278, ComposeUiTest.kt:301, ComposeUiTest.kt:321, ComposeUiTest.kt:334) is often too tight for snackbars and bottom-sheet animations. Lift it explicitly per call.

4. Reach for waitUntil { … } only for non-Compose conditions

// SnackbarHostTest.kt:77-88
val job = scope.launch {
    hostState.showSnackbar("1")
    Truth.assertThat(resultedInvocation).isEqualTo("1")
    hostState.showSnackbar("2")
    Truth.assertThat(resultedInvocation).isEqualTo("12")
    hostState.showSnackbar("3")
    Truth.assertThat(resultedInvocation).isEqualTo("123")
}
rule.waitUntil { job.isCompleted }

Job.isCompleted is not Compose state; mainClock.advanceTimeUntil { job.isCompleted } would loop and time out because no amount of clock advancement makes the Job complete on its own.

5. Register an IdlingResource for genuine external async work

class HttpIdlingResource(private val client: OkHttpClient) : IdlingResource {
    override val isIdleNow: Boolean
        get() = client.dispatcher.runningCallsCount() == 0
    override fun getDiagnosticMessageIfBusy(): String? =
        "${client.dispatcher.runningCallsCount()} HTTP calls still in flight"
}

@Before fun setUp() { rule.registerIdlingResource(HttpIdlingResource(client)) }
@After  fun tearDown() { rule.unregisterIdlingResource(HttpIdlingResource(client)) }

After registration, every waitForIdle (and the implicit waitForIdle inside every node query) will block until isIdleNow == true. MUST keep isIdleNow lightweight — it is called from the main thread (IdlingResource.kt:38-46).

Patterns

Pattern: WRONG — Thread.sleep to wait for a node

// WRONG
@Test fun successScreen() {
    rule.setContent { App() }
    rule.onNodeWithTag("login").performClick()
    Thread.sleep(2_000)
    rule.onNodeWithTag("dashboard").assertExists()
}
// WRONG because: Thread.sleep is unrelated to Compose's synchronization. It either over-
// waits (slowing the test) or under-waits (flake when CI is slow). Compose's own
// IdlingResource is already wired; just wait on the node directly.

// RIGHT
@OptIn(ExperimentalTestApi::class)
@Test fun successScreen() {
    rule.setContent { App() }
    rule.onNodeWithTag("login").performClick()
    rule.waitUntilExactlyOneExists(hasTestTag("dashboard"), timeoutMillis = 2_000)
    rule.onNodeWithTag("dashboard").assertExists()
}

Pattern: WRONG — waitUntil for a Compose-state-observable condition

// WRONG
rule.waitUntil(timeoutMillis = 5_000) { state.value == Phase.Done }
// WRONG because: timeout is measured in wall clock and each iteration burns ~10 ms
// of real time on Thread.sleep(10) (ComposeUiTest.android.kt:899-902). For a Compose
// state condition, advanceTimeUntil drives the test clock and is deterministic.

// RIGHT
rule.mainClock.advanceTimeUntil(timeoutMillis = 5_000) { state.value == Phase.Done }

(skydoves hot take #4.)

Pattern: WRONG — reading state from the test thread

// WRONG
val i = state.firstVisibleItemIndex
assertEquals(2, i)
// WRONG because: the test thread races the recomposer. The read may observe a half-applied
// snapshot, especially right after a click or scroll. Compose's docs are explicit: state
// reads from outside the UI thread are not synchronized.

// RIGHT
val i = rule.runOnIdle { state.firstVisibleItemIndex }
assertEquals(2, i)

(skydoves hot take #5.)

Pattern: hasPendingWork() — passive check, paused-clock only

rule.mainClock.autoAdvance = false
rule.setContent { /* … */ }
rule.mainClock.advanceTimeByFrame()
rule.runOnUiThread { trigger = true }
assertTrue(rule.hasPendingWork())              // recomposition queued, no frame yet
rule.mainClock.advanceTimeByFrame()
assertFalse(rule.hasPendingWork())             // frame applied

From ComposeUiTest.kt:251-256:

If autoAdvance is true, the testing framework continuously processes pending work. In that scenario, calling this method acts as a momentary snapshot and will generally return false. It may briefly return true if work is queued but the framework hasn't auto-advanced yet, making the result fleeting and unreliable for driving test logic.

MUST NOT drive test logic off hasPendingWork() while autoAdvance == true.

Pattern: lift the master idling timeout for slow CI

@Before fun setUp() {
    IdlingPolicies.setMasterPolicyTimeout(60, TimeUnit.SECONDS)
}

Apply when waitForIdle (not waitUntil) times out on CI but passes locally. Both EspressoLink and RobolectricIdlingStrategy honor this policy.

Mandatory rules

• MUST prefer mainClock.advanceTimeUntil { state } over rule.waitUntil { state } whenever the awaited condition is a Compose-state read (skydoves hot take #4).
• MUST wrap state reads from the test thread in runOnIdle { … } or runOnUiThread { … }. Direct state.value reads from the test thread race the recomposer (skydoves hot take #5).
• MUST call runOnUiThread (not runOnIdle) for state mutations under a paused clock (autoAdvance = false); runOnIdle's implicit waitForIdle is wrong for that mode. See ../testing-animations-deterministically/SKILL.md.
• MUST use runWhenIdle { … } for assert-only blocks that do many node reads — it suppresses the redundant per-query waitForIdle. MUST NOT mutate state inside.
• MUST prefer waitUntilExactlyOneExists / waitUntilAtLeastOneExists / waitUntilDoesNotExist over hand-rolled waitUntil { onAllNodes(...).fetchSemanticsNodes().isNotEmpty() }. They are clearer and cite a conditionDescription in the timeout message.
• MUST NOT treat hasPendingWork() as actionable while autoAdvance == true. It is a passive snapshot; reliable only with the clock paused (ComposeUiTest.kt:251-256).
• MUST NOT use Thread.sleep to wait for state to settle. Replace with waitUntil*, mainClock.advanceTimeUntil, or an IdlingResource (skydoves hot take #7). The one legitimate Thread.sleep is on the RenderThread for ripple/screenshot tests.
• PREFERRED: an IdlingResource per genuine external async source (HTTP, DB, an external counter), registered in @Before and unregistered in @After. Override getDiagnosticMessageIfBusy() so timeout messages are useful.
• PREFERRED: IdlingPolicies.setMasterPolicyTimeout(...) in @Before for CI flakes due to slow agents — uniformly lifts both Espresso and Robolectric.

Verification

• No Thread.sleep exists in any test method except the documented RenderThread/screenshot exceptions.
• Every state read from the test thread is wrapped in runOnIdle { … } (search: grep -nP 'state\.\w+' src/androidTest).
• Every waitUntil { state.value … } for a Compose-state condition has been migrated to mainClock.advanceTimeUntil { state.value … }.
• Every "wait for node" path uses waitUntilExactlyOneExists / waitUntilAtLeastOneExists / waitUntilDoesNotExist rather than a hand-rolled waitUntil over fetchSemanticsNodes().
• Every external async source has a registered IdlingResource, registered in @Before and unregistered in @After.
• No call site relies on hasPendingWork() while autoAdvance == true.
• CI run completes 50 iterations without an AndroidComposeUiTestTimeoutException or ComposeTimeoutException flake.

References

• Android Developers — Compose testing: https://developer.android.com/develop/ui/compose/testing
• Android Developers — Compose testing cheat sheet: https://developer.android.com/develop/ui/compose/testing-cheatsheet
• Espresso IdlingPolicies reference: https://developer.android.com/reference/androidx/test/espresso/IdlingPolicies
• compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/ComposeUiTest.kt:174-260 — waitForIdle, awaitIdle, waitUntil, runOnIdle, runOnUiThread, runWhenIdle, awaitAndRunWhenIdle, hasPendingWork.
• compose/ui/ui-test/src/commonMain/kotlin/androidx/compose/ui/test/ComposeUiTest.kt:275-335 — the experimental waitUntilNodeCount / waitUntilExactlyOneExists / waitUntilAtLeastOneExists / waitUntilDoesNotExist extensions.
• compose/ui/ui-test/src/jvmAndAndroidMain/kotlin/androidx/compose/ui/test/IdlingResource.kt — the public IdlingResource interface.
• compose/ui/ui-test/src/jvmAndAndroidMain/kotlin/androidx/compose/ui/test/IdlingResourceRegistry.jvmAndAndroid.kt — the registry that aggregates user-registered resources + Compose's own.
• compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeIdlingResource.android.kt — Compose's automatically-registered resource; 100-frame cap at line 109.
• compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/EspressoLink.android.kt — the androidx.test.espresso.IdlingResource bridge.
• compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeUiTest.android.kt:885-908 — waitUntil's 10 ms wall-clock poll loop.
• compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/AndroidSynchronization.android.kt — runOnUiThread posts a FutureTask via Instrumentation.runOnMainSync.
• compose/material3/material3/src/androidDeviceTest/kotlin/androidx/compose/material3/SnackbarHostTest.kt:77-88 — canonical rule.waitUntil { job.isCompleted }.
• Sibling skill: ../controlling-the-test-clock/SKILL.md — MainTestClock, frame model, advanceTimeUntil.
• Sibling skill: ../testing-animations-deterministically/SKILL.md — paused-clock animation tests.
• Sibling skill: ../../patterns/structuring-a-compose-test/SKILL.md — JUnit lifecycle around idle waits.
• Sibling skill: ../../debug/printing-the-semantics-tree/SKILL.md — when "node not found" turns out to be a finder issue, not an async issue.