Setting Up Host Vs Device Tests

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).

When to use this 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).

When NOT to use this 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.

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.

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 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)	Approximated	Real
  Min SDK	23 (internal const val RobolectricMinSdk = 23 from compose/ui/ui-test/src/androidHostTest/.../Constants.kt)	The module's minSdk
  Speed (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 Modifier.indication, screenshot golden tests, or accessibility validation.

• 2. Place files in the matching source set. The androidx convention is:

  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:

@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.

@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:

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.