using-robolectric-correctly

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Using Robolectric Correctly — Android On The JVM, Without The Footguns

正确使用 Robolectric——在 JVM 上测试 Android,避免常见陷阱

Robolectric simulates Android on the JVM by swapping in pure-Java reimplementations of system classes ("shadows"). It is fast (10-100x vs an emulator) but not an emulator: no real
RenderThread
, no real Binder, no real GPU. This skill locks down the runner choice, the
@Config
matrix, the looper draining ritual, and the AGP 7.2+ sharedTest gotcha. Compose-on-Robolectric specifics live in
../../../compose/synchronization/controlling-the-test-clock/SKILL.md
.
Robolectric 通过将系统类替换为纯 Java 重新实现(这些实现称为 “shadows”)来在 JVM 上模拟 Android。它的速度很快(比模拟器快 10-100 倍),但它不是模拟器:没有真实的
RenderThread
、真实的 Binder 或真实的 GPU。本 skill 明确了运行器选择、
@Config
矩阵、Looper 清空流程,以及 AGP 7.2+ 的 sharedTest 陷阱。在 Robolectric 上使用 Compose 的具体注意事项位于
../../../compose/synchronization/controlling-the-test-clock/SKILL.md
。

When to use this skill

何时使用此 skill

  • The class under test imports
    android.*
    (Context, Resources, View, PackageManager, Looper) and the developer wants to test it on the JVM in seconds, not on an emulator in minutes.
  • A unit test fails with
    RuntimeException: Method ... not mocked
    (the bare-Android-jar default) — the developer needs Robolectric's shadows.
  • A unit test fails with
    Resources$NotFoundException
    —
    testOptions.unitTests.includeAndroidResources
    is missing.
  • The developer asks "AndroidJUnit4 vs RobolectricTestRunner — which?".
  • A
    Handler.postDelayed
    /
    Looper
    queue does not advance under Robolectric's default
    LooperMode.PAUSED
    .
  • The developer asks how to run the same test source on JVM and on a device (
    sharedTest
    /
    androidHostTest
    +
    androidDeviceTest
    ).
  • Build error after AGP 7.2+: "Source directory ... already added to source set", caused by the classic
    sharedTest
    srcDir
    sharing pattern.
  • 被测类导入了
    android.*
    (Context、Resources、View、PackageManager、Looper),开发者希望在几秒内完成 JVM 测试,而不是花几分钟运行模拟器。
  • 单元测试因
    RuntimeException: Method ... not mocked
    而失败(默认的 bare Android jar 所导致)——开发者需要使用 Robolectric 的 shadows。
  • 单元测试因
    Resources$NotFoundException
    而失败——缺少
    testOptions.unitTests.includeAndroidResources
    。
  • 开发者询问“AndroidJUnit4 vs RobolectricTestRunner——该选哪个?”。
  • 在 Robolectric 默认的
    LooperMode.PAUSED
    下,
    Handler.postDelayed
    /
    Looper
    队列不会自动推进。
  • 开发者询问如何在 JVM 和设备上运行相同的测试源文件(
    sharedTest
    /
    androidHostTest
    +
    androidDeviceTest
    )。
  • 使用 AGP 7.2+ 后出现构建错误:“Source directory ... already added to source set”,其原因是传统的
    sharedTest
    srcDir
    共享模式。

When NOT to use this skill

何时不应使用此 skill

  • The class under test has zero
    android.*
    imports. Robolectric pays a 1-3 s class-load tax for nothing — use plain JUnit4. See
    ../../runner/configuring-junit4-on-android/SKILL.md
    .
  • The test verifies pixel correctness, ripple animations, screenshot diffs, accessibility services, or
    RenderThread
    timing. Run on an emulator/device. See
    ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md
    .
  • The test is about coroutines +
    runTest
    and does not need framework Android. Use
    ../../coroutines/testing-coroutines-with-runtest/SKILL.md
    .
  • The test is about Compose UI rendering. The host-test environment is set up by
    ../../../compose/setup/configuring-test-dependencies/SKILL.md
    and the clock semantics live in
    ../../../compose/synchronization/controlling-the-test-clock/SKILL.md
    .
  • 被测类没有导入任何
    android.*
    。使用 Robolectric 会白白增加 1-3 秒的类加载开销——请使用普通 JUnit4。参见
    ../../runner/configuring-junit4-on-android/SKILL.md
    。
  • 测试需要验证像素正确性、ripple 动画、截图差异、无障碍服务或
    RenderThread
    时序。请在模拟器或设备上运行。参见
    ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md
    。
  • 测试关注协程与
    runTest
    ,且不需要 Android 框架。请使用
    ../../coroutines/testing-coroutines-with-runtest/SKILL.md
    。
  • 测试关注 Compose UI 渲染。宿主测试环境由
    ../../../compose/setup/configuring-test-dependencies/SKILL.md
    配置,时钟语义位于
    ../../../compose/synchronization/controlling-the-test-clock/SKILL.md
    。

Prerequisites

前置条件

kotlin
testImplementation("junit:junit:4.13.2")
testImplementation("org.robolectric:robolectric:4.x")
testImplementation("androidx.test:core:1.7.0")              // ApplicationProvider works on both runtimes
testImplementation("androidx.test.ext:junit:1.3.0")         // androidx.test.ext.junit.runners.AndroidJUnit4
(
docs/CORPUS.md
§G.1; R7.)
gradle
android {
    testOptions {
        unitTests {
            includeAndroidResources = true                  // non-negotiable
        }
    }
}
includeAndroidResources
is required if any test (or any class loaded by any test) touches
R.*
,
Resources
, layouts, themes, or anything from
res/
. Without it, resource lookups throw at test startup (R7).
Robolectric 4.x supports SDKs 21 through the latest stable. The androidx Compose host tests pin a floor of 23 — quote it as a single source of truth:
kotlin
// androidx/compose/ui/ui-test/src/androidHostTest/.../Constants.kt
internal const val RobolectricMinSdk = 23
(R7.)
kotlin
testImplementation("junit:junit:4.13.2")
testImplementation("org.robolectric:robolectric:4.x")
testImplementation("androidx.test:core:1.7.0")              // ApplicationProvider works on both runtimes
testImplementation("androidx.test.ext:junit:1.3.0")         // androidx.test.ext.junit.runners.AndroidJUnit4
(
docs/CORPUS.md
§G.1;R7。)
gradle
android {
    testOptions {
        unitTests {
            includeAndroidResources = true                  // non-negotiable
        }
    }
}
如果任何测试(或测试加载的任何类)访问
R.*
、
Resources
、布局、主题或
res/
中的内容,就必须设置
includeAndroidResources
。如果不设置,测试启动时的资源查找会抛出异常(R7)。
Robolectric 4.x 支持 SDK 21 至最新的稳定版本。androidx Compose 宿主测试将下限固定为 23——应将其作为单一事实来源引用:
kotlin
// androidx/compose/ui/ui-test/src/androidHostTest/.../Constants.kt
internal const val RobolectricMinSdk = 23
(R7。)

Runner choice — AndroidJUnit4 vs RobolectricTestRunner

运行器选择——AndroidJUnit4 vs RobolectricTestRunner

Two runners work; they read
@Config
identically.
RunnerWhen
androidx.test.ext.junit.runners.AndroidJUnit4
Default. A router: delegates to Robolectric on JVM and to the real
AndroidJUnit4ClassRunner
on a device. Linchpin of the sharedTest pattern.
org.robolectric.RobolectricTestRunner
Only when the test must never run on a device — e.g. uses Robolectric-specific shadow APIs like
shadowOf(Looper.getMainLooper()).idle()
directly, or needs a Robolectric subclass like
ParameterizedRobolectricTestRunner
.
(R7;
docs/CORPUS.md
§G.6.)
kotlin
import androidx.test.ext.junit.runners.AndroidJUnit4
@RunWith(AndroidJUnit4::class)
@Config(minSdk = 23)
class FooTest { /* runs under Robolectric on JVM, real runner on device */ }

import org.robolectric.RobolectricTestRunner
@RunWith(RobolectricTestRunner::class)
@Config(sdk = [33])
class LooperBoundTest { /* uses ShadowLooper APIs directly — JVM only */ }
CRITICAL:
androidx.test.runner.AndroidJUnit4
(the runner package, not
ext.junit.runners
) is
@Deprecated
(
docs/CORPUS.md
§G.2). Always import from
androidx.test.ext.junit.runners
.
两种运行器都可用,并且会以相同方式读取
@Config
。
运行器使用场景
androidx.test.ext.junit.runners.AndroidJUnit4
默认选择。 它是一个路由器:在 JVM 上委托给 Robolectric,在设备上委托给真实的
AndroidJUnit4ClassRunner
。是 sharedTest 模式的关键。
org.robolectric.RobolectricTestRunner
仅当测试绝不能在设备上运行时使用——例如直接使用 Robolectric 专属 shadow API,如
shadowOf(Looper.getMainLooper()).idle()
,或者需要
ParameterizedRobolectricTestRunner
等 Robolectric 子类。
(R7;
docs/CORPUS.md
§G.6。)
kotlin
import androidx.test.ext.junit.runners.AndroidJUnit4
@RunWith(AndroidJUnit4::class)
@Config(minSdk = 23)
class FooTest { /* runs under Robolectric on JVM, real runner on device */ }

import org.robolectric.RobolectricTestRunner
@RunWith(RobolectricTestRunner::class)
@Config(sdk = [33])
class LooperBoundTest { /* uses ShadowLooper APIs directly — JVM only */ }
关键:
androidx.test.runner.AndroidJUnit4
(runner 包,而不是
ext.junit.runners
)已标记为
@Deprecated
(
docs/CORPUS.md
§G.2)。始终从
androidx.test.ext.junit.runners
导入。

@Config — sdk, qualifiers, application

@Config——sdk、qualifiers、application

@Config
configures the simulated Android environment per class or per method. Method-level overrides class-level; subclasses inherit and may override.
kotlin
// Single SDK
@Config(sdk = [Build.VERSION_CODES.UPSIDE_DOWN_CAKE])
class FooTest

// SDK matrix — runs once per listed SDK
@Config(sdk = [21, 28, 33])
class BarTest

// Range — runs once at the project's targetSdk if it is >= minSdk
@Config(minSdk = 23)
class BazTest

// Per-method override
class QuxTest {
    @Test @Config(sdk = [Build.VERSION_CODES.TIRAMISU])
    fun onTiramisuOnly() { /* ... */ }

    @Test @Config(qualifiers = "fr-rFR-w820dp")           // locale + screen
    fun frenchLayout() { /* ... */ }

    @Test @Config(qualifiers = "+night")                   // additive: keep, force night
    fun darkColors() { /* ... */ }
}

// Override the Application instance
@Config(application = MyTestApplication::class)
class WithFakeApp
(R7.)
Constraint:
sdk
and
minSdk
/
maxSdk
cannot coexist on the same annotation.
minSdk
and
maxSdk
may be combined.
CI-time hot take: prefer
@Config(sdk = [<one SDK>])
on the commit gate; reserve multi-SDK matrices for the merge gate. Each SDK in the matrix re-runs the whole class.
@Config
用于按类或按方法配置模拟的 Android 环境。方法级配置会覆盖类级配置;子类会继承配置,也可以覆盖配置。
kotlin
// Single SDK
@Config(sdk = [Build.VERSION_CODES.UPSIDE_DOWN_CAKE])
class FooTest

// SDK matrix — runs once per listed SDK
@Config(sdk = [21, 28, 33])
class BarTest

// Range — runs once at the project's targetSdk if it is >= minSdk
@Config(minSdk = 23)
class BazTest

// Per-method override
class QuxTest {
    @Test @Config(sdk = [Build.VERSION_CODES.TIRAMISU])
    fun onTiramisuOnly() { /* ... */ }

    @Test @Config(qualifiers = "fr-rFR-w820dp")           // locale + screen
    fun frenchLayout() { /* ... */ }

    @Test @Config(qualifiers = "+night")                   // additive: keep, force night
    fun darkColors() { /* ... */ }
}

// Override the Application instance
@Config(application = MyTestApplication::class)
class WithFakeApp
(R7。)
限制:
sdk
与
minSdk
/
maxSdk
不能出现在同一个注解中。
minSdk
与
maxSdk
可以组合使用。
CI 阶段的实用建议:提交门禁优先使用
@Config(sdk = [<单个 SDK>])
;多 SDK 矩阵则留给合并门禁。矩阵中的每个 SDK 都会重新运行整个测试类。

Shadows

Shadows

Shadows are JVM-friendly fakes for Android system classes. Robolectric ships hundreds; you can write your own with
@Implements
/
@Implementation
. Common ones:
ShadowPurpose
ShadowApplication
Inspect started services / broadcasts / granted permissions.
ShadowLog
Capture
android.util.Log
output (
ShadowLog.stream = System.out
).
ShadowSystemClock
Advance / freeze
SystemClock.elapsedRealtime()
/
uptimeMillis()
.
ShadowLooper
Drive message queues;
idleMainLooper()
,
runUiThreadTasksIncludingDelayedTasks()
.
ShadowPackageManager
Add/remove packages, set system features, queryable intents.
ShadowAlarmManager
Inspect scheduled alarms without firing them.
ShadowNotificationManager
Inspect posted notifications and channels.
ShadowInputManager
Add/remove
InputDevice
s for input tests.
ShadowContentResolver
Register fake providers, observe inserts/queries.
Shadows.shadowOf(realObject)
returns the shadow instance. Static-import and rely on overload resolution:
kotlin
import androidx.test.core.app.ApplicationProvider
import org.robolectric.Shadows.shadowOf
import org.robolectric.shadows.ShadowPackageManager

val app: Application = ApplicationProvider.getApplicationContext()
val shadowPm: ShadowPackageManager = shadowOf(app.packageManager)
shadowPm.setSystemFeature(PackageManager.FEATURE_CAMERA_ANY, true)
Shadows 是适合 JVM 环境的 Android 系统类 fake。Robolectric 内置了数百种 shadow,也可以使用
@Implements
/
@Implementation
自行编写。常见 shadow 包括:
Shadow用途
ShadowApplication
检查已启动的服务、广播和已授予权限。
ShadowLog
捕获
android.util.Log
输出(
ShadowLog.stream = System.out
)。
ShadowSystemClock
推进或冻结
SystemClock.elapsedRealtime()
/
uptimeMillis()
。
ShadowLooper
驱动消息队列;
idleMainLooper()
、
runUiThreadTasksIncludingDelayedTasks()
。
ShadowPackageManager
添加或移除软件包、设置系统功能、查询 Intent。
ShadowAlarmManager
在不触发闹钟的情况下检查计划任务。
ShadowNotificationManager
检查已发布的通知和通知渠道。
ShadowInputManager
为输入测试添加或移除
InputDevice
。
ShadowContentResolver
注册 fake provider,监听插入和查询。
Shadows.shadowOf(realObject)
返回对应的 shadow 实例。可以静态导入并依赖重载解析:
kotlin
import androidx.test.core.app.ApplicationProvider
import org.robolectric.Shadows.shadowOf
import org.robolectric.shadows.ShadowPackageManager

val app: Application = ApplicationProvider.getApplicationContext()
val shadowPm: ShadowPackageManager = shadowOf(app.packageManager)
shadowPm.setSystemFeature(PackageManager.FEATURE_CAMERA_ANY, true)

Looper draining — the most-missed step

Looper 清空——最容易遗漏的一步

Robolectric's main looper is paused in the default
LooperMode.PAUSED
runtime mode. Handler messages posted by the SUT do NOT run automatically. Drain explicitly:
kotlin
import android.os.Looper
import org.robolectric.Shadows.shadowOf
import org.robolectric.shadows.ShadowLooper
import java.time.Duration

// Drain everything currently queued on the main looper.
shadowOf(Looper.getMainLooper()).idle()

// Run delayed tasks too (postDelayed et al).
ShadowLooper.runUiThreadTasksIncludingDelayedTasks()

// Advance virtual time by N ms; only handlers due before that time fire.
shadowOf(Looper.getMainLooper()).idleFor(Duration.ofMillis(500))
(R7.)
This complements (and is independent from) Compose's
MainTestClock.advanceTimeBy(...)
. The Compose clock and the platform looper are separate. For Compose-on-Robolectric,
runComposeUiTest { … waitForIdle() }
drives the looper for you via
RobolectricIdlingStrategy
— outside Compose, drain manually.
在默认的
LooperMode.PAUSED
运行模式下,Robolectric 的主 Looper 会暂停。由 SUT 发布到 Handler 的消息不会自动执行。必须显式清空队列:
kotlin
import android.os.Looper
import org.robolectric.Shadows.shadowOf
import org.robolectric.shadows.ShadowLooper
import java.time.Duration

// Drain everything currently queued on the main looper.
shadowOf(Looper.getMainLooper()).idle()

// Run delayed tasks too (postDelayed et al).
ShadowLooper.runUiThreadTasksIncludingDelayedTasks()

// Advance virtual time by N ms; only handlers due before that time fire.
shadowOf(Looper.getMainLooper()).idleFor(Duration.ofMillis(500))
(R7。)
这与 Compose 的
MainTestClock.advanceTimeBy(...)
相互补充,但两者彼此独立。Compose 时钟和平台 Looper 是两个不同的系统。对于在 Robolectric 上运行 Compose 的场景,
runComposeUiTest { … waitForIdle() }
会通过
RobolectricIdlingStrategy
自动驱动 Looper;在 Compose 之外则需要手动清空。

sharedTest / androidHostTest / androidDeviceTest

sharedTest / androidHostTest / androidDeviceTest

The classic sharedTest pattern (per the 2021 Robolectric blog post) puts one source directory under both
test
and
androidTest
:
gradle
// LEGACY — broken on AGP 7.2+
android {
    sourceSets {
        String dir = 'src/sharedTest/'
        test       { java.srcDirs += dir + 'java' }
        androidTest { java.srcDirs += dir + 'java' }
    }
}
CRITICAL: starting with AGP 7.2+, you cannot put the same source directory into multiple source sets (Robolectric GitHub issue #7432; R7). The build fails with "Source directory ... already added to source set".
Modern alternatives (PREFERRED order):
  1. AndroidX-style KMP source sets —
    commonTest
    ->
    {androidHostTest, androidDeviceTest}
    via the
    androidXMultiplatform
    plugin. Compose internally migrated to this:
    gradle
    sourceSets {
        androidCommonTest  { dependsOn(commonTest) }
        androidDeviceTest  { dependsOn(androidCommonTest) }   // instrumented APK
        androidHostTest    { dependsOn(androidCommonTest) }   // Robolectric on JVM
    }
  2. Separate Gradle module that both
    test
    and
    androidTest
    depend on as
    testImplementation
    /
    androidTestImplementation
    .
  3. Symlink or copy sources at configuration time (least preferred — fragile).
Both
androidHostTest
and
androidDeviceTest
can use
@RunWith(AndroidJUnit4::class)
unchanged because
AndroidJUnit4
is a router. Source-set wiring is
../../../fundamentals/strategies/organizing-test-source-sets/SKILL.md
.
经典的 sharedTest 模式( according to the 2021 Robolectric blog post)会将同一个源目录同时放入
test
和
androidTest
:
gradle
// LEGACY — broken on AGP 7.2+
android {
    sourceSets {
        String dir = 'src/sharedTest/'
        test       { java.srcDirs += dir + 'java' }
        androidTest { java.srcDirs += dir + 'java' }
    }
}
关键:从 AGP 7.2+ 开始,不能将同一个源目录放入多个 source set(Robolectric GitHub issue #7432;R7)。构建会因“Source directory ... already added to source set”而失败。
现代替代方案(按优先级排列):
  1. AndroidX 风格的 KMP source set——通过
    androidXMultiplatform
    插件,将
    commonTest
    映射到
    {androidHostTest, androidDeviceTest}
    。Compose 内部已迁移到这种方式:
    gradle
    sourceSets {
        androidCommonTest  { dependsOn(commonTest) }
        androidDeviceTest  { dependsOn(androidCommonTest) }   // instrumented APK
        androidHostTest    { dependsOn(androidCommonTest) }   // Robolectric on JVM
    }
  2. 独立的 Gradle module,并让
    test
    和
    androidTest
    分别通过
    testImplementation
    /
    androidTestImplementation
    依赖它。
  3. 符号链接或复制源文件,并在配置阶段执行(最不推荐——容易失效)。
androidHostTest
和
androidDeviceTest
都可以继续使用
@RunWith(AndroidJUnit4::class)
,因为
AndroidJUnit4
是一个路由器。Source set 的配置参见
../../../fundamentals/strategies/organizing-test-source-sets/SKILL.md
。

When NOT to reach for Robolectric

何时不应使用 Robolectric

ScenarioWhere it belongs
Pure Kotlin, no
android.*
imports
Plain JUnit4 in
src/test/
(no Robolectric).
Pixel-correct rendering, screenshot testsEmulator/device —
RenderThread
is real there, not on Robolectric.
Accessibility service behaviorEmulator/device. Compose's
enableAccessibilityChecks
installs the validator on Robolectric AND logs a warning (
Build.FINGERPRINT.lowercase() == "robolectric"
); Robolectric does not faithfully drive the accessibility services so any pass is inconclusive (b/332778271).
Choreographer
fidelity, animation timing close to production
Emulator/device.
GPU/Skia behaviorEmulator/device.
@GraphicsMode(GraphicsMode.Mode.NATIVE)
opt-in is a stub of the real pipeline.
场景应使用
纯 Kotlin,没有
android.*
导入
src/test/
中的普通 JUnit4(不使用 Robolectric)。
像素级正确的渲染、截图测试模拟器或设备——只有在那里才有真实的
RenderThread
。
无障碍服务行为模拟器或设备。Compose 的
enableAccessibilityChecks
会在 Robolectric 上安装验证器并记录警告(
Build.FINGERPRINT.lowercase() == "robolectric"
);Robolectric 无法忠实驱动无障碍服务,因此即使测试通过也无法得出可靠结论(b/332778271)。
Choreographer
保真度、接近生产环境的动画时序
模拟器或设备。
GPU/Skia 行为模拟器或设备。
@GraphicsMode(GraphicsMode.Mode.NATIVE)
是对真实渲染管线的 stub。

Patterns

模式

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

模式:错误——对应当 also run on device 的测试使用 RobolectricTestRunner

kotlin
// 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.
kotlin
// RIGHT
@RunWith(AndroidJUnit4::class)
@Config(minSdk = RobolectricMinSdk)                      // pin via single source of truth
class LoginViewModelTest {
    @Test fun loginFlow() { /* ... */ }
}
kotlin
// 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.
kotlin
// 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

模式:错误——在清空 Looper 之前断言

kotlin
// 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.
kotlin
// 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)
    }
}
kotlin
// 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.
kotlin
// 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

模式:错误——缺少 includeAndroidResources

gradle
// WRONG
android {
    testOptions {
        unitTests { /* includeAndroidResources missing */ }
    }
}
Symptom:
android.content.res.Resources$NotFoundException: String resource ID #0x7f0c0001
at test startup. The fix:
gradle
// RIGHT
android {
    testOptions {
        unitTests {
            includeAndroidResources = true                // Groovy
            // isIncludeAndroidResources = true           // Kotlin DSL
        }
    }
}
gradle
// WRONG
android {
    testOptions {
        unitTests { /* includeAndroidResources missing */ }
    }
}
症状:测试启动时出现
android.content.res.Resources$NotFoundException: String resource ID #0x7f0c0001
。修复方式:
gradle
// RIGHT
android {
    testOptions {
        unitTests {
            includeAndroidResources = true                // Groovy
            // isIncludeAndroidResources = true           // Kotlin DSL
        }
    }
}

Pattern: WRONG — sharedTest srcDir sharing on AGP 7.2+

模式:错误——在 AGP 7.2+ 上共享 sharedTest srcDir

gradle
// 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".
gradle
// RIGHT — AndroidX-style KMP source sets
sourceSets {
    androidCommonTest  { dependsOn(commonTest) }
    androidDeviceTest  { dependsOn(androidCommonTest) }
    androidHostTest    { dependsOn(androidCommonTest) }
}
gradle
// 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".
gradle
// RIGHT — AndroidX-style KMP source sets
sourceSets {
    androidCommonTest  { dependsOn(commonTest) }
    androidDeviceTest  { dependsOn(androidCommonTest) }
    androidHostTest    { dependsOn(androidCommonTest) }
}

Pattern: ParameterizedRobolectricTestRunner — when matrix is the point

模式:ParameterizedRobolectricTestRunner——当测试矩阵本身是重点时

kotlin
// 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.
kotlin
// 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` */ }
}
这是应当固定使用
RobolectricTestRunner
(其参数化子类)的场景之一——因为不存在
AndroidJUnit4
的参数化变体。

Pattern: production code branching on Robolectric — read with caution

模式:生产代码根据 Robolectric 进行分支判断——谨慎使用

kotlin
// 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.
kotlin
// androidx/compose/ui/ui-test/.../RobolectricIdlingStrategy.android.kt
internal val HasRobolectricFingerprint
    get() = Build.FINGERPRINT.lowercase() == "robolectric"
这种写法在 androidx 内部广泛使用(Compose 无障碍、idle 管理、图形层等)。除非该分支确实仅用于测试,否则被测库代码不应照搬这种写法——错误检测会悄无声息地改变行为。

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.
  • 必须从
    androidx.test.ext.junit.runners
    导入
    AndroidJUnit4
    。禁止从
    androidx.test.runner
    导入——后者已标记为
    @Deprecated
    (
    docs/CORPUS.md
    §G.2)。
  • 必须优先使用
    @RunWith(AndroidJUnit4::class)
    ,而不是
    @RunWith(RobolectricTestRunner::class)
    。仅当测试直接使用 Robolectric 专属 API(如
    shadowOf(Looper.getMainLooper()).idle()
    ),或需要
    ParameterizedRobolectricTestRunner
    时,才使用后者。
  • 必须为任何访问
    R.*
    /
    Resources
    / 布局 / 主题的单元测试项目设置
    testOptions.unitTests.includeAndroidResources = true
    。
  • 必须在断言任何依赖
    Handler.post*
    回调的结果之前,使用
    shadowOf(Looper.getMainLooper()).idle()
    (或
    ShadowLooper.runUiThreadTasksIncludingDelayedTasks()
    )清空 Looper。默认的
    LooperMode.PAUSED
    不会自动执行任务。
  • 必须固定类级别的
    @Config(minSdk = …)
    (或
    sdk = […]
    )——不要依赖项目中可能随 CI 环境变化的默认 SDK。
  • 禁止在 AGP 7.2+ 上使用传统的
    srcDirs
    共享模式
    test.java.srcDirs += 'src/sharedTest/java'
    。请迁移到
    androidHostTest
    +
    androidDeviceTest
    (KMP source set)或使用独立的 Gradle module。
  • 禁止对没有任何
    android.*
    导入的测试类使用 Robolectric。否则只会白白增加 1-3 秒的类加载开销。
  • 禁止使用 Robolectric 测试截图、ripple 动画、无障碍服务或
    RenderThread
    时序——请使用模拟器或设备。
  • 推荐:在
    androidHostTest
    module 中,将
    androidx/compose/ui/ui-test/src/androidHostTest/.../Constants.kt
    中的
    RobolectricMinSdk = 23
    作为最低 SDK 的单一事实来源引用。
  • 推荐:将相关测试归入同一个类,以摊薄按类加载的开销。避免在许多小类中随意添加
    @RunWith(RobolectricTestRunner::class)
    。
  • 推荐:提交门禁使用单 SDK 的
    @Config(sdk = [33])
    ;合并门禁使用多 SDK 矩阵。

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
    .
  • 没有导入
    androidx.test.runner.AndroidJUnit4
    (应使用
    androidx.test.ext.junit.runners.AndroidJUnit4
    )。
    grep -rn 'androidx.test.runner.AndroidJUnit4' src/test src/androidTest
    的结果为空。
  • 已在 module 的
    build.gradle(.kts)
    中设置
    testOptions.unitTests.includeAndroidResources = true
    。
  • 没有在实际未使用 Robolectric 专属 API 的测试类上使用
    @RunWith(RobolectricTestRunner::class)
    。
  • 每个向
    Handler
    发布任务或触发
    Looper
    工作的测试,都会在断言前调用
    shadowOf(Looper.getMainLooper()).idle()
    (或
    runUiThreadTasksIncludingDelayedTasks
    )。
  • 每个 Robolectric 测试类都声明了
    @Config(minSdk = …)
    或
    @Config(sdk = […])
    。
  • Source set 使用
    androidHostTest
    +
    androidDeviceTest
    (或共享 module),而不是传统的
    srcDirs += sharedTest
    。
  • 没有截图、ripple 或无障碍服务测试在 Robolectric 下运行——这些测试位于
    src/androidTest/
    或
    androidDeviceTest
    。
  • ./gradlew :module:test
    通过;对于
    androidCommonTest
    中的任何测试,
    ./gradlew :module:connectedDebugAndroidTest
    也通过。

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.
  • Robolectric——入门: http://robolectric.org/getting-started/
  • Robolectric——配置: http://robolectric.org/configuring/
  • Robolectric——sharedTest 博客文章: http://robolectric.org/blog/2021/10/06/sharedTest/
  • Android Developers——构建本地单元测试: 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 失效: https://github.com/robolectric/robolectric/issues/7432
  • 研究:
    tasks/research/R7-robolectric.md
    。
  • docs/CORPUS.md
    §G.1 / §G.6——Gradle 坐标与运行器选择。
  • androidx/compose/ui/ui-test/src/androidHostTest/.../Constants.kt
    ——
    RobolectricMinSdk = 23
    下限。
  • androidx/compose/ui/ui-test/.../RobolectricComposeTest.kt
    ——规范的
    @RunWith(AndroidJUnit4::class) @Config(minSdk = RobolectricMinSdk)
    跨运行时测试。
  • androidx/compose/ui/ui-test/.../PrefetchNotHangingMainThreadTest.kt
    ——使用
    @RunWith(RobolectricTestRunner::class)
    并显式调用
    shadowOf(Looper.getMainLooper()).idle()
    。
  • androidx/compose/ui/ui-test/.../ViewVisibilityRobolectricTest.kt
    ——
    ParameterizedRobolectricTestRunner
    示例。
  • androidx/compose/ui/ui-test/.../RobolectricIdlingStrategy.android.kt
    ——
    Build.FINGERPRINT.lowercase() == "robolectric"
    检测方式。
  • androidx/compose/ui/ui/.../MediaQueryIntegrationTest.kt
    ——在
    @RunWith(AndroidJUnit4::class)
    测试中使用
    ShadowPackageManager
    /
    ShadowInputManager
    。
  • 同级:
    ../../coroutines/testing-coroutines-with-runtest/SKILL.md
    ——
    runTest
    +
    MainDispatcherRule
    (独立于 Robolectric)。
  • 同级:
    ../../coroutines/testing-flows-with-turbine/SKILL.md
    ——Flow 断言;Turbine 在 Robolectric 下无需改动即可使用。
  • 同级:
    ../../runner/configuring-junit4-on-android/SKILL.md
    ——Robolectric 周围的 JUnit4 配置。
  • 同级:
    ../../mocking/mocking-with-mockito/SKILL.md
    ——在 Robolectric 下 mock Android 类型。
  • 同级:
    ../../mocking/mocking-with-mockk/SKILL.md
    ——对 fingerprint 分支使用
    mockkStatic(Build::class)
    。
  • 跨集合:
    ../../../fundamentals/strategies/applying-testing-strategies/SKILL.md
    ——在 Google 的三档测试框架中,Robolectric 属于“中等”测试。
  • 跨集合:
    ../../../fundamentals/strategies/organizing-test-source-sets/SKILL.md
    ——
    src/test/
    、
    src/androidTest/
    、
    androidHostTest
    /
    androidDeviceTest
    之间的区别。
  • 跨集合:
    ../../../compose/synchronization/controlling-the-test-clock/SKILL.md
    ——Compose 的
    MainTestClock
    与
    ShadowLooper
    相互独立。
  • 跨集合:
    ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md
    ——当相同测试源需要在设备上运行时使用。