setting-up-host-vs-device-tests

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Setting Up Host vs Device Tests — Pick the Right Source Set

配置主机测试与设备测试——选择正确的源代码集

Compose tests run unchanged on either Robolectric (JVM, fast, no emulator) or on a real/virtual device (full Android stack, RenderThread, accessibility). The same
runComposeUiTest { setContent { … } }
block compiles in both — only the underlying
Looper
and
Choreographer
differ. This skill encodes which flavor each test should live in, the Robolectric class skeleton, and the one legitimate
Thread.sleep
exception (screenshot tests waiting on the RenderThread).
Compose 测试无需修改即可在 Robolectric(JVM、快速、无需模拟器)或真实/虚拟设备(完整 Android 技术栈、RenderThread、无障碍)上运行。同一个
runComposeUiTest { setContent { … } }
代码块在两者中均可编译——只有底层的
Looper
和
Choreographer
不同。此 skill 规定了每类测试应使用的测试环境、Robolectric 类骨架,以及唯一允许使用
Thread.sleep
的例外情况(截图测试等待 RenderThread)。

When to use this skill

何时使用此 skill

  • The user is starting a Compose UI test and asks "test/ or androidTest/?".
  • A test passes on a local emulator but fails on CI's Robolectric runner (or vice versa).
  • The user reports
    Build.FINGERPRINT == "robolectric"
    warnings from
    enableAccessibilityChecks(...)
    .
  • A screenshot test produces a black/empty PNG on the host runner.
  • A ripple/
    pressInteraction
    test renders no ripple on Robolectric and the user is debugging why.
  • The user wrote
    Thread.sleep(1000)
    to "wait for an animation" and is asking why it is flaky.
  • The user mentions
    androidDeviceTest
    /
    androidHostTest
    source sets (used in
    androidx
    itself).
  • 用户刚开始编写 Compose UI 测试,并询问“test/ 还是 androidTest/?”。
  • 测试在本地模拟器上通过,却在 CI 的 Robolectric runner 上失败(或反之)。
  • 用户报告
    enableAccessibilityChecks(...)
    出现
    Build.FINGERPRINT == "robolectric"
    警告。
  • 截图测试在 host runner 上生成黑色或空白 PNG。
  • ripple/
    pressInteraction
    测试在 Robolectric 上没有渲染任何涟漪,用户正在排查原因。
  • 用户编写了
    Thread.sleep(1000)
    来“等待动画完成”,并询问为什么测试容易出现不稳定。
  • 用户提到
    androidDeviceTest
    或
    androidHostTest
    源代码集(androidx 自身使用的划分方式)。

When NOT to use this skill

何时不应使用此 skill

  • The dependencies are not yet wired correctly — start with
    ./configuring-test-dependencies/SKILL.md
    .
  • The choice is between
    createComposeRule()
    and
    runComposeUiTest { }
    — see
    ./choosing-test-rule-vs-runtest/SKILL.md
    .
  • The test runs in the right flavor but is flaky on idle/animation — see
    ../../synchronization/synchronizing-with-idle/SKILL.md
    and
    ../../synchronization/testing-animations-deterministically/SKILL.md
    .
  • 依赖项尚未正确配置——请先参阅
    ./configuring-test-dependencies/SKILL.md
    。
  • 需要在
    createComposeRule()
    和
    runComposeUiTest { }
    之间选择——请参阅
    ./choosing-test-rule-vs-runtest/SKILL.md
    。
  • 测试已放在正确的测试环境中,但在空闲或动画处理方面仍不稳定——请参阅
    ../../synchronization/synchronizing-with-idle/SKILL.md
    和
    ../../synchronization/testing-animations-deterministically/SKILL.md
    。

Prerequisites

前置条件

  • androidx.compose.ui:ui-test
    ,
    ui-test-junit4
    , and
    ui-test-manifest
    on the correct configurations for the chosen flavor — see
    ./configuring-test-dependencies/SKILL.md
    .
  • For host tests:
    org.robolectric:robolectric
    on
    testImplementation
    ,
    testOptions { unitTests.isIncludeAndroidResources = true }
    in the Android block.
  • For device tests: a configured emulator or physical device,
    androidx.test.runner.AndroidJUnitRunner
    (or a Hilt subclass) as the
    testInstrumentationRunner
    .
  • Working knowledge of
    MainTestClock
    semantics — see the synchronization skill set.
  • 对于所选测试环境,应在正确的 configuration 中配置
    androidx.compose.ui:ui-test
    、
    ui-test-junit4
    和
    ui-test-manifest
    ——请参阅
    ./configuring-test-dependencies/SKILL.md
    。
  • 对于 host test:在
    testImplementation
    中添加
    org.robolectric:robolectric
    ,并在 Android 的
    android { }
    块中设置
    testOptions { unitTests.isIncludeAndroidResources = true }
    。
  • 对于 device test:准备已配置的模拟器或物理设备,并将
    androidx.test.runner.AndroidJUnitRunner
    (或 Hilt 子类)设置为
    testInstrumentationRunner
    。
  • 熟悉
    MainTestClock
    的语义——请参阅同步相关的 skill 集合。

Workflow

工作流

  • 1. Decide the flavor by capability, not by speed. The matrix:
    CapabilityHost (Robolectric,
    src/test/
    )
    Device (instrumentation,
    src/androidTest/
    )
    Recomposition + state changesWorksWorks
    Layout + measurementWorksWorks
    Touch input via
    performTouchInput
    Works (synthetic events)Works (real input pipeline)
    Modifier.indication
    ripples
    No (RenderThread not driven)Works
    Screenshot capture (
    captureToImage
    )
    No (no real surface)Works
    enableAccessibilityChecks(...)
    Inconclusive —
    ComposeUiTestExt.android.kt:50-53
    logs
    Log.w("ComposeUiTest", "Accessibility checks are currently not supported by Robolectric")
    and still installs the validator, but Robolectric does not faithfully drive accessibility services (b/332778271). Treat passing as inconclusive.
    Works (
    @RequiresApi(34)
    )
    Gesture detectors needing real-time clock changes (double-tap, long-press timing)Works only with manual
    mainClock.advanceTimeBy(...)
    Works automatically
    Activity lifecycle (real
    onPause
    /
    onResume
    )
    ApproximatedReal
    Min SDK23 (
    internal const val RobolectricMinSdk = 23
    from
    compose/ui/ui-test/src/androidHostTest/.../Constants.kt
    )
    The module's
    minSdk
    Speed (rough order)SecondsTens of seconds + emulator boot
    CI footprintJVM onlyEmulator service or Firebase Test Lab
    Choose host for logic/recomposition/finder coverage. Choose device for anything that touches the RenderThread, real animations involving
    Modifier.indication
    , screenshot golden tests, or accessibility validation.
  • 2. Place files in the matching source set. The androidx convention is:
    text
    src/
    ├── androidHostTest/        # = test/ — Robolectric on JVM
    │   └── kotlin/.../FooTest.kt
    ├── androidDeviceTest/      # = androidTest/ — instrumentation
    │   └── kotlin/.../FooScreenshotTest.kt
    └── androidCommonTest/      # helpers shared by both
        └── kotlin/.../FooTestHelpers.kt
    In a typical app module without KMP source sets, the equivalent is
    src/test/
    (host) and
    src/androidTest/
    (device). The same
    runComposeUiTest { setContent { … } }
    body compiles unchanged in both — only the Looper/Choreographer differs at runtime.
  • 3. Configure the host test class skeleton. Copy the canonical androidx pattern from
    compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/RobolectricComposeTest.kt
    :
kotlin
@RunWith(AndroidJUnit4::class)
@Config(minSdk = 23)
@OptIn(ExperimentalTestApi::class)
class MyHostTest {
    @Before
    fun setup() {
        // capture the master timeout so we can restore it afterwards
        masterTimeout = IdlingPolicies.getMasterIdlingPolicy()
    }

    @After
    fun tearDown() {
        masterTimeout?.let {
            IdlingPolicies.setMasterPolicyTimeout(it.idleTimeout, it.idleTimeoutUnit)
        }
    }

    @Test
    fun stateChange() = runComposeUiTest {
        setContent { ClickCounter() }
        onNodeWithText("Click me").performClick()
        onNodeWithText("Click count", substring = true).assertTextEquals("Click count: 1")
    }

    private var masterTimeout: IdlingPolicy? = null
}
AndroidJUnit4::class
delegates to Robolectric on the JVM and to
AndroidJUnit4ClassRunner
on a device — making the same class portable.
@RunWith(RobolectricTestRunner::class)
also works but ties the class to host-only.
  • 4. Configure the device test class skeleton.
kotlin
@RunWith(AndroidJUnit4::class)
class MyDeviceTest {
    @get:Rule val rule = createComposeRule()       // or v2 import — see ./choosing-test-rule-vs-runtest/

    @Test
    fun stateChange() {
        rule.setContent { ClickCounter() }
        rule.onNodeWithText("Click me").performClick()
        rule.onNodeWithText("Click count", substring = true).assertTextEquals("Click count: 1")
    }
}
  • 5. Compose
    mainClock.advanceTimeBy(...)
    for any animation/gesture-detection test.
    On Robolectric, gesture detectors (double-tap, long-press) rely on the test clock advancing — they do NOT receive real wall-clock ticks. The
    RobolectricComposeTest.kt
    source quotes this directly: gesture detectors require manual
    mainClock.advanceTimeBy(...)
    because they detect events through clock changes. Same applies to any
    animateFloatAsState
    driven by the recomposer's frame clock — see
    ../../synchronization/testing-animations-deterministically/SKILL.md
    .
  • 6. Identify the one legitimate
    Thread.sleep
    use case: screenshot tests waiting on the RenderThread.
    Compose's
    IdlingResource
    aggregates the recomposer, snapshot, and frame-clock awaiters, but the RenderThread is outside that aggregation. Ripple animations (
    Modifier.indication
    ) and any draw-time animation owned by the platform render pipeline cannot be waited on through
    mainClock.advanceTimeBy
    or
    waitForIdle
    . From
    compose/material3/material3/src/androidDeviceTest/.../ToggleButtonScreenshotTest.kt:115-123
    :
kotlin
rule.mainClock.autoAdvance = false
rule.onNode(isToggleable()).performTouchInput { down(center) }

rule.mainClock.advanceTimeByFrame()
rule.waitForIdle()                          // wait for measure
rule.mainClock.advanceTimeBy(milliseconds = 200)

// Ripples are drawn on the RenderThread, not the main (UI) thread, so we can't wait for
// synchronization. Instead just wait until after the ripples are finished animating.
Thread.sleep(300)

assertAgainstGolden("toggleButton_lightTheme_defaultToPressed")
This is the only case. Anywhere else,
Thread.sleep
is a smell — it desyncs from
MainTestClock
and produces flakes that wear the developer down. Use
mainClock.advanceTimeBy(durationMs)
(test clock) for animations or
rule.waitUntil(timeoutMillis = …) { … }
(wall clock) for external state.
  • 7. Enforce: NO
    Thread.sleep
    in host tests.
    Host tests cannot drive the RenderThread anyway, so the screenshot exception does not apply. Replace every
    Thread.sleep(N)
    in a host test with
    mainClock.advanceTimeBy(N)
    (animation case) or
    rule.waitUntil { … }
    (external state).
  • 8. Place screenshot, ripple, and accessibility tests in the device source set. The host runner cannot satisfy them. Specifically:
    • Screenshots:
      captureToImage()
      requires a real
      Surface
      . Host returns no pixel data.
    • Ripples:
      Modifier.indication
      draws on the RenderThread — no observable state on host.
    • Accessibility:
      enableAccessibilityChecks(...)
      is
      @RequiresApi(34)
      . On Robolectric, both extension implementations check
      Build.FINGERPRINT.lowercase() == "robolectric"
      , emit a
      Log.w
      warning, AND still install the validator — but Robolectric does not faithfully drive accessibility services, so any pass is inconclusive (b/332778271). Run accessibility checks on a real device for trustworthy results.
  • 9. Place fast logic/recomposition/state tests in the host source set. Examples that thrive on Robolectric:
    • StateRestorationTester.emulateSavedInstanceStateRestore()
      flows.
    • Pure state-change verification (
      assertTextEquals
      ,
      assertIsOn
      ).
    • LazyList finder/scroll tests that don't depend on velocity-driven physics.
    • mainClock.advanceTimeBy(durationMs)
      driven animation snapshots that don't need rasterization.
  • 1. 根据能力选择测试环境,而不是根据速度选择。 参考下表:
    能力Host(Robolectric,
    src/test/
    )
    Device(instrumentation,
    src/androidTest/
    )
    重组 + 状态变化支持支持
    布局 + 测量支持支持
    通过
    performTouchInput
    进行触摸输入
    支持(合成事件)支持(真实输入管线)
    Modifier.indication
    涟漪
    不支持(不会驱动 RenderThread)支持
    截图捕获(
    captureToImage
    )
    不支持(没有真实 Surface)支持
    enableAccessibilityChecks(...)
    结论不确定——
    ComposeUiTestExt.android.kt:50-53
    会记录
    Log.w("ComposeUiTest", "Accessibility checks are currently not supported by Robolectric")
    并仍然安装验证器,但 Robolectric 无法忠实驱动无障碍服务(b/332778271)。应将测试通过视为不确定结果。
    支持(
    @RequiresApi(34)
    )
    需要实时时钟变化的手势检测器(双击、长按计时)仅在手动调用
    mainClock.advanceTimeBy(...)
    时支持
    自动支持
    Activity 生命周期(真实的
    onPause
    /
    onResume
    )
    近似模拟真实执行
    最低 SDK23(来自
    compose/ui/ui-test/src/androidHostTest/.../Constants.kt
    的
    internal const val RobolectricMinSdk = 23
    )
    模块的
    minSdk
    速度(大致顺序)数秒数十秒,加上模拟器启动时间
    CI 资源占用仅需 JVM需要模拟器服务或 Firebase Test Lab
    对于逻辑、重组和 finder 覆盖,选择 host test。对于任何涉及 RenderThread、真实动画中的
    Modifier.indication
    、截图 golden test 或无障碍验证的测试,选择 device test。
  • 2. 将文件放在匹配的源代码集中。 androidx 的约定如下:
    text
    src/
    ├── androidHostTest/        # = test/ — Robolectric on JVM
    │   └── kotlin/.../FooTest.kt
    ├── androidDeviceTest/      # = androidTest/ — instrumentation
    │   └── kotlin/.../FooScreenshotTest.kt
    └── androidCommonTest/      # helpers shared by both
        └── kotlin/.../FooTestHelpers.kt
    在没有 KMP 源代码集的典型 app module 中,等价目录为
    src/test/
    (host)和
    src/androidTest/
    (device)。相同的
    runComposeUiTest { setContent { … } }
    代码块在两者中均可原样编译——只有运行时使用的 Looper/Choreographer 不同。
  • 3. 配置 host test 类骨架。 从
    compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/RobolectricComposeTest.kt
    复制 androidx 的标准模式:
kotlin
@RunWith(AndroidJUnit4::class)
@Config(minSdk = 23)
@OptIn(ExperimentalTestApi::class)
class MyHostTest {
    @Before
    fun setup() {
        // capture the master timeout so we can restore it afterwards
        masterTimeout = IdlingPolicies.getMasterIdlingPolicy()
    }

    @After
    fun tearDown() {
        masterTimeout?.let {
            IdlingPolicies.setMasterPolicyTimeout(it.idleTimeout, it.idleTimeoutUnit)
        }
    }

    @Test
    fun stateChange() = runComposeUiTest {
        setContent { ClickCounter() }
        onNodeWithText("Click me").performClick()
        onNodeWithText("Click count", substring = true).assertTextEquals("Click count: 1")
    }

    private var masterTimeout: IdlingPolicy? = null
}
AndroidJUnit4::class
会在 JVM 上委托给 Robolectric,在设备上委托给
AndroidJUnit4ClassRunner
——因此同一个类可以跨环境移植。也可以使用
@RunWith(RobolectricTestRunner::class)
,但这会将类绑定为仅适用于 host。
  • 4. 配置 device test 类骨架。
kotlin
@RunWith(AndroidJUnit4::class)
class MyDeviceTest {
    @get:Rule val rule = createComposeRule()       // or v2 import — see ./choosing-test-rule-vs-runtest/

    @Test
    fun stateChange() {
        rule.setContent { ClickCounter() }
        rule.onNodeWithText("Click me").performClick()
        rule.onNodeWithText("Click count", substring = true).assertTextEquals("Click count: 1")
    }
}
  • 5. 对所有动画或手势检测测试,使用 Compose 的
    mainClock.advanceTimeBy(...)
    。
    在 Robolectric 中,手势检测器(双击、长按)依赖测试时钟推进——它们不会收到真实的 wall-clock ticks。
    RobolectricComposeTest.kt
    源码直接说明:手势检测器要求手动调用
    mainClock.advanceTimeBy(...)
    ,因为它们通过时钟变化来检测事件。由 recomposer 的 frame clock 驱动的
    animateFloatAsState
    等场景同理——请参阅
    ../../synchronization/testing-animations-deterministically/SKILL.md
    。
  • 6. 找出唯一合法的
    Thread.sleep
    使用场景:截图测试等待 RenderThread。
    Compose 的
    IdlingResource
    会聚合 recomposer、snapshot 和 frame-clock awaiter,但 RenderThread 不在该聚合范围内。涟漪动画(
    Modifier.indication
    )以及任何由平台渲染管线负责的绘制时动画,都无法通过
    mainClock.advanceTimeBy
    或
    waitForIdle
    等待。来自
    compose/material3/material3/src/androidDeviceTest/.../ToggleButtonScreenshotTest.kt:115-123
    :
kotlin
rule.mainClock.autoAdvance = false
rule.onNode(isToggleable()).performTouchInput { down(center) }

rule.mainClock.advanceTimeByFrame()
rule.waitForIdle()                          // wait for measure
rule.mainClock.advanceTimeBy(milliseconds = 200)

// Ripples are drawn on the RenderThread, not the main (UI) thread, so we can't wait for
// synchronization. Instead just wait until after the ripples are finished animating.
Thread.sleep(300)

assertAgainstGolden("toggleButton_lightTheme_defaultToPressed")
仅此场景可以使用。其他任何地方使用
Thread.sleep
都是不良信号——它会与
MainTestClock
失去同步,并产生会不断消耗开发者精力的不稳定测试。对于动画,应使用
mainClock.advanceTimeBy(durationMs)
(测试时钟);对于外部状态,应使用
rule.waitUntil(timeoutMillis = …) { … }
(wall clock)。
  • 7. 强制规定:host test 中禁止使用
    Thread.sleep
    。
    Host test 本来就无法驱动 RenderThread,因此截图例外不适用。将 host test 中的每个
    Thread.sleep(N)
    替换为
    mainClock.advanceTimeBy(N)
    (动画场景)或
    rule.waitUntil { … }
    (外部状态场景)。
  • 8. 将截图、涟漪和无障碍测试放在 device 源代码集中。 Host runner 无法满足这些测试需求。具体而言:
    • 截图:
      captureToImage()
      需要真实的
      Surface
      。Host 不会返回任何像素数据。
    • 涟漪:
      Modifier.indication
      在 RenderThread 上绘制——host 上没有可观察状态。
    • 无障碍:
      enableAccessibilityChecks(...)
      带有
      @RequiresApi(34)
      。在 Robolectric 上,两个 extension implementation 都会检查
      Build.FINGERPRINT.lowercase() == "robolectric"
      、发出
      Log.w
      警告,并且仍然安装验证器——但 Robolectric 无法忠实驱动无障碍服务,因此任何通过结果都不确定(b/332778271)。应在真实设备上运行无障碍检查,以获得可信结果。
  • 9. 将快速的逻辑、重组和状态测试放在 host 源代码集中。 适合在 Robolectric 上运行的示例包括:
    • StateRestorationTester.emulateSavedInstanceStateRestore()
      流程。
    • 纯状态变化验证(
      assertTextEquals
      、
      assertIsOn
      )。
    • 不依赖速度驱动物理计算的 LazyList finder/滚动测试。
    • 由
      mainClock.advanceTimeBy(durationMs)
      驱动且不需要栅格化的动画快照。

Patterns

模式

Pattern: WRONG vs RIGHT — screenshot test on host

模式:错误与正确——在 host 上运行截图测试

kotlin
// WRONG — placed in src/test/ (Robolectric)
@RunWith(AndroidJUnit4::class)
@Config(minSdk = 23)
class ButtonScreenshotTest {
    @Test
    fun pressed() = runComposeUiTest {
        setContent { Button(onClick = {}) { Text("OK") } }
        onNode(hasText("OK")).performTouchInput { down(center) }
        onNode(hasText("OK")).captureToImage().assertAgainstGolden("pressed")
    }
}
// WRONG because: Robolectric has no real Surface, so captureToImage() returns black/empty
// pixels and the ripple from Modifier.indication never draws (RenderThread is not driven).
// The test will produce a false-positive pass or a meaningless golden file.
kotlin
// RIGHT — placed in src/androidTest/ (device)
@RunWith(AndroidJUnit4::class)
class ButtonScreenshotTest {
    @get:Rule val rule = createComposeRule()

    @Test
    fun pressed() {
        rule.setContent { Button(onClick = {}) { Text("OK") } }
        rule.mainClock.autoAdvance = false
        rule.onNode(hasText("OK")).performTouchInput { down(center) }
        rule.mainClock.advanceTimeByFrame()
        rule.waitForIdle()
        rule.mainClock.advanceTimeBy(milliseconds = 200)
        Thread.sleep(300)                          // legitimate — RenderThread for ripples
        rule.onNode(hasText("OK")).captureToImage().assertAgainstGolden("pressed")
    }
}
kotlin
// WRONG — placed in src/test/ (Robolectric)
@RunWith(AndroidJUnit4::class)
@Config(minSdk = 23)
class ButtonScreenshotTest {
    @Test
    fun pressed() = runComposeUiTest {
        setContent { Button(onClick = {}) { Text("OK") } }
        onNode(hasText("OK")).performTouchInput { down(center) }
        onNode(hasText("OK")).captureToImage().assertAgainstGolden("pressed")
    }
}
// WRONG because: Robolectric has no real Surface, so captureToImage() returns black/empty
// pixels and the ripple from Modifier.indication never draws (RenderThread is not driven).
// The test will produce a false-positive pass or a meaningless golden file.
kotlin
// RIGHT — placed in src/androidTest/ (device)
@RunWith(AndroidJUnit4::class)
class ButtonScreenshotTest {
    @get:Rule val rule = createComposeRule()

    @Test
    fun pressed() {
        rule.setContent { Button(onClick = {}) { Text("OK") } }
        rule.mainClock.autoAdvance = false
        rule.onNode(hasText("OK")).performTouchInput { down(center) }
        rule.mainClock.advanceTimeByFrame()
        rule.waitForIdle()
        rule.mainClock.advanceTimeBy(milliseconds = 200)
        Thread.sleep(300)                          // legitimate — RenderThread for ripples
        rule.onNode(hasText("OK")).captureToImage().assertAgainstGolden("pressed")
    }
}

Pattern: WRONG vs RIGHT —
Thread.sleep
in a host animation test

模式:错误与正确——host 动画测试中的
Thread.sleep

kotlin
// WRONG — host test
@Test
fun fadeIn() = runComposeUiTest {
    val target = mutableStateOf(0f)
    setContent { Box(Modifier.alpha(animateFloatAsState(target.value).value)) }
    target.value = 1f
    Thread.sleep(500)                                // smell
    onNode(isRoot()).captureToImage()                // also broken on host
}
// WRONG because: Thread.sleep desyncs from MainTestClock. The test clock has not advanced,
// the recomposer has not run withFrameNanos, and the animation made zero observable progress.
kotlin
// RIGHT — host test (recomposition only — no pixel capture)
@Test
fun fadeIn() = runComposeUiTest {
    mainClock.autoAdvance = false
    val target = mutableStateOf(0f)
    setContent { Box(Modifier.alpha(animateFloatAsState(target.value).value).testTag("box")) }
    runOnUiThread { target.value = 1f }
    mainClock.advanceTimeByFrame()                   // kick off
    mainClock.advanceTimeBy(durationMillis = 500)    // step forward by test clock
    onNodeWithTag("box").assertIsDisplayed()
}
For pixel verification of the fade, move the test to the device source set and use
captureToImage()
.
kotlin
// WRONG — host test
@Test
fun fadeIn() = runComposeUiTest {
    val target = mutableStateOf(0f)
    setContent { Box(Modifier.alpha(animateFloatAsState(target.value).value)) }
    target.value = 1f
    Thread.sleep(500)                                // smell
    onNode(isRoot()).captureToImage()                // also broken on host
}
// WRONG because: Thread.sleep desyncs from MainTestClock. The test clock has not advanced,
// the recomposer has not run withFrameNanos, and the animation made zero observable progress.
kotlin
// RIGHT — host test (recomposition only — no pixel capture)
@Test
fun fadeIn() = runComposeUiTest {
    mainClock.autoAdvance = false
    val target = mutableStateOf(0f)
    setContent { Box(Modifier.alpha(animateFloatAsState(target.value).value).testTag("box")) }
    runOnUiThread { target.value = 1f }
    mainClock.advanceTimeByFrame()                   // kick off
    mainClock.advanceTimeBy(durationMillis = 500)    // step forward by test clock
    onNodeWithTag("box").assertIsDisplayed()
}
如果需要验证淡出动画的像素效果,请将测试移至 device 源代码集并使用
captureToImage()
。

Pattern: WRONG vs RIGHT — accessibility checks on host

模式:错误与正确——在 host 上执行无障碍检查

kotlin
// WRONG — host
@Test
fun submitIsLabelled() = runComposeUiTest {
    enableAccessibilityChecks()                      // logs warning, runs no checks
    setContent { Submit() }
    onNodeWithTag("submit").performClick()
}
// WRONG because: both ui-test-accessibility and ui-test-junit4-accessibility detect
// Build.FINGERPRINT.lowercase() == "robolectric", emit a Log.w, AND still install the
// validator — but Robolectric does not faithfully drive accessibility services, so the
// result is inconclusive (b/332778271). Run accessibility checks on a real device.
kotlin
// RIGHT — device
@RunWith(AndroidJUnit4::class)
class SubmitA11yTest {
    @get:Rule val rule = createAndroidComposeRule<MainActivity>()

    @Test fun submitIsLabelled() {
        rule.enableAccessibilityChecks()
        rule.setContent { Submit() }
        rule.onNodeWithTag("submit").performClick()  // accessibility checks run automatically
    }
}
kotlin
// WRONG — host
@Test
fun submitIsLabelled() = runComposeUiTest {
    enableAccessibilityChecks()                      // logs warning, runs no checks
    setContent { Submit() }
    onNodeWithTag("submit").performClick()
}
// WRONG because: both ui-test-accessibility and ui-test-junit4-accessibility detect
// Build.FINGERPRINT.lowercase() == "robolectric", emit a Log.w, AND still install the
// validator — but Robolectric does not faithfully drive accessibility services, so the
// result is inconclusive (b/332778271). Run accessibility checks on a real device.
kotlin
// RIGHT — device
@RunWith(AndroidJUnit4::class)
class SubmitA11yTest {
    @get:Rule val rule = createAndroidComposeRule<MainActivity>()

    @Test fun submitIsLabelled() {
        rule.enableAccessibilityChecks()
        rule.setContent { Submit() }
        rule.onNodeWithTag("submit").performClick()  // accessibility checks run automatically
    }
}

Pattern: shared body, two source sets

模式:共享代码块与两个源代码集

The same
runComposeUiTest { ... }
body can compile in both source sets when the test only uses the common API. Place the body in
androidCommonTest/
and create two thin wrappers — one in
androidHostTest/
(with
@RunWith(AndroidJUnit4::class) @Config(minSdk = 23)
), one in
androidDeviceTest/
(no
@Config
). This is how androidx's own ui-test module exercises both flavors without code duplication. For an app module without KMP source sets, prefer keeping the body inline in whichever flavor is appropriate.
当测试仅使用通用 API 时,相同的
runComposeUiTest { ... }
代码块可以在两个源代码集中编译。将代码块放在
androidCommonTest/
,并创建两个轻量包装器——一个位于
androidHostTest/
,带有
@RunWith(AndroidJUnit4::class) @Config(minSdk = 23)
;另一个位于
androidDeviceTest/
,不添加
@Config
。androidx 自身的 ui-test module 正是通过这种方式测试两种环境,而无需复制代码。对于不包含 KMP 源代码集的 app module,应优先将代码块直接放在合适的测试环境中。

Mandatory rules

强制规则

  • MUST NOT put screenshot /
    captureToImage
    / ripple /
    Modifier.indication
    -dependent tests in the host source set. The RenderThread is not driven; the test is meaningless even when it appears to pass.
  • MUST NOT rely on
    enableAccessibilityChecks(...)
    results from a host test. Both extensions log a warning under
    Build.FINGERPRINT.lowercase() == "robolectric"
    and still install the validator, but Robolectric does not faithfully drive accessibility services so the result is inconclusive — run accessibility checks on a real device API 34+.
  • MUST NOT use
    Thread.sleep
    in a host test under any circumstance. The screenshot exception does not apply (host has no RenderThread).
  • MUST NOT use
    Thread.sleep
    in a device test except when waiting on the RenderThread for ripple/screenshot golden capture. Skydoves hot take #7:
    Thread.sleep
    is a smell. Anywhere else, replace it with
    mainClock.advanceTimeBy(durationMs)
    (test clock) or
    rule.waitUntil(timeoutMillis) { ... }
    (wall clock) — see
    ../../synchronization/synchronizing-with-idle/SKILL.md
    .
  • MUST annotate Robolectric host tests with
    @Config(minSdk = 23)
    or higher. Lower SDK levels are not supported by androidx's host test infrastructure (
    internal const val RobolectricMinSdk = 23
    ).
  • MUST annotate gesture-detection or animation host tests to step the clock manually with
    mainClock.advanceTimeBy(...)
    . Robolectric does not advance the test clock from real-time signals.
  • MUST set
    testOptions { unitTests.isIncludeAndroidResources = true }
    in the module's
    android { }
    block so Robolectric can read merged resources during host Compose tests.
  • PREFERRED: start with a host test for fast feedback. Move to a device test only when capability requires it (RenderThread, accessibility, real input timing).
  • PREFERRED: when a test must work in both flavors, factor the body into
    androidCommonTest/
    (KMP) or a helper function the two flavors call.
  • 禁止将截图、
    captureToImage
    、涟漪或依赖
    Modifier.indication
    的测试放在 host 源代码集中。Host 不会驱动 RenderThread;即使测试看似通过,结果也没有意义。
  • 禁止依赖 host test 中的
    enableAccessibilityChecks(...)
    结果。两个 extension 都会在
    Build.FINGERPRINT.lowercase() == "robolectric"
    时记录警告,并且仍然安装验证器,但 Robolectric 无法忠实驱动无障碍服务,因此结果不确定——应在 API 34+ 的真实设备上运行无障碍检查。
  • 禁止在任何 host test 中使用
    Thread.sleep
    。截图例外不适用,因为 host 没有 RenderThread。
  • 禁止在 device test 中使用
    Thread.sleep
    ,唯一例外是等待 RenderThread 完成涟漪渲染或截图 golden capture。Skydoves 的尖锐观点 #7:
    Thread.sleep
    是不良信号。其他任何场景都应使用
    mainClock.advanceTimeBy(durationMs)
    (测试时钟)或
    rule.waitUntil(timeoutMillis) { ... }
    (wall clock)替代它——请参阅
    ../../synchronization/synchronizing-with-idle/SKILL.md
    。
  • 必须为 Robolectric host test 添加
    @Config(minSdk = 23)
    或更高版本的注解。androidx 的 host test 基础设施不支持更低的 SDK(
    internal const val RobolectricMinSdk = 23
    )。
  • 必须在手势检测或动画 host test 中手动推进时钟,调用
    mainClock.advanceTimeBy(...)
    。Robolectric 不会根据实时信号推进测试时钟。
  • 必须在模块的
    android { }
    块中设置
    testOptions { unitTests.isIncludeAndroidResources = true }
    ,使 Robolectric 能在 host Compose test 中读取合并后的资源。
  • 优先从 host test 开始,以获得快速反馈。只有当能力存在要求时,才移至 device test(RenderThread、无障碍、真实输入计时)。
  • 优先当测试必须同时适用于两种环境时,将代码块提取到
    androidCommonTest/
    (KMP),或提取为由两种环境调用的 helper function。

Verification

验证

  • ./gradlew :<module>:testDebugUnitTest
    runs and passes for all host tests;
    ./gradlew :<module>:connectedDebugAndroidTest
    runs and passes for all device tests.
  • No
    Thread.sleep
    appears in any host test (
    grep -r "Thread.sleep" src/test src/androidHostTest
    ).
  • No
    captureToImage
    , no
    enableAccessibilityChecks
    , and no test that depends on
    Modifier.indication
    ripples appears in the host source set.
  • Every
    Thread.sleep
    in the device source set has a comment explaining the RenderThread / screenshot rationale.
  • Robolectric host test classes carry
    @RunWith(AndroidJUnit4::class)
    (or
    @RunWith(RobolectricTestRunner::class)
    ) AND
    @Config(minSdk = 23)
    (or higher).
  • Animation/gesture host tests set
    mainClock.autoAdvance = false
    and call
    mainClock.advanceTimeBy(durationMs)
    explicitly.
  • ./gradlew :<module>:testDebugUnitTest
    能够运行并通过所有 host test;
    ./gradlew :<module>:connectedDebugAndroidTest
    能够运行并通过所有 device test。
  • 任何 host test 中都不存在
    Thread.sleep
    (
    grep -r "Thread.sleep" src/test src/androidHostTest
    )。
  • Host 源代码集中不存在
    captureToImage
    、
    enableAccessibilityChecks
    ,也不存在依赖
    Modifier.indication
    涟漪的测试。
  • Device 源代码集中的每个
    Thread.sleep
    都有注释说明其与 RenderThread 或截图相关的原因。
  • Robolectric host test 类带有
    @RunWith(AndroidJUnit4::class)
    (或
    @RunWith(RobolectricTestRunner::class)
    )以及
    @Config(minSdk = 23)
    (或更高版本)。
  • 动画或手势 host test 设置
    mainClock.autoAdvance = false
    ,并显式调用
    mainClock.advanceTimeBy(durationMs)
    。

References

参考资料

  • Compose testing overview (Android Developers): https://developer.android.com/develop/ui/compose/testing
  • Robolectric — Compose support: http://robolectric.org/
  • Compose UI release notes: https://developer.android.com/jetpack/androidx/releases/compose-ui
  • Testing animations (Android Developers): https://developer.android.com/develop/ui/compose/animation/testing
  • compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/RobolectricComposeTest.kt
    — canonical host class skeleton,
    @RunWith(AndroidJUnit4::class) @Config(minSdk = RobolectricMinSdk)
    , gesture-detector clock comment,
    IdlingPolicies
    setup/teardown.
  • compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/Constants.kt
    —
    internal const val RobolectricMinSdk = 23
    .
  • compose/material3/material3/src/androidDeviceTest/kotlin/androidx/compose/material3/ToggleButtonScreenshotTest.kt:115-123
    — the canonical legitimate
    Thread.sleep(300)
    waiting on the RenderThread for ripple completion before
    assertAgainstGolden
    .
  • compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/RobolectricIdlingStrategy.android.kt
    — Robolectric idling strategy that drives the host idle loop.
  • compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeIdlingResource.android.kt
    — the recomposer + snapshot + frame-clock aggregator (caps at 100 frames/call); does NOT include the RenderThread, which is why ripple tests need
    Thread.sleep
    .
  • Compose 测试概览(Android Developers):https://developer.android.com/develop/ui/compose/testing
  • Robolectric——Compose 支持:http://robolectric.org/
  • Compose UI 发布说明:https://developer.android.com/jetpack/androidx/releases/compose-ui
  • 测试动画(Android Developers):https://developer.android.com/develop/ui/compose/animation/testing
  • compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/RobolectricComposeTest.kt
    ——标准的 host 类骨架,包含
    @RunWith(AndroidJUnit4::class) @Config(minSdk = RobolectricMinSdk)
    、手势检测器时钟说明以及
    IdlingPolicies
    的 setup/teardown。
  • compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/Constants.kt
    ——
    internal const val RobolectricMinSdk = 23
    。
  • compose/material3/material3/src/androidDeviceTest/kotlin/androidx/compose/material3/ToggleButtonScreenshotTest.kt:115-123
    ——在
    assertAgainstGolden
    前等待 RenderThread 完成涟漪渲染的合法
    Thread.sleep(300)
    标准示例。
  • compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/RobolectricIdlingStrategy.android.kt
    ——驱动 host 空闲循环的 Robolectric idle strategy。
  • compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeIdlingResource.android.kt
    ——recomposer、snapshot 与 frame-clock 的聚合器(每次调用最多 100 帧);不包含 RenderThread,因此涟漪测试需要使用
    Thread.sleep
    。