Using Robolectric Correctly

Patterns

Pattern: WRONG — RobolectricTestRunner for a test that should also run on device

// WRONG
@RunWith(RobolectricTestRunner::class)
@Config(minSdk = 23)
class LoginViewModelTest {
    @Test fun loginFlow() { /* ... */ }
}
// WRONG because: this class CAN run unchanged on a device too — there are no
// Robolectric-only APIs in the body. Pinning to RobolectricTestRunner locks the
// test to the JVM and forfeits the sharedTest pattern. The same class moved to
// src/androidTest/ (or androidDeviceTest) would not run.

// RIGHT
@RunWith(AndroidJUnit4::class)
@Config(minSdk = RobolectricMinSdk)                      // pin via single source of truth
class LoginViewModelTest {
    @Test fun loginFlow() { /* ... */ }
}

Pattern: WRONG — assert before draining the looper

// WRONG
@RunWith(AndroidJUnit4::class)
class HandlerTest {
    @Test fun postedRuns() {
        var fired = false
        Handler(Looper.getMainLooper()).post { fired = true }
        assertTrue(fired)                                 // FAIL: runnable is queued, not run
    }
}
// WRONG because: Robolectric's default LooperMode.PAUSED does not auto-run posted
// runnables. The post is queued; assertTrue runs before the queue is drained.

// RIGHT
@RunWith(AndroidJUnit4::class)
class HandlerTest {
    @Test fun postedRuns() {
        var fired = false
        Handler(Looper.getMainLooper()).post { fired = true }
        shadowOf(Looper.getMainLooper()).idle()           // drain queue
        assertTrue(fired)
    }
}

Pattern: WRONG — missing includeAndroidResources

// WRONG
android {
    testOptions {
        unitTests { /* includeAndroidResources missing */ }
    }
}

Symptom: android.content.res.Resources$NotFoundException: String resource ID #0x7f0c0001 at test startup. The fix:

// RIGHT
android {
    testOptions {
        unitTests {
            includeAndroidResources = true                // Groovy
            // isIncludeAndroidResources = true           // Kotlin DSL
        }
    }
}

Pattern: WRONG — sharedTest srcDir sharing on AGP 7.2+

// WRONG
android {
    sourceSets {
        test       { java.srcDirs += 'src/sharedTest/java' }
        androidTest { java.srcDirs += 'src/sharedTest/java' }
    }
}
// WRONG because: AGP 7.2+ rejects sharing a single source directory across
// source sets (Robolectric issue #7432). Build fails with "Source directory
// already added to source set".

// RIGHT — AndroidX-style KMP source sets
sourceSets {
    androidCommonTest  { dependsOn(commonTest) }
    androidDeviceTest  { dependsOn(androidCommonTest) }
    androidHostTest    { dependsOn(androidCommonTest) }
}

Pattern: ParameterizedRobolectricTestRunner — when matrix is the point

// androidx/compose/ui/ui-test/.../ViewVisibilityRobolectricTest.kt (paraphrased)
@RunWith(ParameterizedRobolectricTestRunner::class)
@Config(minSdk = RobolectricMinSdk)
class ViewVisibilityRobolectricTest(private val visibility: Int) {
    companion object {
        @JvmStatic
        @Parameters(name = "visibility={0}")
        fun params() = listOf(View.VISIBLE, View.INVISIBLE, View.GONE)
    }
    @Test fun behaves() { /* uses `visibility` */ }
}

This is the one place to pin RobolectricTestRunner (its parameterized subclass) — there is no AndroidJUnit4 parameterized variant.

Pattern: production code branching on Robolectric — read with caution

// androidx/compose/ui/ui-test/.../RobolectricIdlingStrategy.android.kt
internal val HasRobolectricFingerprint
    get() = Build.FINGERPRINT.lowercase() == "robolectric"

This idiom is widespread inside androidx (Compose accessibility, idling, graphics layers). Library code under test SHOULD avoid copying it unless the branch is genuinely test-only — misdetection silently changes behavior.

Mandatory rules

• MUST import AndroidJUnit4 from androidx.test.ext.junit.runners. MUST NOT import from androidx.test.runner — that one is @Deprecated (docs/CORPUS.md §G.2).
• MUST prefer @RunWith(AndroidJUnit4::class) over @RunWith(RobolectricTestRunner::class). The latter only when the test uses Robolectric-specific APIs (e.g. shadowOf(Looper.getMainLooper()).idle()) directly, or needs ParameterizedRobolectricTestRunner.
• MUST set testOptions.unitTests.includeAndroidResources = true for any project whose unit tests touch R.* / Resources / layouts / themes.
• MUST drain the looper with shadowOf(Looper.getMainLooper()).idle() (or ShadowLooper.runUiThreadTasksIncludingDelayedTasks()) before asserting anything that depends on a Handler.post* callback. Default LooperMode.PAUSED does NOT auto-run.
• MUST pin a class-level @Config(minSdk = …) (or sdk = […]) — do not depend on the project's default SDK varying in CI.
• MUST NOT use the legacy srcDirs sharing pattern test.java.srcDirs += 'src/sharedTest/java' on AGP 7.2+. Migrate to androidHostTest + androidDeviceTest (KMP source sets) or a separate Gradle module.
• MUST NOT add Robolectric to a test class that has zero android.* imports. The class-load tax is 1-3 s for nothing.
• MUST NOT use Robolectric for screenshot tests, ripple animations, accessibility services, or RenderThread timing — use an emulator/device.
• PREFERRED: quote RobolectricMinSdk = 23 from androidx/compose/ui/ui-test/src/androidHostTest/.../Constants.kt as the single source of truth for the floor SDK in androidHostTest modules.
• PREFERRED: group related tests into the same class to amortize the per-class class-load tax. Avoid sprinkling @RunWith(RobolectricTestRunner::class) across many small classes.
• PREFERRED: single-SDK @Config(sdk = [33]) on the commit gate; multi-SDK matrices on the merge gate.

Verification

• No import of androidx.test.runner.AndroidJUnit4 (use androidx.test.ext.junit.runners.AndroidJUnit4). grep -rn 'androidx.test.runner.AndroidJUnit4' src/test src/androidTest returns empty.
• testOptions.unitTests.includeAndroidResources = true is set in the module's build.gradle(.kts).
• No @RunWith(RobolectricTestRunner::class) exists on a test class that does not actually use Robolectric-specific APIs.
• Every test that posts to a Handler / triggers Looper work calls shadowOf(Looper.getMainLooper()).idle() (or runUiThreadTasksIncludingDelayedTasks) before asserting.
• Every Robolectric test class declares @Config(minSdk = …) or @Config(sdk = […]).
• Source-set wiring uses androidHostTest + androidDeviceTest (or a shared module), not legacy srcDirs += sharedTest.
• No screenshot/ripple/accessibility-service test runs under Robolectric — those live in src/androidTest/ or androidDeviceTest.
• ./gradlew :module:test passes; ./gradlew :module:connectedDebugAndroidTest passes for any test in androidCommonTest.

References

• Robolectric — getting started: http://robolectric.org/getting-started/
• Robolectric — configuring: http://robolectric.org/configuring/
• Robolectric — sharedTest blog post: http://robolectric.org/blog/2021/10/06/sharedTest/
• Android Developers — Build local unit tests: https://developer.android.com/training/testing/local-tests
• Android Developers — Robolectric: https://developer.android.com/training/testing/local-tests/robolectric
• Robolectric GitHub issue #7432 — AGP 7.2 sharedTest breakage: https://github.com/robolectric/robolectric/issues/7432
• Research: tasks/research/R7-robolectric.md.
• docs/CORPUS.md §G.1 / §G.6 — Gradle coordinates and runner choice.
• androidx/compose/ui/ui-test/src/androidHostTest/.../Constants.kt — RobolectricMinSdk = 23 floor.
• androidx/compose/ui/ui-test/.../RobolectricComposeTest.kt — canonical @RunWith(AndroidJUnit4::class) @Config(minSdk = RobolectricMinSdk) cross-runtime test.
• androidx/compose/ui/ui-test/.../PrefetchNotHangingMainThreadTest.kt — @RunWith(RobolectricTestRunner::class) with explicit shadowOf(Looper.getMainLooper()).idle().
• androidx/compose/ui/ui-test/.../ViewVisibilityRobolectricTest.kt — ParameterizedRobolectricTestRunner example.
• androidx/compose/ui/ui-test/.../RobolectricIdlingStrategy.android.kt — Build.FINGERPRINT.lowercase() == "robolectric" detection idiom.
• androidx/compose/ui/ui/.../MediaQueryIntegrationTest.kt — ShadowPackageManager / ShadowInputManager in an @RunWith(AndroidJUnit4::class) test.
• Sibling: ../../coroutines/testing-coroutines-with-runtest/SKILL.md — runTest + MainDispatcherRule (independent of Robolectric).
• Sibling: ../../coroutines/testing-flows-with-turbine/SKILL.md — Flow assertions; Turbine works under Robolectric unchanged.
• Sibling: ../../runner/configuring-junit4-on-android/SKILL.md — JUnit4 plumbing surrounding Robolectric.
• Sibling: ../../mocking/mocking-with-mockito/SKILL.md — mocking Android types under Robolectric.
• Sibling: ../../mocking/mocking-with-mockk/SKILL.md — mockkStatic(Build::class) for fingerprint branches.
• Cross-set: ../../../fundamentals/strategies/applying-testing-strategies/SKILL.md — Robolectric is "medium" tests in Google's three-size framing.
• Cross-set: ../../../fundamentals/strategies/organizing-test-source-sets/SKILL.md — src/test/ vs src/androidTest/ vs androidHostTest/androidDeviceTest.
• Cross-set: ../../../compose/synchronization/controlling-the-test-clock/SKILL.md — Compose's MainTestClock is separate from ShadowLooper.
• Cross-set: ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md — when the same test source needs to run on a device.