Configuring Junit4 On Android

Configuring JUnit4 on Android — The Right Runner, Registry, and Matrix

Almost every "test suite is misconfigured" report boils down to one of three root causes: the wrong AndroidJUnit4 is imported, the wrong InstrumentationRegistry is imported, or the size-annotation / dispatcher plumbing is missing. This skill encodes the exact Gradle matrix from androidx.test:core 1.7.0 onward, the canonical FQCNs, and the minimal MainDispatcherRule pattern that androidx itself ships in testutils-ktx.

When to use this skill

• The user reports Cannot resolve symbol AndroidJUnit4, AndroidJUnit4 is deprecated, or asks "which AndroidJUnit4 should I import".
• The user reports IllegalStateException: No instrumentation registered from InstrumentationRegistry.getInstrumentation() in a unit test, or asks why InstrumentationRegistry is crossed out.
• The user wants Truth subjects (IntentSubject, BundleSubject, LocationSubject, ParcelableSubject) but does not know which artifact ships them.
• The user wants am instrument -e size small to filter tests and asks how to wire @SmallTest / @MediumTest / @LargeTest.
• The user is writing a ViewModel / coroutine test and needs the canonical MainDispatcherRule template.

When NOT to use this skill

• The user is wiring Mockito mocks — use ../../mocking/mocking-with-mockito/SKILL.md.
• The user is wiring MockK mocks — use ../../mocking/mocking-with-mockk/SKILL.md.
• The user is configuring runTest { … } or Turbine — use ../../coroutines/testing-coroutines-with-runtest/SKILL.md or ../../coroutines/testing-flows-with-turbine/SKILL.md.
• The user is configuring Robolectric specifically (SDK matrix, resources, @Config) — use ../../robolectric/using-robolectric-correctly/SKILL.md.
• The user is running tests on a device with am instrument — use ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md.
• The user is choosing between fakes and mocks — use ../../../fundamentals/doubles/picking-test-doubles/SKILL.md.

Prerequisites

• Android Gradle Plugin applied (com.android.application or com.android.library).
• A src/test/ source set on disk (Gradle creates it lazily — mkdir -p src/test/kotlin if missing).
• Kotlin module (these notes assume Kotlin; the same FQCNs work from Java).
• For coroutine-related tests, org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.x already on the classpath.

Workflow

• 1. Pin the canonical Gradle dependency matrix. These are the released stable versions backing this skill (verified against ~/.gradle/caches/modules-2/files-2.1/androidx.test/...). Pin them directly, do not latest.release:

dependencies {
    // Core JUnit4
    testImplementation("junit:junit:4.13.2")

    // androidx.test foundations (work in src/test/ via Robolectric and in src/androidTest/)
    testImplementation("androidx.test:core:1.7.0")
    testImplementation("androidx.test:core-ktx:1.6.1")
    testImplementation("androidx.test:runner:1.7.0")
    testImplementation("androidx.test:rules:1.7.0")
    testImplementation("androidx.test.ext:junit:1.3.0")
    testImplementation("androidx.test.ext:junit-ktx:1.3.0")
    testImplementation("androidx.test.ext:truth:1.7.0")
    testImplementation("com.google.truth:truth:1.4.4")

    // Coroutines test (for MainDispatcherRule / runTest)
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.1")
}

For instrumented tests in src/androidTest/, mirror the same artifacts on androidTestImplementation. The artifacts are dual-classpath compatible.

• 2. Annotate test classes with the correct @RunWith. There are TWO classes named AndroidJUnit4 on the classpath. The deprecated one is androidx.test.runner.AndroidJUnit4 (file runner-1.7.0/androidx/test/runner/AndroidJUnit4.java L41-44 — @Deprecated). The canonical one is androidx.test.ext.junit.runners.AndroidJUnit4 from the androidx.test.ext:junit:1.3.0 artifact (file junit-1.3.0/androidx/test/ext/junit/runners/AndroidJUnit4.java L49). It delegates to Robolectric on the JVM (when org.robolectric.RobolectricTestRunner is on the classpath) and to androidx.test.internal.runner.junit4.AndroidJUnit4ClassRunner on a device.

import androidx.test.ext.junit.runners.AndroidJUnit4   // canonical
import org.junit.runner.RunWith

@RunWith(AndroidJUnit4::class)
class MyTest { /* ... */ }

• 3. Use the canonical InstrumentationRegistry. androidx.test.InstrumentationRegistry (no .platform.app.) is @Deprecated since :monitor 1.x — every member is @InlineMe'd to its replacement. The canonical class is androidx.test.platform.app.InstrumentationRegistry (file monitor-1.8.0/androidx/test/platform/app/InstrumentationRegistry.java L30-85).

import androidx.test.platform.app.InstrumentationRegistry

val instrumentation = InstrumentationRegistry.getInstrumentation()
val args: Bundle = InstrumentationRegistry.getArguments()  // copy of -e key/value pairs

getInstrumentation() throws IllegalStateException("No instrumentation registered! Must run under a registering instrumentation.") if called outside an instrumentation host or before Robolectric initialises its shadow. Robolectric registers an Instrumentation instance into the registry before tests run, so this works in src/test/ when @RunWith(AndroidJUnit4::class) is in effect.

• 4. Pull the application Context via ApplicationProvider, not via the registry. ApplicationProvider.getApplicationContext() is the single entry point for the Application context (file core-1.7.0/androidx/test/core/app/ApplicationProvider.java L29-43). Internally it returns getInstrumentation().getTargetContext().getApplicationContext() — same Context, more readable callsite, and the unchecked generic lets callers cast to their Application subclass.

import androidx.test.core.app.ApplicationProvider

val ctx: Context = ApplicationProvider.getApplicationContext()
val app: MyApp = ApplicationProvider.getApplicationContext()   // unchecked cast

• 5. Tag each test with a size annotation when the suite is large enough to need filtering. Size is one of three: @SmallTest (<200ms, no Android stubs), @MediumTest (<1000ms, Android framework via Robolectric), @LargeTest (>1000ms, instrumented). Annotations live in androidx.test.filters.* (file runner-1.7.0/androidx/test/filters/SmallTest.java L44-46). The runner's RunnerArgs.SIZE (runner-1.7.0/androidx/test/internal/runner/RunnerArgs.java L58) wires -e size <value> directly to these annotations.

import androidx.test.filters.SmallTest
import androidx.test.filters.MediumTest

@SmallTest
class FastValidatorTest { /* ... */ }

@MediumTest
class RoomDaoTest { /* ... */ }

The corresponding am instrument invocation is adb shell am instrument -w -r -e size small <pkg>/androidx.test.runner.AndroidJUnitRunner. See ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md for the on-device counterpart.

• 6. Reach for Truth subjects from androidx.test.ext:truth for Android-domain assertions. Truth shipped with androidx.test.ext:truth:1.7.0 adds Android-aware Subject types. Each exposes a static assertThat(T actual) shortcut and a static Subject.Factory<T, S> name() factory:

Idiomatic import-and-call:

import androidx.test.ext.truth.content.IntentSubject.assertThat
import androidx.test.ext.truth.os.BundleSubject

@Test fun intent_routes_to_settings() {
    val intent = Intent(Intent.ACTION_VIEW, Uri.parse("settings://wifi"))
    assertThat(intent).hasAction(Intent.ACTION_VIEW)
    assertThat(intent).hasData(Uri.parse("settings://wifi"))
}

• 7. Install a MainDispatcherRule for any test that touches Dispatchers.Main. Compose, viewModelScope, and LiveData all default to Dispatchers.Main, which is unavailable on the JVM unless swapped. The canonical androidx pattern lives at testutils/testutils-ktx/src/jvmMain/kotlin/androidx/testutils/MainDispatcherRule.jvm.kt — use it verbatim:

import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.ExperimentalCoroutinesApi
import kotlinx.coroutines.test.StandardTestDispatcher
import kotlinx.coroutines.test.TestDispatcher
import kotlinx.coroutines.test.resetMain
import kotlinx.coroutines.test.setMain
import org.junit.rules.TestWatcher
import org.junit.runner.Description

@OptIn(ExperimentalCoroutinesApi::class)
class MainDispatcherRule(
    val testDispatcher: TestDispatcher = StandardTestDispatcher(),
) : TestWatcher() {
    override fun starting(description: Description) {
        Dispatchers.setMain(testDispatcher)
    }

    override fun finished(description: Description) {
        Dispatchers.resetMain()
    }
}

Apply on a test class:

@RunWith(AndroidJUnit4::class)
class MyViewModelTest {
    @get:Rule val mainDispatcherRule = MainDispatcherRule()

    @Test fun loadsUsers() = runTest {
        val vm = MyViewModel(repo = FakeUserRepository())
        vm.load()
        advanceUntilIdle()
        assertThat(vm.users.value).isNotEmpty()
    }
}

StandardTestDispatcher is preferred — it queues continuations and only advances on runCurrent()/advanceUntilIdle(), matching kotlinx.coroutines.test.runTest semantics. UnconfinedTestDispatcher dispatches eagerly and is appropriate only when ordering is irrelevant.

• 8. Verify the test class actually runs. Execute the suite once: ./gradlew :<module>:testDebugUnitTest --tests com.example.MyTest. The Gradle output shows the runner choice — org.junit.runner.RunWith: AndroidJUnit4 confirms the canonical runner is bound; Test process exited with status code near the top confirms Robolectric is wiring up.