Robolectric

Step 1: Establish the Android test boundary

1. DEFINE setup | behavior test | lifecycle/resources | scheduling | SDK/qualifier coverage | AndroidX/Compose | custom shadow | CI/download failure | upgrade.
2. IDENTIFY the owning Android module, variant, source sets, Gradle wrapper, AGP, test engine, test-worker JDK, compileSdk/targetSdk/minSdk, AndroidX/Compose version ownership, and required Android behavior.
3. USE Robolectric for Android framework behavior on a host JVM. Keep pure Kotlin/Java logic in ordinary unit tests; use device/emulator instrumentation for actual permissions/system services, Bluetooth/radio, OEM, GPU, or cross-app behavior. A shadow's recorded request is not proof the real OS executed it.
4. READ the current setup docs, stable release, and requested-version source before changing dependencies. The pinned 4.17 source overrides lagging README examples and historical documentation fields. Route general build migration to kotlin-gradle, coroutine scheduling to kotlin-coroutines, Android Compose implementation to android-material3-compose.

Completion: exact consumer-visible behavior, Android simulation boundary, module/variant and verification command are known.

Step 2: Configure the existing module

1. READ configuration and CI for worker-JDK/SDK compatibility, engine selection, configuration precedence, upgrades, runtime downloads or failures.
2. MERGE Gradle setup into the existing Android module's owning configuration; preserve its plugins, repositories, version catalog and toolchain. Required: testImplementation Robolectric and JUnit 4; unitTests.isIncludeAndroidResources=true for manifest/resources; documented opens on JDK 17+ test workers.
3. PLACE JVM tests in src/test/java or src/test/kotlin, not src/androidTest. Use org.junit.Test with RobolectricTestRunner, or declared AndroidJUnit4. Existing JUnit Platform suites need an aligned Vintage runtime for these JUnit 4 tests, not Jupiter annotations on a Robolectric runner class.
4. USE the tested variant's merged manifest/binary resources and generated R. Keep Activity registration, theme and app namespace accurate. Do not use returnDefaultValues or Config.NONE to conceal missing runner/resource setup.
5. SELECT a supported runtime SDK explicitly when the app target is outside the supported inventory, only with accepted coverage scope. compileSdk and installed Android SDK platforms do not define Robolectric runtime support. Verify both daemon and worker JDK; they may differ.