setting-up-host-vs-device-tests
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSetting 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 block compiles in both — only the underlying and differ. This skill encodes which flavor each test should live in, the Robolectric class skeleton, and the one legitimate exception (screenshot tests waiting on the RenderThread).
runComposeUiTest { setContent { … } }LooperChoreographerThread.sleepCompose 测试无需修改即可在 Robolectric(JVM、快速、无需模拟器)或真实/虚拟设备(完整 Android 技术栈、RenderThread、无障碍)上运行。同一个 代码块在两者中均可编译——只有底层的 和 不同。此 skill 规定了每类测试应使用的测试环境、Robolectric 类骨架,以及唯一允许使用 的例外情况(截图测试等待 RenderThread)。
runComposeUiTest { setContent { … } }LooperChoreographerThread.sleepWhen 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 warnings from
Build.FINGERPRINT == "robolectric".enableAccessibilityChecks(...) - A screenshot test produces a black/empty PNG on the host runner.
- A ripple/test renders no ripple on Robolectric and the user is debugging why.
pressInteraction - The user wrote to "wait for an animation" and is asking why it is flaky.
Thread.sleep(1000) - The user mentions /
androidDeviceTestsource sets (used inandroidHostTestitself).androidx
- 用户刚开始编写 Compose UI 测试,并询问“test/ 还是 androidTest/?”。
- 测试在本地模拟器上通过,却在 CI 的 Robolectric runner 上失败(或反之)。
- 用户报告 出现
enableAccessibilityChecks(...)警告。Build.FINGERPRINT == "robolectric" - 截图测试在 host runner 上生成黑色或空白 PNG。
- ripple/测试在 Robolectric 上没有渲染任何涟漪,用户正在排查原因。
pressInteraction - 用户编写了 来“等待动画完成”,并询问为什么测试容易出现不稳定。
Thread.sleep(1000) - 用户提到 或
androidDeviceTest源代码集(androidx 自身使用的划分方式)。androidHostTest
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 and
createComposeRule()— seerunComposeUiTest { }../choosing-test-rule-vs-runtest/SKILL.md - The test runs in the right flavor but is flaky on idle/animation — see and
../../synchronization/synchronizing-with-idle/SKILL.md.../../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, andui-test-junit4on the correct configurations for the chosen flavor — seeui-test-manifest../configuring-test-dependencies/SKILL.md - For host tests: on
org.robolectric:robolectric,testImplementationin the Android block.testOptions { unitTests.isIncludeAndroidResources = true } - For device tests: a configured emulator or physical device, (or a Hilt subclass) as the
androidx.test.runner.AndroidJUnitRunner.testInstrumentationRunner - Working knowledge of semantics — see the synchronization skill set.
MainTestClock
- 对于所选测试环境,应在正确的 configuration 中配置 、
androidx.compose.ui:ui-test和ui-test-junit4——请参阅ui-test-manifest。./configuring-test-dependencies/SKILL.md - 对于 host test:在 中添加
testImplementation,并在 Android 的org.robolectric:robolectric块中设置android { }。testOptions { unitTests.isIncludeAndroidResources = true } - 对于 device test:准备已配置的模拟器或物理设备,并将 (或 Hilt 子类)设置为
androidx.test.runner.AndroidJUnitRunner。testInstrumentationRunner - 熟悉 的语义——请参阅同步相关的 skill 集合。
MainTestClock
Workflow
工作流
-
1. Decide the flavor by capability, not by speed. The matrix:
Capability Host (Robolectric, )src/test/Device (instrumentation, )src/androidTest/Recomposition + state changes Works Works Layout + measurement Works Works Touch input via performTouchInputWorks (synthetic events) Works (real input pipeline) ripplesModifier.indicationNo (RenderThread not driven) Works Screenshot capture ( )captureToImageNo (no real surface) Works enableAccessibilityChecks(...)Inconclusive — logsComposeUiTestExt.android.kt:50-53and still installs the validator, but Robolectric does not faithfully drive accessibility services (b/332778271). Treat passing as inconclusive.Log.w("ComposeUiTest", "Accessibility checks are currently not supported by Robolectric")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)onResumeApproximated Real Min SDK 23 ( frominternal const val RobolectricMinSdk = 23)compose/ui/ui-test/src/androidHostTest/.../Constants.ktThe module's minSdkSpeed (rough order) Seconds Tens of seconds + emulator boot CI footprint JVM only Emulator service or Firebase Test Lab Choose host for logic/recomposition/finder coverage. Choose device for anything that touches the RenderThread, real animations involving, screenshot golden tests, or accessibility validation.Modifier.indication -
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.ktIn a typical app module without KMP source sets, the equivalent is(host) andsrc/test/(device). The samesrc/androidTest/body compiles unchanged in both — only the Looper/Choreographer differs at runtime.runComposeUiTest { setContent { … } } -
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::classAndroidJUnit4ClassRunner@RunWith(RobolectricTestRunner::class)- 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. Composefor 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
mainClock.advanceTimeBy(...)source quotes this directly: gesture detectors require manualRobolectricComposeTest.ktbecause they detect events through clock changes. Same applies to anymainClock.advanceTimeBy(...)driven by the recomposer's frame clock — seeanimateFloatAsState.../../synchronization/testing-animations-deterministically/SKILL.md -
6. Identify the one legitimateuse case: screenshot tests waiting on the RenderThread. Compose's
Thread.sleepaggregates the recomposer, snapshot, and frame-clock awaiters, but the RenderThread is outside that aggregation. Ripple animations (IdlingResource) and any draw-time animation owned by the platform render pipeline cannot be waited on throughModifier.indicationormainClock.advanceTimeBy. FromwaitForIdle: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, is a smell — it desyncs from and produces flakes that wear the developer down. Use (test clock) for animations or (wall clock) for external state.
Thread.sleepMainTestClockmainClock.advanceTimeBy(durationMs)rule.waitUntil(timeoutMillis = …) { … }-
7. Enforce: NOin host tests. Host tests cannot drive the RenderThread anyway, so the screenshot exception does not apply. Replace every
Thread.sleepin a host test withThread.sleep(N)(animation case) ormainClock.advanceTimeBy(N)(external state).rule.waitUntil { … } -
8. Place screenshot, ripple, and accessibility tests in the device source set. The host runner cannot satisfy them. Specifically:
- Screenshots: requires a real
captureToImage(). Host returns no pixel data.Surface - Ripples: draws on the RenderThread — no observable state on host.
Modifier.indication - Accessibility: is
enableAccessibilityChecks(...). On Robolectric, both extension implementations check@RequiresApi(34), emit aBuild.FINGERPRINT.lowercase() == "robolectric"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.Log.w
- Screenshots:
-
9. Place fast logic/recomposition/state tests in the host source set. Examples that thrive on Robolectric:
- flows.
StateRestorationTester.emulateSavedInstanceStateRestore() - Pure state-change verification (,
assertTextEquals).assertIsOn - LazyList finder/scroll tests that don't depend on velocity-driven physics.
- driven animation snapshots that don't need rasterization.
mainClock.advanceTimeBy(durationMs)
-
1. 根据能力选择测试环境,而不是根据速度选择。 参考下表:
能力 Host(Robolectric, )src/test/Device(instrumentation, )src/androidTest/重组 + 状态变化 支持 支持 布局 + 测量 支持 支持 通过 进行触摸输入performTouchInput支持(合成事件) 支持(真实输入管线) 涟漪Modifier.indication不支持(不会驱动 RenderThread) 支持 截图捕获( )captureToImage不支持(没有真实 Surface) 支持 enableAccessibilityChecks(...)结论不确定—— 会记录ComposeUiTestExt.android.kt:50-53并仍然安装验证器,但 Robolectric 无法忠实驱动无障碍服务(b/332778271)。应将测试通过视为不确定结果。Log.w("ComposeUiTest", "Accessibility checks are currently not supported by Robolectric")支持( )@RequiresApi(34)需要实时时钟变化的手势检测器(双击、长按计时) 仅在手动调用 时支持mainClock.advanceTimeBy(...)自动支持 Activity 生命周期(真实的 /onPause)onResume近似模拟 真实执行 最低 SDK 23(来自 的compose/ui/ui-test/src/androidHostTest/.../Constants.kt)internal const val RobolectricMinSdk = 23模块的 minSdk速度(大致顺序) 数秒 数十秒,加上模拟器启动时间 CI 资源占用 仅需 JVM 需要模拟器服务或 Firebase Test Lab 对于逻辑、重组和 finder 覆盖,选择 host test。对于任何涉及 RenderThread、真实动画中的、截图 golden test 或无障碍验证的测试,选择 device test。Modifier.indication -
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 中,等价目录为(host)和src/test/(device)。相同的src/androidTest/代码块在两者中均可原样编译——只有运行时使用的 Looper/Choreographer 不同。runComposeUiTest { setContent { … } } -
3. 配置 host test 类骨架。 从复制 androidx 的标准模式:
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::classAndroidJUnit4ClassRunner@RunWith(RobolectricTestRunner::class)- 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 的。 在 Robolectric 中,手势检测器(双击、长按)依赖测试时钟推进——它们不会收到真实的 wall-clock ticks。
mainClock.advanceTimeBy(...)源码直接说明:手势检测器要求手动调用RobolectricComposeTest.kt,因为它们通过时钟变化来检测事件。由 recomposer 的 frame clock 驱动的mainClock.advanceTimeBy(...)等场景同理——请参阅animateFloatAsState。../../synchronization/testing-animations-deterministically/SKILL.md -
6. 找出唯一合法的使用场景:截图测试等待 RenderThread。 Compose 的
Thread.sleep会聚合 recomposer、snapshot 和 frame-clock awaiter,但 RenderThread 不在该聚合范围内。涟漪动画(IdlingResource)以及任何由平台渲染管线负责的绘制时动画,都无法通过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")仅此场景可以使用。其他任何地方使用 都是不良信号——它会与 失去同步,并产生会不断消耗开发者精力的不稳定测试。对于动画,应使用 (测试时钟);对于外部状态,应使用 (wall clock)。
Thread.sleepMainTestClockmainClock.advanceTimeBy(durationMs)rule.waitUntil(timeoutMillis = …) { … }-
7. 强制规定:host test 中禁止使用。 Host test 本来就无法驱动 RenderThread,因此截图例外不适用。将 host test 中的每个
Thread.sleep替换为Thread.sleep(N)(动画场景)或mainClock.advanceTimeBy(N)(外部状态场景)。rule.waitUntil { … } -
8. 将截图、涟漪和无障碍测试放在 device 源代码集中。 Host runner 无法满足这些测试需求。具体而言:
- 截图:需要真实的
captureToImage()。Host 不会返回任何像素数据。Surface - 涟漪:在 RenderThread 上绘制——host 上没有可观察状态。
Modifier.indication - 无障碍:带有
enableAccessibilityChecks(...)。在 Robolectric 上,两个 extension implementation 都会检查@RequiresApi(34)、发出Build.FINGERPRINT.lowercase() == "robolectric"警告,并且仍然安装验证器——但 Robolectric 无法忠实驱动无障碍服务,因此任何通过结果都不确定(b/332778271)。应在真实设备上运行无障碍检查,以获得可信结果。Log.w
- 截图:
-
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
Thread.sleep模式:错误与正确——host 动画测试中的 Thread.sleep
Thread.sleepkotlin
// 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 body can compile in both source sets when the test only uses the common API. Place the body in and create two thin wrappers — one in (with ), one in (no ). 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.
runComposeUiTest { ... }androidCommonTest/androidHostTest/@RunWith(AndroidJUnit4::class) @Config(minSdk = 23)androidDeviceTest/@Config当测试仅使用通用 API 时,相同的 代码块可以在两个源代码集中编译。将代码块放在 ,并创建两个轻量包装器——一个位于 ,带有 ;另一个位于 ,不添加 。androidx 自身的 ui-test module 正是通过这种方式测试两种环境,而无需复制代码。对于不包含 KMP 源代码集的 app module,应优先将代码块直接放在合适的测试环境中。
runComposeUiTest { ... }androidCommonTest/androidHostTest/@RunWith(AndroidJUnit4::class) @Config(minSdk = 23)androidDeviceTest/@ConfigMandatory rules
强制规则
- MUST NOT put screenshot / / ripple /
captureToImage-dependent tests in the host source set. The RenderThread is not driven; the test is meaningless even when it appears to pass.Modifier.indication - MUST NOT rely on results from a host test. Both extensions log a warning under
enableAccessibilityChecks(...)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+.Build.FINGERPRINT.lowercase() == "robolectric" - MUST NOT use in a host test under any circumstance. The screenshot exception does not apply (host has no RenderThread).
Thread.sleep - MUST NOT use in a device test except when waiting on the RenderThread for ripple/screenshot golden capture. Skydoves hot take #7:
Thread.sleepis a smell. Anywhere else, replace it withThread.sleep(test clock) ormainClock.advanceTimeBy(durationMs)(wall clock) — seerule.waitUntil(timeoutMillis) { ... }.../../synchronization/synchronizing-with-idle/SKILL.md - MUST annotate Robolectric host tests with or higher. Lower SDK levels are not supported by androidx's host test infrastructure (
@Config(minSdk = 23)).internal const val RobolectricMinSdk = 23 - MUST annotate gesture-detection or animation host tests to step the clock manually with . Robolectric does not advance the test clock from real-time signals.
mainClock.advanceTimeBy(...) - MUST set in the module's
testOptions { unitTests.isIncludeAndroidResources = true }block so Robolectric can read merged resources during host Compose tests.android { } - 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 (KMP) or a helper function the two flavors call.
androidCommonTest/
- 禁止将截图、、涟漪或依赖
captureToImage的测试放在 host 源代码集中。Host 不会驱动 RenderThread;即使测试看似通过,结果也没有意义。Modifier.indication - 禁止依赖 host test 中的 结果。两个 extension 都会在
enableAccessibilityChecks(...)时记录警告,并且仍然安装验证器,但 Robolectric 无法忠实驱动无障碍服务,因此结果不确定——应在 API 34+ 的真实设备上运行无障碍检查。Build.FINGERPRINT.lowercase() == "robolectric" - 禁止在任何 host test 中使用 。截图例外不适用,因为 host 没有 RenderThread。
Thread.sleep - 禁止在 device test 中使用 ,唯一例外是等待 RenderThread 完成涟漪渲染或截图 golden capture。Skydoves 的尖锐观点 #7:
Thread.sleep是不良信号。其他任何场景都应使用Thread.sleep(测试时钟)或mainClock.advanceTimeBy(durationMs)(wall clock)替代它——请参阅rule.waitUntil(timeoutMillis) { ... }。../../synchronization/synchronizing-with-idle/SKILL.md - 必须为 Robolectric host test 添加 或更高版本的注解。androidx 的 host test 基础设施不支持更低的 SDK(
@Config(minSdk = 23))。internal const val RobolectricMinSdk = 23 - 必须在手势检测或动画 host test 中手动推进时钟,调用 。Robolectric 不会根据实时信号推进测试时钟。
mainClock.advanceTimeBy(...) - 必须在模块的 块中设置
android { },使 Robolectric 能在 host Compose test 中读取合并后的资源。testOptions { unitTests.isIncludeAndroidResources = true } - 优先从 host test 开始,以获得快速反馈。只有当能力存在要求时,才移至 device test(RenderThread、无障碍、真实输入计时)。
- 优先当测试必须同时适用于两种环境时,将代码块提取到 (KMP),或提取为由两种环境调用的 helper function。
androidCommonTest/
Verification
验证
- runs and passes for all host tests;
./gradlew :<module>:testDebugUnitTestruns and passes for all device tests../gradlew :<module>:connectedDebugAndroidTest - No appears in any host test (
Thread.sleep).grep -r "Thread.sleep" src/test src/androidHostTest - No , no
captureToImage, and no test that depends onenableAccessibilityChecksripples appears in the host source set.Modifier.indication - Every in the device source set has a comment explaining the RenderThread / screenshot rationale.
Thread.sleep - Robolectric host test classes carry (or
@RunWith(AndroidJUnit4::class)) AND@RunWith(RobolectricTestRunner::class)(or higher).@Config(minSdk = 23) - Animation/gesture host tests set and call
mainClock.autoAdvance = falseexplicitly.mainClock.advanceTimeBy(durationMs)
- 能够运行并通过所有 host test;
./gradlew :<module>:testDebugUnitTest能够运行并通过所有 device test。./gradlew :<module>:connectedDebugAndroidTest - 任何 host test 中都不存在 (
Thread.sleep)。grep -r "Thread.sleep" src/test src/androidHostTest - Host 源代码集中不存在 、
captureToImage,也不存在依赖enableAccessibilityChecks涟漪的测试。Modifier.indication - Device 源代码集中的每个 都有注释说明其与 RenderThread 或截图相关的原因。
Thread.sleep - 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
- — canonical host class skeleton,
compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/RobolectricComposeTest.kt, gesture-detector clock comment,@RunWith(AndroidJUnit4::class) @Config(minSdk = RobolectricMinSdk)setup/teardown.IdlingPolicies - —
compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/Constants.kt.internal const val RobolectricMinSdk = 23 - — the canonical legitimate
compose/material3/material3/src/androidDeviceTest/kotlin/androidx/compose/material3/ToggleButtonScreenshotTest.kt:115-123waiting on the RenderThread for ripple completion beforeThread.sleep(300).assertAgainstGolden - — Robolectric idling strategy that drives the host idle loop.
compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/RobolectricIdlingStrategy.android.kt - — the recomposer + snapshot + frame-clock aggregator (caps at 100 frames/call); does NOT include the RenderThread, which is why ripple tests need
compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeIdlingResource.android.kt.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
- ——标准的 host 类骨架,包含
compose/ui/ui-test/src/androidHostTest/kotlin/androidx/compose/ui/test/RobolectricComposeTest.kt、手势检测器时钟说明以及@RunWith(AndroidJUnit4::class) @Config(minSdk = RobolectricMinSdk)的 setup/teardown。IdlingPolicies - ——
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前等待 RenderThread 完成涟漪渲染的合法assertAgainstGolden标准示例。Thread.sleep(300) - ——驱动 host 空闲循环的 Robolectric idle strategy。
compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/RobolectricIdlingStrategy.android.kt - ——recomposer、snapshot 与 frame-clock 的聚合器(每次调用最多 100 帧);不包含 RenderThread,因此涟漪测试需要使用
compose/ui/ui-test/src/androidMain/kotlin/androidx/compose/ui/test/ComposeIdlingResource.android.kt。Thread.sleep