Running Instrumented Tests With Androidjunit4

Running Instrumented Tests with AndroidJUnit4 — Get the Runner Stack Right

Instrumentation tests fail before any assertion runs when the runner stack is misconfigured: a deprecated AndroidJUnit4 import, the orchestrator on androidTestImplementation instead of androidTestUtil, the deprecated androidx.test.InstrumentationRegistry instead of androidx.test.platform.app.InstrumentationRegistry. This skill encodes the exact dependency matrix, the runner Gradle config, and the supporting annotations and rules.

When to use this skill

• The IDE flags androidx.test.runner.AndroidJUnit4 as @Deprecated, or the test compiles but emits the deprecation warning.
• am instrument returns INSTRUMENTATION_FAILED: <pkg>/androidx.test.runner.AndroidJUnitRunner or Test runner not found.
• Test Orchestrator is configured in Gradle but tests still share a single instrumentation process (orchestrator silently disabled).
• The user passes -e size small / -e package com.foo via am instrument and the test ignores it — RunnerArgs is unwired.
• A test needs ACCESS_FINE_LOCATION / RECORD_AUDIO etc. and the user is hand-rolling permission grants from adb.
• The user wants to skip a test below API 26 and is searching for the annotation.

When NOT to use this skill

• The user is launching an Activity or driving lifecycle — see ../../scenarios/launching-activities-with-activityscenario/SKILL.md.
• The user is interacting with Views — see ../../espresso/writing-espresso-tests/SKILL.md.
• The user is driving system UI or another app — see ../../uiautomator/cross-app-tests-with-uiautomator/SKILL.md.
• The user runs JVM (Robolectric / pure JUnit) tests — see ../../../jvm-tests/runner/configuring-junit4-on-android/SKILL.md.
• The user is choosing what to test in the first place — see ../../../fundamentals/strategies/applying-testing-strategies/SKILL.md.

Prerequisites

• Android Gradle Plugin module (com.android.application or com.android.library).
• A src/androidTest/ source set on disk (./gradlew :module:connectedDebugAndroidTest should resolve).
• An emulator or physical device (or Firebase Test Lab / managed devices) — the runner cannot execute on the JVM.
• JUnit 4 on the test classpath (junit:junit:4.13.2); JUnit 5 requires a Vintage engine bridge and is out of scope.

Workflow

• 1. Pin the AndroidX Test artifacts on androidTestImplementation. These are the canonical 2026 GA versions per docs/CORPUS.md H.1:

dependencies {
    androidTestImplementation("androidx.test:core:1.7.0")
    androidTestImplementation("androidx.test:runner:1.7.0")
    androidTestImplementation("androidx.test:rules:1.7.0")
    androidTestImplementation("androidx.test.ext:junit:1.3.0")
    androidTestImplementation("androidx.test.ext:junit-ktx:1.3.0")
    androidTestImplementation("androidx.test.ext:truth:1.7.0")
}

androidx.test.ext:junit is the artifact that owns the non-deprecated AndroidJUnit4 runner and the non-deprecated ActivityScenarioRule. androidx.test:runner still ships the legacy AndroidJUnit4 (deprecated) — never import from there. See tasks/research/R1-androidx-test-core.md lines 481-490.

• 2. Set the testInstrumentationRunner in the module's android.defaultConfig. The runner FQCN is androidx.test.runner.AndroidJUnitRunner — note this is the runner class, distinct from the deprecated AndroidJUnit4 test runner annotation. From tasks/research/R1-androidx-test-core.md lines 270-289:

android {
    defaultConfig {
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
        // Optional: pass `-e key value` args to every run via Gradle
        testInstrumentationRunnerArguments["clearPackageData"] = "true"
    }
    testOptions {
        animationsDisabled = true                  // hermetic — see Pattern below
    }
}

• 3. Annotate test classes with @RunWith(AndroidJUnit4::class) from androidx.test.ext.junit.runners. This is the only correct import:

import androidx.test.ext.junit.runners.AndroidJUnit4
import org.junit.Test
import org.junit.runner.RunWith

@RunWith(AndroidJUnit4::class)
class LoginActivityTest {
    @Test fun loginSucceeds() { /* ... */ }
}

The deprecated androidx.test.runner.AndroidJUnit4 is @Deprecated at runner-1.7.0/androidx/test/runner/AndroidJUnit4.java:43-44. It still works at runtime but the IDE warns and codemods will replace it.

• 4. Read instrumentation arguments via androidx.test.platform.app.InstrumentationRegistry. The legacy androidx.test.InstrumentationRegistry (no platform.app) is @Deprecated and @InlineMe'd to the canonical class — see tasks/research/R1-androidx-test-core.md lines 142-153:

import androidx.test.platform.app.InstrumentationRegistry
import androidx.test.core.app.ApplicationProvider

val instrumentation = InstrumentationRegistry.getInstrumentation()
val args: Bundle = InstrumentationRegistry.getArguments()       // -e key value extras
val targetContext: Context = ApplicationProvider.getApplicationContext()
val testContext: Context = instrumentation.context             // package context of the test APK

InstrumentationRegistry.getArguments() exposes the -e key/value pairs from am instrument -e key value, e.g. -e size small -e numShards 4. The canonical list of supported keys is in runner-1.7.0/androidx/test/internal/runner/RunnerArgs.java lines 54-99 (see tasks/research/R1-androidx-test-core.md lines 295-336).

• 5. Annotate tests with @SmallTest / @MediumTest / @LargeTest from androidx.test.filters. Used together with am instrument -e size small to filter by speed envelope. From the package KDocs: SmallTest ≤200ms, MediumTest ≤1000ms, LargeTest >1000ms. Sibling annotations: @FlakyTest, @RequiresDevice, @Suppress.

import androidx.test.filters.SmallTest
import androidx.test.filters.SdkSuppress

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

@Test
@SdkSuppress(minSdkVersion = 26)
fun usesApi26OnlyApi() { /* ... */ }

@SdkSuppress(minSdkVersion, maxSdkVersion, excludedSdks, codeName) lives at runner-1.7.0/androidx/test/filters/SdkSuppress.java:39-58. Tests outside the API range are skipped (assumption-failure, exit code -4), not failed.

• 6. Add Test Orchestrator on androidTestUtil — NOT androidTestImplementation. This is the most common single misconfiguration in the runner stack. Test Orchestrator runs each @Test in its own instrumentation process so a crash kills only that one test, with optional clearPackageData between tests:

dependencies {
    androidTestUtil("androidx.test:orchestrator:1.6.1")  // installs orchestrator APK on device
    androidTestUtil("androidx.test:services:1.6.0")      // required for clearPackageData
}

android {
    testOptions {
        execution = "ANDROIDX_TEST_ORCHESTRATOR"
    }
    defaultConfig {
        testInstrumentationRunnerArguments["clearPackageData"] = "true"
    }
}

androidTestUtil is a special AGP configuration that installs helper APKs on the device prior to running tests. Putting orchestrator on androidTestImplementation compiles, silently does nothing, and the test still runs in a single shared process. See tasks/research/R1-androidx-test-core.md lines 683-687.

• 7. Grant runtime permissions with GrantPermissionRule.grant(...) instead of adb shell pm grant. The rule ships in androidx.test:rules and grants permissions for the duration of the test class:

import androidx.test.rule.GrantPermissionRule
import org.junit.Rule

@get:Rule
val permissionRule: GrantPermissionRule = GrantPermissionRule.grant(
    android.Manifest.permission.ACCESS_FINE_LOCATION,
    android.Manifest.permission.RECORD_AUDIO,
)

The rule is implemented at rules-1.7.0/androidx/test/rule/GrantPermissionRule.java. On API 23+ it uses UiAutomation.grantRuntimePermission; on older devices the permission must already be granted in the manifest (the rule is a no-op).

• 8. Disable animations for hermetic runs. testOptions { animationsDisabled = true } toggles window_animation_scale, transition_animation_scale, and animator_duration_scale to 0 for the duration of the test run, then restores the previous values on teardown. Without this, tap-to-focus, ripple, and Activity transitions race with assertions.

• 9. (Optional) Order multiple @Rules with @Rule(order = N). Lower order numbers evaluate outer first. Hilt requires @HiltAndroidRule at order = 0:

@get:Rule(order = 0) val hiltRule = HiltAndroidRule(this)
@get:Rule(order = 1) val activityRule = ActivityScenarioRule(LoginActivity::class.java)

• 10. Run. From the host:

./gradlew :app:connectedDebugAndroidTest
# or via adb directly:
adb shell am instrument -w -r \
  -e size small \
  -e clearPackageData true \
  com.example.app.test/androidx.test.runner.AndroidJUnitRunner

-w (wait) is required for the exit code to be meaningful. Without it, $? is 0 even on test failure. See docs/CORPUS.md I.5.