Synchronizing With Idle

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.