running-instrumented-tests-with-androidjunit4

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Running Instrumented Tests with AndroidJUnit4 — Get the Runner Stack Right

使用 AndroidJUnit4 运行插桩测试——配置正确的 Runner 技术栈

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.
当 Runner 技术栈配置错误时,插桩测试会在执行任何断言之前失败:使用了已弃用的
AndroidJUnit4
import、把 orchestrator 放在
androidTestImplementation
而不是
androidTestUtil
,或者使用了已弃用的
androidx.test.InstrumentationRegistry
而不是
androidx.test.platform.app.InstrumentationRegistry
。此 skill 记录了确切的依赖矩阵、runner 的 Gradle 配置,以及配套的注解和规则。

When to use this skill

何时使用此 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.
  • IDE 将
    androidx.test.runner.AndroidJUnit4
    标记为
    @Deprecated
    ,或者测试可以编译但会发出弃用警告。
  • am instrument
    返回
    INSTRUMENTATION_FAILED: <pkg>/androidx.test.runner.AndroidJUnitRunner
    或
    Test runner not found
    。
  • Test Orchestrator 已在 Gradle 中配置,但测试仍共享单个 instrumentation 进程(orchestrator 被静默禁用)。
  • 用户通过
    am instrument
    传递
    -e size small
    /
    -e package com.foo
    ,但测试忽略了这些参数——
    RunnerArgs
    未接入。
  • 测试需要
    ACCESS_FINE_LOCATION
    /
    RECORD_AUDIO
    等权限,而用户正在手工编写来自
    adb
    的权限授予逻辑。
  • 用户希望跳过 API 26 以下的测试,并正在查找相应的注解。

When NOT to use this skill

何时不应使用此 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
    .
  • 用户正在启动
    Activity
    或驱动生命周期——参见
    ../../scenarios/launching-activities-with-activityscenario/SKILL.md
    。
  • 用户正在与 Views 交互——参见
    ../../espresso/writing-espresso-tests/SKILL.md
    。
  • 用户正在驱动系统 UI 或其他应用——参见
    ../../uiautomator/cross-app-tests-with-uiautomator/SKILL.md
    。
  • 用户运行 JVM(Robolectric / pure JUnit)测试——参见
    ../../../jvm-tests/runner/configuring-junit4-on-android/SKILL.md
    。
  • 用户正在决定首先应该测试什么——参见
    ../../../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.
  • Android Gradle Plugin 模块(
    com.android.application
    或
    com.android.library
    )。
  • 磁盘上存在
    src/androidTest/
    源集(
    ./gradlew :module:connectedDebugAndroidTest
    应该可以解析)。
  • 模拟器或物理设备(或 Firebase Test Lab / managed devices)——runner 无法在 JVM 上执行。
  • 测试类路径上有 JUnit 4(
    junit:junit:4.13.2
    );JUnit 5 需要 Vintage engine bridge,不在本文范围内。

Workflow

工作流程

  • 1. Pin the AndroidX Test artifacts on
    androidTestImplementation
    .
    These are the canonical 2026 GA versions per
    docs/CORPUS.md
    H.1:
kotlin
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:
kotlin
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:
kotlin
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:
kotlin
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
    .
kotlin
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:
kotlin
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:
kotlin
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
    @Rule
    s with
    @Rule(order = N)
    .
    Lower order numbers evaluate outer first. Hilt requires
    @HiltAndroidRule
    at
    order = 0
    :
kotlin
@get:Rule(order = 0) val hiltRule = HiltAndroidRule(this)
@get:Rule(order = 1) val activityRule = ActivityScenarioRule(LoginActivity::class.java)
  • 10. Run. From the host:
bash
./gradlew :app:connectedDebugAndroidTest
  • 1. 在
    androidTestImplementation
    上锁定 AndroidX Test artifacts。
    根据
    docs/CORPUS.md
    H.1,以下是规范的 2026 GA 版本:
kotlin
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
是提供未弃用的
AndroidJUnit4
runner 和未弃用的
ActivityScenarioRule
的 artifact。
androidx.test:runner
仍会附带旧的
AndroidJUnit4
(已弃用)——切勿从那里 import。参见
tasks/research/R1-androidx-test-core.md
第 481-490 行。
  • 2. 在模块的
    android.defaultConfig
    中设置
    testInstrumentationRunner
    。
    runner 的 FQCN 是
    androidx.test.runner.AndroidJUnitRunner
    ——请注意,这是 runner 类,不同于已弃用的
    AndroidJUnit4
    测试 runner 注解。根据
    tasks/research/R1-androidx-test-core.md
    第 270-289 行:
kotlin
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. 使用来自
    androidx.test.ext.junit.runners
    的
    @RunWith(AndroidJUnit4::class)
    标注测试类。
    这是唯一正确的 import:
kotlin
import androidx.test.ext.junit.runners.AndroidJUnit4
import org.junit.Test
import org.junit.runner.RunWith

@RunWith(AndroidJUnit4::class)
class LoginActivityTest {
    @Test fun loginSucceeds() { /* ... */ }
}
androidx.test.runner.AndroidJUnit4
在
runner-1.7.0/androidx/test/runner/AndroidJUnit4.java:43-44
处被标记为
@Deprecated
。它在运行时仍然可用,但 IDE 会发出警告,codemod 也会将其替换。
  • 4. 通过
    androidx.test.platform.app.InstrumentationRegistry
    读取 instrumentation 参数。
    旧的
    androidx.test.InstrumentationRegistry
    (不含
    platform.app
    )被标记为
    @Deprecated
    且使用了
    @InlineMe
    ,指向规范类——参见
    tasks/research/R1-androidx-test-core.md
    第 142-153 行:
kotlin
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()
会暴露来自
am instrument -e key value
的
-e
键值对,例如
-e size small -e numShards 4
。支持的键的规范列表位于
runner-1.7.0/androidx/test/internal/runner/RunnerArgs.java
第 54-99 行(参见
tasks/research/R1-androidx-test-core.md
第 295-336 行)。
  • 5. 使用来自
    androidx.test.filters
    的
    @SmallTest
    /
    @MediumTest
    /
    @LargeTest
    标注测试。
    可与
    am instrument -e size small
    一起使用,按速度范围进行筛选。根据 package KDocs:
    SmallTest
    ≤200ms,
    MediumTest
    ≤1000ms,
    LargeTest
    >1000ms。同类注解包括:
    @FlakyTest
    、
    @RequiresDevice
    、
    @Suppress
    。
kotlin
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)
位于
runner-1.7.0/androidx/test/filters/SdkSuppress.java:39-58
。API 范围之外的测试会被跳过(assumption-failure,退出码为
-4
),而不是判定为失败。
  • 6. 将 Test Orchestrator 添加到
    androidTestUtil
    ——不要放到
    androidTestImplementation
    。
    这是 runner 技术栈中最常见的单一配置错误。Test Orchestrator 会让每个
    @Test
    在自己的 instrumentation 进程中运行,因此崩溃只会终止该测试,并可在测试之间选择性地执行
    clearPackageData
    :
kotlin
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
是 AGP 的特殊 configuration,会在运行测试前将辅助 APK 安装到设备上。将 orchestrator 放在
androidTestImplementation
中仍可编译,但会静默失效,测试依然在单个共享进程中运行。参见
tasks/research/R1-androidx-test-core.md
第 683-687 行。
  • 7. 使用
    GrantPermissionRule.grant(...)
    授予运行时权限,而不是
    adb shell pm grant
    。
    该规则随
    androidx.test:rules
    提供,并会在整个测试类期间授予权限:
kotlin
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,
)
该规则实现于
rules-1.7.0/androidx/test/rule/GrantPermissionRule.java
。在 API 23 及更高版本上,它使用
UiAutomation.grantRuntimePermission
;在较旧的设备上,权限必须已在 manifest 中授予(该规则不会执行任何操作)。
  • 8. 为 hermetic 运行禁用动画。
    testOptions { animationsDisabled = true }
    会在测试运行期间将
    window_animation_scale
    、
    transition_animation_scale
    和
    animator_duration_scale
    切换为
    0
    ,随后在 teardown 时恢复之前的值。否则,tap-to-focus、ripple 和 Activity 转换可能与断言产生竞态。
  • 9.(可选)使用
    @Rule(order = N)
    排列多个
    @Rule
    。
    较小的 order 编号会最先作为外层规则求值。Hilt 要求
    @HiltAndroidRule
    的
    order = 0
    :
kotlin
@get:Rule(order = 0) val hiltRule = HiltAndroidRule(this)
@get:Rule(order = 1) val activityRule = ActivityScenarioRule(LoginActivity::class.java)
  • 10. 运行。 在主机端执行:
bash
./gradlew :app:connectedDebugAndroidTest

or via adb directly:

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.
adb shell am instrument -w -r
-e size small
-e clearPackageData true
com.example.app.test/androidx.test.runner.AndroidJUnitRunner

`-w`(wait)是获得有意义退出码所必需的。没有它,即使测试失败,`$?` 也会是 `0`。参见 `docs/CORPUS.md` I.5。

Patterns

模式

Pattern: WRONG vs RIGHT —
AndroidJUnit4
import

模式:错误 vs 正确——
AndroidJUnit4
import

kotlin
// WRONG
import androidx.test.runner.AndroidJUnit4   // @Deprecated since androidx.test:runner 1.x
@RunWith(AndroidJUnit4::class)
class FooTest
// WRONG because: this class is @Deprecated at runner-1.7.0/.../AndroidJUnit4.java:43-44.
// The IDE flags it; codemods replace it; the doc explicitly redirects to ext.junit.
kotlin
// RIGHT
import androidx.test.ext.junit.runners.AndroidJUnit4
@RunWith(AndroidJUnit4::class)
class FooTest
kotlin
// WRONG
import androidx.test.runner.AndroidJUnit4   // @Deprecated since androidx.test:runner 1.x
@RunWith(AndroidJUnit4::class)
class FooTest
// WRONG because: this class is @Deprecated at runner-1.7.0/.../AndroidJUnit4.java:43-44.
// The IDE flags it; codemods replace it; the doc explicitly redirects to ext.junit.
kotlin
// RIGHT
import androidx.test.ext.junit.runners.AndroidJUnit4
@RunWith(AndroidJUnit4::class)
class FooTest

Pattern: WRONG vs RIGHT —
InstrumentationRegistry
import

模式:错误 vs 正确——
InstrumentationRegistry
import

kotlin
// WRONG
import androidx.test.InstrumentationRegistry             // @Deprecated, every member @InlineMe'd
val ctx = InstrumentationRegistry.getTargetContext()     // returns target package context, NOT the application
// WRONG because: monitor-1.8.0/androidx/test/InstrumentationRegistry.java:34 is @Deprecated.
// Use androidx.test.platform.app.InstrumentationRegistry + ApplicationProvider.
kotlin
// RIGHT
import androidx.test.platform.app.InstrumentationRegistry
import androidx.test.core.app.ApplicationProvider
val instrumentation = InstrumentationRegistry.getInstrumentation()
val ctx: Context = ApplicationProvider.getApplicationContext()
kotlin
// WRONG
import androidx.test.InstrumentationRegistry             // @Deprecated, every member @InlineMe'd
val ctx = InstrumentationRegistry.getTargetContext()     // returns target package context, NOT the application
// WRONG because: monitor-1.8.0/androidx/test/InstrumentationRegistry.java:34 is @Deprecated.
// Use androidx.test.platform.app.InstrumentationRegistry + ApplicationProvider.
kotlin
// RIGHT
import androidx.test.platform.app.InstrumentationRegistry
import androidx.test.core.app.ApplicationProvider
val instrumentation = InstrumentationRegistry.getInstrumentation()
val ctx: Context = ApplicationProvider.getApplicationContext()

Pattern: WRONG vs RIGHT — Test Orchestrator configuration (THE common misconfig)

模式:错误 vs 正确——Test Orchestrator 配置(常见错误)

kotlin
// WRONG
dependencies {
    androidTestImplementation("androidx.test:orchestrator:1.6.1")
}
android.testOptions.execution = "ANDROIDX_TEST_ORCHESTRATOR"
// WRONG because: orchestrator must be installed as a separate APK on the device.
// `androidTestImplementation` puts it on the test APK classpath instead, where it does
// nothing. Tests still run in one shared process. No error, just silent inactivation.
kotlin
// RIGHT
dependencies {
    androidTestUtil("androidx.test:orchestrator:1.6.1")
    androidTestUtil("androidx.test:services:1.6.0")  // required for clearPackageData
}
android.testOptions.execution = "ANDROIDX_TEST_ORCHESTRATOR"
kotlin
// WRONG
dependencies {
    androidTestImplementation("androidx.test:orchestrator:1.6.1")
}
android.testOptions.execution = "ANDROIDX_TEST_ORCHESTRATOR"
// WRONG because: orchestrator must be installed as a separate APK on the device.
// `androidTestImplementation` puts it on the test APK classpath instead, where it does
// nothing. Tests still run in one shared process. No error, just silent inactivation.
kotlin
// RIGHT
dependencies {
    androidTestUtil("androidx.test:orchestrator:1.6.1")
    androidTestUtil("androidx.test:services:1.6.0")  // required for clearPackageData
}
android.testOptions.execution = "ANDROIDX_TEST_ORCHESTRATOR"

Pattern: filtering tests at run time via
RunnerArgs

模式:通过
RunnerArgs
在运行时筛选测试

bash
undefined
bash
undefined

Run a single method

Run a single method

adb shell am instrument -w -r
-e class com.example.LoginActivityTest#loginSucceeds
com.example.app.test/androidx.test.runner.AndroidJUnitRunner
adb shell am instrument -w -r
-e class com.example.LoginActivityTest#loginSucceeds
com.example.app.test/androidx.test.runner.AndroidJUnitRunner

Filter by size annotation

Filter by size annotation

adb shell am instrument -w -r -e size small com.example.app.test/androidx.test.runner.AndroidJUnitRunner
adb shell am instrument -w -r -e size small com.example.app.test/androidx.test.runner.AndroidJUnitRunner

Shard across N runners (CI fan-out)

Shard across N runners (CI fan-out)

adb shell am instrument -w -r -e numShards 4 -e shardIndex 0
com.example.app.test/androidx.test.runner.AndroidJUnitRunner

The full list of supported `-e` keys lives in `runner-1.7.0/androidx/test/internal/runner/RunnerArgs.java:54-99` (`class`, `package`, `notClass`, `size`, `annotation`, `notAnnotation`, `numShards`, `shardIndex`, `clearPackageData`, `coverage`, `debug`, `listener`, etc.). To consume them inside the test, read `InstrumentationRegistry.getArguments()`.
adb shell am instrument -w -r -e numShards 4 -e shardIndex 0
com.example.app.test/androidx.test.runner.AndroidJUnitRunner

支持的完整 `-e` 键列表位于 `runner-1.7.0/androidx/test/internal/runner/RunnerArgs.java:54-99`(`class`、`package`、`notClass`、`size`、`annotation`、`notAnnotation`、`numShards`、`shardIndex`、`clearPackageData`、`coverage`、`debug`、`listener` 等)。如需在测试内部读取这些参数,请使用 `InstrumentationRegistry.getArguments()`。

Mandatory rules

强制规则

  • MUST use
    androidx.test.ext.junit.runners.AndroidJUnit4
    for
    @RunWith(...)
    . The
    androidx.test.runner.AndroidJUnit4
    form is
    @Deprecated
    .
  • MUST use
    androidx.test.platform.app.InstrumentationRegistry
    . The bare
    androidx.test.InstrumentationRegistry
    is
    @Deprecated
    .
  • MUST put
    androidx.test:orchestrator
    on
    androidTestUtil
    , never on
    androidTestImplementation
    . Putting it on the wrong configuration fails silently.
  • MUST set
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    (the runner class — that one is not deprecated, only the test-runner annotation is).
  • MUST pass
    -w
    to
    am instrument
    so the exit code reflects test result. Without it,
    $?
    is meaningless.
  • MUST NOT call
    Thread.sleep
    to wait for instrumentation lifecycle (
    onCreate
    ,
    onStart
    ). Use
    ActivityScenario.moveToState
    (see
    ../../scenarios/launching-activities-with-activityscenario/SKILL.md
    ) or an
    IdlingResource
    .
  • MUST NOT grant permissions via raw
    adb shell pm grant
    from inside the test — use
    GrantPermissionRule.grant(...)
    so the grant scopes to the test class and reverts cleanly.
  • MUST NOT use
    @Rule public ActivityTestRule
    — it is
    @Deprecated
    . Use
    @get:Rule val rule = ActivityScenarioRule(...)
    .
  • PREFERRED: annotate every instrumentation test class with
    @SmallTest
    /
    @MediumTest
    /
    @LargeTest
    so CI shards can filter by size.
  • PREFERRED: keep
    testOptions.animationsDisabled = true
    even when individual tests don't seem to need it; ripple/transition flake silently corrupts unrelated tests.
  • 对
    @RunWith(...)
    必须使用
    androidx.test.ext.junit.runners.AndroidJUnit4
    。
    androidx.test.runner.AndroidJUnit4
    形式已标记为
    @Deprecated
    。
  • 必须使用
    androidx.test.platform.app.InstrumentationRegistry
    。不带
    platform.app
    的
    androidx.test.InstrumentationRegistry
    已标记为
    @Deprecated
    。
  • 必须将
    androidx.test:orchestrator
    放在
    androidTestUtil
    中,绝不能放在
    androidTestImplementation
    中。放错配置会静默失效。
  • 必须设置
    testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    (这是 runner 类——只有测试 runner 注解被弃用,该类没有弃用)。
  • 向
    am instrument
    传递参数时必须使用
    -w
    ,使退出码反映测试结果。没有它,
    $?
    将失去意义。
  • 不得调用
    Thread.sleep
    等待 instrumentation 生命周期(
    onCreate
    、
    onStart
    )。应使用
    ActivityScenario.moveToState
    (参见
    ../../scenarios/launching-activities-with-activityscenario/SKILL.md
    )或
    IdlingResource
    。
  • 不得在测试内部通过原始
    adb shell pm grant
    授予权限——应使用
    GrantPermissionRule.grant(...)
    ,使授权范围限定到测试类并干净地撤销。
  • 不得使用
    @Rule public ActivityTestRule
    ——它已标记为
    @Deprecated
    。应使用
    @get:Rule val rule = ActivityScenarioRule(...)
    。
  • **首选:**为每个 instrumentation 测试类添加
    @SmallTest
    /
    @MediumTest
    /
    @LargeTest
    ,以便 CI 按大小筛选分片。
  • **首选:**即使单个测试看起来不需要,也应保持
    testOptions.animationsDisabled = true
    ;ripple/transition flake 会悄无声息地破坏无关测试。

Verification

验证

  • ./gradlew :<module>:connectedDebugAndroidTest
    runs without
    Test runner not found
    or
    INSTRUMENTATION_FAILED
    .
  • No source file imports
    androidx.test.runner.AndroidJUnit4
    or
    androidx.test.InstrumentationRegistry
    (legacy paths).
  • grep -r "androidTestImplementation.*orchestrator" build.gradle*
    returns nothing — orchestrator is on
    androidTestUtil
    .
  • adb shell am instrument -w -r -e size small <pkg>.test/androidx.test.runner.AndroidJUnitRunner
    returns a non-zero exit code on test failure.
  • If orchestrator is enabled,
    adb logcat | grep AndroidTestOrchestrator
    shows per-test process spawning.
  • testOptions.animationsDisabled = true
    is set in the module's
    android
    block.
  • Any runtime permission required by tests has a
    @get:Rule val rule = GrantPermissionRule.grant(...)
    (not a manual
    adb shell pm grant
    ).
  • ./gradlew :<module>:connectedDebugAndroidTest
    运行时不出现
    Test runner not found
    或
    INSTRUMENTATION_FAILED
    。
  • 没有任何源文件导入
    androidx.test.runner.AndroidJUnit4
    或
    androidx.test.InstrumentationRegistry
    (旧版路径)。
  • grep -r "androidTestImplementation.*orchestrator" build.gradle*
    没有返回结果——orchestrator 位于
    androidTestUtil
    中。
  • adb shell am instrument -w -r -e size small <pkg>.test/androidx.test.runner.AndroidJUnitRunner
    在测试失败时返回非零退出码。
  • 启用 orchestrator 后,
    adb logcat | grep AndroidTestOrchestrator
    会显示按测试创建进程。
  • 模块的
    android
    块中已设置
    testOptions.animationsDisabled = true
    。
  • 测试所需的任何运行时权限都使用
    @get:Rule val rule = GrantPermissionRule.grant(...)
    (而非手动执行
    adb shell pm grant
    )。

References

参考资料

  • Android Developers — AndroidJUnitRunner overview: https://developer.android.com/training/testing/instrumented-tests/androidx-test-libraries/runner
  • Android Developers — Test Orchestrator: https://developer.android.com/training/testing/instrumented-tests/androidx-test-libraries/runner#use-android
  • AndroidX Test release notes: https://developer.android.com/jetpack/androidx/releases/test
  • runner-1.7.0/androidx/test/runner/AndroidJUnit4.java
    lines 41-44 —
    @Deprecated public final class AndroidJUnit4 extends Runner
    .
  • junit-1.3.0/androidx/test/ext/junit/runners/AndroidJUnit4.java
    line 49 — current non-deprecated runner; delegates to Robolectric on JVM and
    AndroidJUnit4ClassRunner
    on device.
  • runner-1.7.0/androidx/test/runner/AndroidJUnitRunner.java
    lines 270-372 — the runner class
    am instrument
    invokes; lifecycle and orchestrator wait logic.
  • runner-1.7.0/androidx/test/internal/runner/RunnerArgs.java
    lines 54-99 — canonical list of every
    -e
    key the runner accepts.
  • monitor-1.8.0/androidx/test/InstrumentationRegistry.java
    line 34 —
    @Deprecated
    legacy registry; every member
    @InlineMe
    'd to the platform.app form.
  • monitor-1.8.0/androidx/test/platform/app/InstrumentationRegistry.java
    — current canonical registry.
  • rules-1.7.0/androidx/test/rule/GrantPermissionRule.java
    lines 1-100 —
    static GrantPermissionRule grant(String...)
    .
  • runner-1.7.0/androidx/test/filters/SdkSuppress.java
    lines 39-58 —
    minSdkVersion
    /
    maxSdkVersion
    /
    excludedSdks
    /
    codeName
    .
  • tasks/research/R1-androidx-test-core.md
    — full runner / test-core deep dive (lines 269-740 for runner; 481-490 for the dual-
    AndroidJUnit4
    confusion).
  • docs/CORPUS.md
    Section H — instrumentation library coordinates and deprecation table.
  • Sibling skill:
    ../../managed-devices/running-tests-on-gradle-managed-devices/SKILL.md
    — running these tests on emulators Gradle provisions/boots/tears down (reproducible in CI).
  • Cross-set:
    ../../../adb/tests/running-instrumented-tests-via-adb/SKILL.md
    — invoking the runner directly via
    adb shell am instrument -w -r
    .
  • Cross-set:
    ../../../platform/legacy/migrating-from-android-test-classes/SKILL.md
    — if the module still uses the legacy
    android.test.*
    classes /
    InstrumentationTestRunner
    , migrate it onto this runner stack first.
  • Android Developers — AndroidJUnitRunner 概览:https://developer.android.com/training/testing/instrumented-tests/androidx-test-libraries/runner
  • Android Developers — Test Orchestrator:https://developer.android.com/training/testing/instrumented-tests/androidx-test-libraries/runner#use-android
  • AndroidX Test 发布说明:https://developer.android.com/jetpack/androidx/releases/test
  • runner-1.7.0/androidx/test/runner/AndroidJUnit4.java
    第 41-44 行 —
    @Deprecated public final class AndroidJUnit4 extends Runner
    。
  • junit-1.3.0/androidx/test/ext/junit/runners/AndroidJUnit4.java
    第 49 行 — 当前未弃用的 runner;在 JVM 上委托给
    Robolectric
    ,在设备上委托给
    AndroidJUnit4ClassRunner
    。
  • runner-1.7.0/androidx/test/runner/AndroidJUnitRunner.java
    第 270-372 行 —
    am instrument
    调用的 runner 类;包含生命周期和 orchestrator 等待逻辑。
  • runner-1.7.0/androidx/test/internal/runner/RunnerArgs.java
    第 54-99 行 — runner 支持的每个
    -e
    键的规范列表。
  • monitor-1.8.0/androidx/test/InstrumentationRegistry.java
    第 34 行 — 已弃用的旧版 registry;每个成员都通过
    @InlineMe
    指向 platform.app 形式。
  • monitor-1.8.0/androidx/test/platform/app/InstrumentationRegistry.java
    — 当前规范的 registry。
  • rules-1.7.0/androidx/test/rule/GrantPermissionRule.java
    第 1-100 行 —
    static GrantPermissionRule grant(String...)
    。
  • runner-1.7.0/androidx/test/filters/SdkSuppress.java
    第 39-58 行 —
    minSdkVersion
    /
    maxSdkVersion
    /
    excludedSdks
    /
    codeName
    。
  • tasks/research/R1-androidx-test-core.md
    — 对 runner / test-core 的深入分析(第 269-740 行介绍 runner;第 481-490 行介绍
    AndroidJUnit4
    混淆问题)。
  • docs/CORPUS.md
    Section H — instrumentation library 坐标和弃用对照表。
  • 同类 skill:
    ../../managed-devices/running-tests-on-gradle-managed-devices/SKILL.md
    — 在 Gradle 预配、启动和销毁的模拟器上运行这些测试(可复现的 CI 环境)。
  • 跨领域 skill:
    ../../../adb/tests/running-instrumented-tests-via-adb/SKILL.md
    — 通过
    adb shell am instrument -w -r
    直接调用 runner。
  • 跨领域 skill:
    ../../../platform/legacy/migrating-from-android-test-classes/SKILL.md
    — 如果模块仍在使用旧版
    android.test.*
    类 /
    InstrumentationTestRunner
    ,请先将测试迁移到当前 runner 技术栈。