SkikoComposeUiTest: Android-shaped idle/draw, decouple draw from the frame clock

MatkovIvan · MatkovIvan · commit d25552448479 · 2026-06-06T20:59:02.000+02:00
Reworks the skiko test harness so waiting and capturing mirror Android's
ComposeIdlingResource / waitForNextChoreographerFrame model.

- Split the old render() into performFrame() (advances the frame clock) and
  redraw() (re-renders settled state WITHOUT advancing the clock), the analog of
  Android's forceRedraw() on capture. captureToImage() drives redraw() itself.
- isIdle() no longer gates on draw (matching ComposeIdlingResource.isIdleNow):
  it waits on snapshot apply + measure/layout only; a pending draw is flushed
  after the wait by ensureScheduledDrawCompleted().
- Unify waitForIdle()/awaitIdle() over runUntilIdle { pace }, bounded by
  testTimeout so a never-settling test fails fast instead of hanging.
- Apply snapshot changes after each resumed continuation via
  ApplyingContinuationInterceptor; runInternalSkikoComposeUiTest no longer wraps
  runTest.
- Add DrawOnlyInvalidationTest covering draw-only vs measure vs recomposition
  invalidation under paused/running clocks (Android-verified expectations).
diff --git a/compose/ui/ui-test/src/skikoMain/kotlin/androidx/compose/ui/test/ComposeUiTest.skiko.kt b/compose/ui/ui-test/src/skikoMain/kotlin/androidx/compose/ui/test/ComposeUiTest.skiko.kt
@@ -38,7 +38,6 @@ import androidx.compose.ui.platform.PlatformWindowInsets
 import androidx.compose.ui.platform.WindowInfo
 import androidx.compose.ui.scene.CanvasLayersComposeScene
 import androidx.compose.ui.scene.ComposeScene
-import androidx.compose.ui.scene.hasInvalidations
 import androidx.compose.ui.semantics.SemanticsNode
 import androidx.compose.ui.unit.Density
 import androidx.compose.ui.unit.DpSize
@@ -52,8 +51,7 @@ import kotlin.coroutines.EmptyCoroutineContext
 import kotlin.coroutines.cancellation.CancellationException
 import kotlin.math.roundToInt
 import kotlin.time.Duration
-import kotlin.time.DurationUnit
-import kotlin.time.toDuration
+import kotlin.time.TimeSource
 import kotlinx.coroutines.CoroutineDispatcher
 import kotlinx.coroutines.CoroutineExceptionHandler
 import kotlinx.coroutines.CoroutineScope
@@ -221,7 +219,8 @@ open class SkikoComposeUiTest @InternalTestApi constructor(
 
     private val recomposerCoroutineScope = CoroutineScope(
         effectContext +
-            compositionCoroutineDispatcher +
+            // Apply snapshot changes after every resumed continuation.
+            ApplyingContinuationInterceptor(compositionCoroutineDispatcher) +
             infiniteAnimationPolicy +
             uncaughtExceptionHandler +
             Job()
@@ -303,8 +302,11 @@ open class SkikoComposeUiTest @InternalTestApi constructor(
                 while (isActive) {
                     delay(FRAME_DELAY_MILLIS)
                     runOnUiThread {
-                        render(mainClock.currentTime)
+                        frameRecomposer.performFrame(
+                            frameTimeNanos = mainClock.currentTime * NanoSecondsPerMilliSecond,
+                        )
                     }
+                    redraw()
                 }
             }
             block()
@@ -314,13 +316,17 @@ open class SkikoComposeUiTest @InternalTestApi constructor(
     }
 
     /**
-     * Render the scene at the given time.
+     * Redraws the current (already-settled) state into [surface] WITHOUT advancing the frame clock,
+     * so a capture reflects the latest state. This is the analog of Android's `View.forceRedraw()` on
+     * capture: draw is decoupled from idle, so producing an up-to-date image is the capture's
+     * responsibility rather than the idle loop's.
      */
-    private fun render(timeMillis: Long) {
-        surface.canvas.clear(Color.TRANSPARENT)
-        frameRecomposer.performFrame(timeMillis * NanoSecondsPerMilliSecond)
+    private fun redraw() = runOnUiThread {
         scene.measureAndLayout()
-        scene.draw(surface.canvas.asComposeCanvas())
+        with(surface.canvas) {
+            clear(Color.TRANSPARENT)
+            scene.draw(asComposeCanvas())
+        }
     }
 
     private fun createScene() {
@@ -349,7 +355,15 @@ open class SkikoComposeUiTest @InternalTestApi constructor(
             // The rendering is done by withRenderLoop
         } else {
             runOnUiThread {
-                render(mainClock.currentTime)
+                // Settle non-frame work WITHOUT advancing the frame clock - drain
+                // the currently-due tasks via the test scheduler, then run measure/layout.
+                // Never [frameRecomposer.performFrame], so withFrameNanos awaiters are not resumed.
+                compositionCoroutineDispatcher.scheduler.runCurrent()
+                scene.measureAndLayout()
+
+                // Publish global snapshot writes produced during this settle,
+                // so the next isIdle() sees an applied state.
+                Snapshot.sendApplyNotifications()
             }
         }
     }
@@ -360,48 +374,86 @@ open class SkikoComposeUiTest @InternalTestApi constructor(
             return false
         }
 
-        if (!mainClock.autoAdvance) {
-            return true
+        // Only an auto-advancing clock waits for recomposition/effects/frame work to drain.
+        // With a frozen clock the test drives frames itself, so a parked withFrameNanos awaiter
+        // only resumes when the test advances the clock - gating on it here would hang.
+        if (mainClock.autoAdvance && frameRecomposer.hasPendingWork()) {
+            return false
         }
 
+        // Idle once pending snapshot writes are applied and measure/layout has settled.
+        // Do NOT gate on draw, matching Android's ComposeIdlingResource.isIdleNow (which checks
+        // recomposition + measure/layout, not draw). A pending draw is instead flushed after the
+        // wait loop by [ensureScheduledDrawCompleted], mirroring Android's waitForNextChoreographerFrame.
         return !Snapshot.current.hasPendingChanges()
             && !Snapshot.isApplyObserverNotificationPending
-            && !frameRecomposer.hasPendingWork()
-            && !scene.hasInvalidations()
+            && !scene.hasPendingMeasureOrLayout
             && areAllResourcesIdle()
     }
 
     override fun waitForIdle() {
-        val startedAt = currentNanoTime().toDuration(DurationUnit.NANOSECONDS)
-        var lastReportedElapsedSeconds = 0L
-        // always check even if we are idle
-        uncaughtExceptionHandler.throwUncaught()
-        while (!isIdle()) {
-            advanceIfNeededAndRenderNextFrame()
-            uncaughtExceptionHandler.throwUncaught()
+        // Mirrors Android's two-step waitForIdle(): await idleness, then ensure the scheduled draw
+        // has completed (cf. idlingStrategy.runUntilIdle() + waitForNextChoreographerFrame()).
+        runUntilIdle {
             if (!areAllResourcesIdle()) {
                 sleep(IDLING_RESOURCES_CHECK_INTERVAL_MS)
             }
-            val currentTime = currentNanoTime().toDuration(DurationUnit.NANOSECONDS)
-            val elapsedSeconds = (currentTime - startedAt).inWholeSeconds
-            if (elapsedSeconds > lastReportedElapsedSeconds) {
-                println("Suspicious! waitForIdle has not finished after $elapsedSeconds seconds.")
-                lastReportedElapsedSeconds = elapsedSeconds
-            }
         }
+        ensureScheduledDrawCompleted()
     }
 
-    override suspend fun awaitIdle() {
-        // always check even if we are idle
+    /**
+     * Awaits composition, measure and layout - the analog of Android's idlingStrategy.runUntilIdle().
+     * Draw is intentionally NOT awaited here (see [isIdle], mirroring Android's
+     * `ComposeIdlingResource.isIdleNow`); callers flush it afterwards via [ensureScheduledDrawCompleted].
+     *
+     * [pace] runs after each rendered frame to back off before re-checking idleness: a blocking sleep
+     * for [waitForIdle], a suspending delay/yield for [awaitIdle]. It is [inline] so [pace] can suspend
+     * when called from [awaitIdle].
+     */
+    private inline fun runUntilIdle(pace: () -> Unit) {
+        // Always check even if we are idle.
         uncaughtExceptionHandler.throwUncaught()
+        val startedAt = TimeSource.Monotonic.markNow()
         while (!isIdle()) {
             advanceIfNeededAndRenderNextFrame()
             uncaughtExceptionHandler.throwUncaught()
+            // Bound the wait by [testTimeout] so a test that never settles fails fast.
+            if (startedAt.elapsedNow() > testTimeout) {
+                throw ComposeTimeoutException("waitForIdle: timeout $testTimeout reached")
+            }
+            pace()
+        }
+    }
+
+    /**
+     * Ensures a scheduled draw has completed before returning from a wait - the skiko analog of the
+     * `waitForNextChoreographerFrame()` step at the end of Android's `waitForIdle()` ("wait for the
+     * next frame to ensure any scheduled drawing has completed"). On Android the draw is produced by
+     * the Choreographer/ViewRootImpl pipeline running during the wait; there is no such pipeline here
+     * and [withRenderLoop] is inert under a paused clock, so we render the pending draw directly.
+     *
+     * A snapshot read only in draw scope (e.g. drawBehind/Canvas) invalidates the layer without any
+     * pending measure/layout, so it is intentionally not part of [isIdle] - matching Android, whose
+     * `ComposeIdlingResource.isIdleNow` also excludes draw. Verified on the Android runtime: under a
+     * paused clock a draw-only state change is observed after `waitForIdle`. Never resumes
+     * withFrameNanos awaiters ([redraw] does measure/layout + draw only, no performFrame).
+     */
+    private fun ensureScheduledDrawCompleted() {
+        if (scene.hasPendingDraw) {
+            redraw()
+        }
+    }
+
+    override suspend fun awaitIdle() {
+        // Same two-step shape as [waitForIdle], but suspending: await idleness, then flush the draw.
+        runUntilIdle {
             if (!areAllResourcesIdle()) {
                 delay(IDLING_RESOURCES_CHECK_INTERVAL_MS)
             }
             yield()
         }
+        ensureScheduledDrawCompleted()
     }
 
     override fun <T> runOnUiThread(action: () -> T): T {
@@ -476,10 +528,12 @@ open class SkikoComposeUiTest @InternalTestApi constructor(
 
     fun captureToImage(): ImageBitmap {
         waitForIdle()
+        redraw()
         return surface.makeImageSnapshot().toComposeImageBitmap()
     }
 
     fun captureToImage(semanticsNode: SemanticsNode): ImageBitmap {
+        redraw()
         val rect = semanticsNode.boundsInWindow
         val image = surface.makeImageSnapshot(
             rect.left.toInt(),
diff --git a/compose/ui/ui-test/src/skikoMain/kotlin/androidx/compose/ui/test/v2/ComposeUiTest.skiko.kt b/compose/ui/ui-test/src/skikoMain/kotlin/androidx/compose/ui/test/v2/ComposeUiTest.skiko.kt
@@ -138,7 +138,7 @@ fun runSkikoComposeUiTest(
 }
 
 @InternalTestApi
-@OptIn(InternalComposeUiApi::class, ExperimentalTestApi::class, ExperimentalCoroutinesApi::class)
+@OptIn(ExperimentalTestApi::class, InternalComposeUiApi::class)
 fun runInternalSkikoComposeUiTest(
     width: Int = 1024,
     height: Int = 768,
@@ -150,17 +150,15 @@ fun runInternalSkikoComposeUiTest(
     windowInsets: PlatformWindowInsets? = null,
     block: suspend SkikoComposeUiTest.() -> Unit,
 ): TestResult {
-    return runTest {
-        SkikoComposeUiTest(
-            width = width,
-            height = height,
-            effectContext = effectContext,
-            runTestContext = runTestContext,
-            testTimeout = testTimeout,
-            density = density,
-            semanticsOwnerListener = semanticsOwnerListener,
-            windowInsets = windowInsets,
-            useStandardTestDispatcherForComposition = true,
-        ).runTest(block)
-    }
+    return SkikoComposeUiTest(
+        width = width,
+        height = height,
+        effectContext = effectContext,
+        runTestContext = runTestContext,
+        testTimeout = testTimeout,
+        density = density,
+        semanticsOwnerListener = semanticsOwnerListener,
+        windowInsets = windowInsets,
+        useStandardTestDispatcherForComposition = true,
+    ).runTest(block)
 }
diff --git a/compose/ui/ui-test/src/skikoTest/kotlin/androidx/compose/ui/test/DrawOnlyInvalidationTest.kt b/compose/ui/ui-test/src/skikoTest/kotlin/androidx/compose/ui/test/DrawOnlyInvalidationTest.kt
@@ -0,0 +1,120 @@
+/*
+ * Copyright 2026 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.compose.ui.test
+
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.drawBehind
+import androidx.compose.ui.layout.Layout
+import kotlin.test.Test
+import kotlin.test.assertEquals
+
+@OptIn(ExperimentalTestApi::class)
+class DrawOnlyInvalidationTest {
+
+    /**
+     * Paused clock: the first frame is drawn by `waitForIdle`, and a subsequent draw-only
+     * invalidation is also flushed by `waitForIdle` - without `captureToImage`. Android-verified:
+     * `afterSetContent=[0] afterFirstWait=[0] afterMutate=[0] afterWaitAfterMutate=[0, 1]`.
+     */
+    @Test
+    fun pausedClock_drawOnlyInvalidationIsFlushedByWaitForIdle() = runComposeUiTest {
+        mainClock.autoAdvance = false
+        val state = mutableStateOf(0)
+        val drawn = mutableListOf<Int>()
+        setContent {
+            Layout(
+                modifier = Modifier.drawBehind { drawn.add(state.value) },
+                measurePolicy = { _, _ -> layout(10, 10) {} }
+            )
+        }
+        waitForIdle()
+        assertEquals(listOf(0), drawn, "first frame should be drawn by waitForIdle")
+
+        state.value = 1 // draw-only invalidation: no measure/layout/recomposition
+        waitForIdle() // no clock advance, no captureToImage
+        assertEquals(listOf(0, 1), drawn, "draw-only update should be flushed by waitForIdle")
+    }
+
+    /**
+     * Paused clock, measure invalidation (state read in measure): flushed by `waitForIdle`.
+     * Android-verified: draw count 1 -> 2.
+     */
+    @Test
+    fun pausedClock_measureInvalidationIsFlushedByWaitForIdle() = runComposeUiTest {
+        mainClock.autoAdvance = false
+        val state = mutableStateOf(0)
+        val drawn = mutableListOf<Int>()
+        setContent {
+            Layout(
+                modifier = Modifier.drawBehind { drawn.add(-1) },
+                measurePolicy = { _, _ ->
+                    val s = state.value // read in measure -> measure invalidation
+                    layout(10 + s, 10) {}
+                }
+            )
+        }
+        waitForIdle()
+        assertEquals(1, drawn.size)
+        state.value = 1
+        waitForIdle()
+        assertEquals(2, drawn.size, "measure invalidation should trigger a redraw")
+    }
+
+    /**
+     * Paused clock, recomposition invalidation (state read in composition) is NOT flushed without
+     * advancing the clock: recomposition is driven by the frame clock, so a paused clock leaves it
+     * pending (and, per [MainTestClock], pending recompositions are not awaited when autoAdvance is
+     * false). Android-verified: `[0] -> [0]`.
+     */
+    @Test
+    fun pausedClock_recompositionIsNotFlushedWithoutAdvancingClock() = runComposeUiTest {
+        mainClock.autoAdvance = false
+        val state = mutableStateOf(0)
+        val drawn = mutableListOf<Int>()
+        setContent {
+            val v = state.value // read in composition -> recomposition invalidation
+            Layout(
+                modifier = Modifier.drawBehind { drawn.add(v) },
+                measurePolicy = { _, _ -> layout(10, 10) {} }
+            )
+        }
+        waitForIdle()
+        assertEquals(listOf(0), drawn)
+        state.value = 1
+        waitForIdle()
+        assertEquals(listOf(0), drawn, "recomposition should stay pending under a paused clock")
+    }
+
+    /** Running clock (autoAdvance=true, the default): draw-only invalidation flushed. */
+    @Test
+    fun runningClock_drawOnlyInvalidationIsFlushed() = runComposeUiTest {
+        val state = mutableStateOf(0)
+        val drawn = mutableListOf<Int>()
+        setContent {
+            Layout(
+                modifier = Modifier.drawBehind { drawn.add(state.value) },
+                measurePolicy = { _, _ -> layout(10, 10) {} }
+            )
+        }
+        waitForIdle()
+        assertEquals(listOf(0), drawn)
+        state.value = 1
+        waitForIdle()
+        assertEquals(listOf(0, 1), drawn)
+    }
+}
