running-instrumented-tests-with-androidjunit4
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseRunning 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 import, the orchestrator on instead of , the deprecated instead of . This skill encodes the exact dependency matrix, the runner Gradle config, and the supporting annotations and rules.
AndroidJUnit4androidTestImplementationandroidTestUtilandroidx.test.InstrumentationRegistryandroidx.test.platform.app.InstrumentationRegistry当 Runner 技术栈配置错误时,插桩测试会在执行任何断言之前失败:使用了已弃用的 import、把 orchestrator 放在 而不是 ,或者使用了已弃用的 而不是 。此 skill 记录了确切的依赖矩阵、runner 的 Gradle 配置,以及配套的注解和规则。
AndroidJUnit4androidTestImplementationandroidTestUtilandroidx.test.InstrumentationRegistryandroidx.test.platform.app.InstrumentationRegistryWhen to use this skill
何时使用此 skill
- The IDE flags as
androidx.test.runner.AndroidJUnit4, or the test compiles but emits the deprecation warning.@Deprecated - returns
am instrumentorINSTRUMENTATION_FAILED: <pkg>/androidx.test.runner.AndroidJUnitRunner.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 smallvia-e package com.fooand the test ignores it —am instrumentis unwired.RunnerArgs - A test needs /
ACCESS_FINE_LOCATIONetc. and the user is hand-rolling permission grants fromRECORD_AUDIO.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 or driving lifecycle — see
Activity.../../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 (or
com.android.application).com.android.library - A source set on disk (
src/androidTest/should resolve)../gradlew :module:connectedDebugAndroidTest - 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 5 requires a Vintage engine bridge and is out of scope.
junit:junit:4.13.2
- Android Gradle Plugin 模块(或
com.android.application)。com.android.library - 磁盘上存在 源集(
src/androidTest/应该可以解析)。./gradlew :module:connectedDebugAndroidTest - 模拟器或物理设备(或 Firebase Test Lab / managed devices)——runner 无法在 JVM 上执行。
- 测试类路径上有 JUnit 4();JUnit 5 需要 Vintage engine bridge,不在本文范围内。
junit:junit:4.13.2
Workflow
工作流程
- 1. Pin the AndroidX Test artifacts on . These are the canonical 2026 GA versions per
androidTestImplementationH.1:docs/CORPUS.md
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:junitAndroidJUnit4ActivityScenarioRuleandroidx.test:runnerAndroidJUnit4tasks/research/R1-androidx-test-core.md- 2. Set the in the module's
testInstrumentationRunner. The runner FQCN isandroid.defaultConfig— note this is the runner class, distinct from the deprecatedandroidx.test.runner.AndroidJUnitRunnertest runner annotation. FromAndroidJUnit4lines 270-289:tasks/research/R1-androidx-test-core.md
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 from
@RunWith(AndroidJUnit4::class). This is the only correct import:androidx.test.ext.junit.runners
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 is at . It still works at runtime but the IDE warns and codemods will replace it.
androidx.test.runner.AndroidJUnit4@Deprecatedrunner-1.7.0/androidx/test/runner/AndroidJUnit4.java:43-44- 4. Read instrumentation arguments via . The legacy
androidx.test.platform.app.InstrumentationRegistry(noandroidx.test.InstrumentationRegistry) isplatform.appand@Deprecated'd to the canonical class — see@InlineMelines 142-153:tasks/research/R1-androidx-test-core.md
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 APKInstrumentationRegistry.getArguments()-eam instrument -e key value-e size small -e numShards 4runner-1.7.0/androidx/test/internal/runner/RunnerArgs.javatasks/research/R1-androidx-test-core.md- 5. Annotate tests with /
@SmallTest/@MediumTestfrom@LargeTest. Used together withandroidx.test.filtersto filter by speed envelope. From the package KDocs:am instrument -e size small≤200ms,SmallTest≤1000ms,MediumTest>1000ms. Sibling annotations:LargeTest,@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-4- 6. Add Test Orchestrator on — NOT
androidTestUtil. This is the most common single misconfiguration in the runner stack. Test Orchestrator runs eachandroidTestImplementationin its own instrumentation process so a crash kills only that one test, with optional@Testbetween tests: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"
}
}androidTestUtilandroidTestImplementationtasks/research/R1-androidx-test-core.md- 7. Grant runtime permissions with instead of
GrantPermissionRule.grant(...). The rule ships inadb shell pm grantand grants permissions for the duration of the test class: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,
)The rule is implemented at . On API 23+ it uses ; on older devices the permission must already be granted in the manifest (the rule is a no-op).
rules-1.7.0/androidx/test/rule/GrantPermissionRule.javaUiAutomation.grantRuntimePermission-
8. Disable animations for hermetic runs.toggles
testOptions { animationsDisabled = true },window_animation_scale, andtransition_animation_scaletoanimator_duration_scalefor 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.0 -
9. (Optional) Order multiples with
@Rule. Lower order numbers evaluate outer first. Hilt requires@Rule(order = N)at@HiltAndroidRule: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. 在 上锁定 AndroidX Test artifacts。 根据
androidTestImplementationH.1,以下是规范的 2026 GA 版本:docs/CORPUS.md
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:junitAndroidJUnit4ActivityScenarioRuleandroidx.test:runnerAndroidJUnit4tasks/research/R1-androidx-test-core.md- 2. 在模块的 中设置
android.defaultConfig。 runner 的 FQCN 是testInstrumentationRunner——请注意,这是 runner 类,不同于已弃用的androidx.test.runner.AndroidJUnitRunner测试 runner 注解。根据AndroidJUnit4第 270-289 行:tasks/research/R1-androidx-test-core.md
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标注测试类。 这是唯一正确的 import:@RunWith(AndroidJUnit4::class)
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.AndroidJUnit4runner-1.7.0/androidx/test/runner/AndroidJUnit4.java:43-44@Deprecated- 4. 通过 读取 instrumentation 参数。 旧的
androidx.test.platform.app.InstrumentationRegistry(不含androidx.test.InstrumentationRegistry)被标记为platform.app且使用了@Deprecated,指向规范类——参见@InlineMe第 142-153 行:tasks/research/R1-androidx-test-core.md
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 APKInstrumentationRegistry.getArguments()am instrument -e key value-e-e size small -e numShards 4runner-1.7.0/androidx/test/internal/runner/RunnerArgs.javatasks/research/R1-androidx-test-core.md- 5. 使用来自 的
androidx.test.filters/@SmallTest/@MediumTest标注测试。 可与@LargeTest一起使用,按速度范围进行筛选。根据 package KDocs:am instrument -e size small≤200ms,SmallTest≤1000ms,MediumTest>1000ms。同类注解包括:LargeTest、@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-4- 6. 将 Test Orchestrator 添加到 ——不要放到
androidTestUtil。 这是 runner 技术栈中最常见的单一配置错误。Test Orchestrator 会让每个androidTestImplementation在自己的 instrumentation 进程中运行,因此崩溃只会终止该测试,并可在测试之间选择性地执行@Test: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"
}
}androidTestUtilandroidTestImplementationtasks/research/R1-androidx-test-core.md- 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,
)该规则实现于 。在 API 23 及更高版本上,它使用 ;在较旧的设备上,权限必须已在 manifest 中授予(该规则不会执行任何操作)。
rules-1.7.0/androidx/test/rule/GrantPermissionRule.javaUiAutomation.grantRuntimePermission-
8. 为 hermetic 运行禁用动画。会在测试运行期间将
testOptions { animationsDisabled = true }、window_animation_scale和transition_animation_scale切换为animator_duration_scale,随后在 teardown 时恢复之前的值。否则,tap-to-focus、ripple 和 Activity 转换可能与断言产生竞态。0 -
9.(可选)使用排列多个
@Rule(order = N)。 较小的 order 编号会最先作为外层规则求值。Hilt 要求@Rule的@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:connectedDebugAndroidTestor 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
-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
-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
AndroidJUnit4模式:错误 vs 正确——AndroidJUnit4
import
AndroidJUnit4kotlin
// 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 FooTestkotlin
// 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 FooTestPattern: WRONG vs RIGHT — InstrumentationRegistry
import
InstrumentationRegistry模式:错误 vs 正确——InstrumentationRegistry
import
InstrumentationRegistrykotlin
// 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模式:通过 RunnerArgs
在运行时筛选测试
RunnerArgsbash
undefinedbash
undefinedRun 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
-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
-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
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
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 for
androidx.test.ext.junit.runners.AndroidJUnit4. The@RunWith(...)form isandroidx.test.runner.AndroidJUnit4.@Deprecated - MUST use . The bare
androidx.test.platform.app.InstrumentationRegistryisandroidx.test.InstrumentationRegistry.@Deprecated - MUST put on
androidx.test:orchestrator, never onandroidTestUtil. Putting it on the wrong configuration fails silently.androidTestImplementation - MUST set (the runner class — that one is not deprecated, only the test-runner annotation is).
testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" - MUST pass to
-wso the exit code reflects test result. Without it,am instrumentis meaningless.$? - MUST NOT call to wait for instrumentation lifecycle (
Thread.sleep,onCreate). UseonStart(seeActivityScenario.moveToState) or an../../scenarios/launching-activities-with-activityscenario/SKILL.md.IdlingResource - MUST NOT grant permissions via raw from inside the test — use
adb shell pm grantso the grant scopes to the test class and reverts cleanly.GrantPermissionRule.grant(...) - MUST NOT use — it is
@Rule public ActivityTestRule. Use@Deprecated.@get:Rule val rule = ActivityScenarioRule(...) - PREFERRED: annotate every instrumentation test class with /
@SmallTest/@MediumTestso CI shards can filter by size.@LargeTest - PREFERRED: keep even when individual tests don't seem to need it; ripple/transition flake silently corrupts unrelated tests.
testOptions.animationsDisabled = true
- 对 必须使用
@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 - 必须设置 (这是 runner 类——只有测试 runner 注解被弃用,该类没有弃用)。
testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner" - 向 传递参数时必须使用
am instrument,使退出码反映测试结果。没有它,-w将失去意义。$? - 不得调用 等待 instrumentation 生命周期(
Thread.sleep、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,以便 CI 按大小筛选分片。@LargeTest - **首选:**即使单个测试看起来不需要,也应保持 ;ripple/transition flake 会悄无声息地破坏无关测试。
testOptions.animationsDisabled = true
Verification
验证
- runs without
./gradlew :<module>:connectedDebugAndroidTestorTest runner not found.INSTRUMENTATION_FAILED - No source file imports or
androidx.test.runner.AndroidJUnit4(legacy paths).androidx.test.InstrumentationRegistry - returns nothing — orchestrator is on
grep -r "androidTestImplementation.*orchestrator" build.gradle*.androidTestUtil - returns a non-zero exit code on test failure.
adb shell am instrument -w -r -e size small <pkg>.test/androidx.test.runner.AndroidJUnitRunner - If orchestrator is enabled, shows per-test process spawning.
adb logcat | grep AndroidTestOrchestrator - is set in the module's
testOptions.animationsDisabled = trueblock.android - Any runtime permission required by tests has a (not a manual
@get:Rule val rule = GrantPermissionRule.grant(...)).adb shell pm grant
- 运行时不出现
./gradlew :<module>:connectedDebugAndroidTest或Test runner not found。INSTRUMENTATION_FAILED - 没有任何源文件导入 或
androidx.test.runner.AndroidJUnit4(旧版路径)。androidx.test.InstrumentationRegistry - 没有返回结果——orchestrator 位于
grep -r "androidTestImplementation.*orchestrator" build.gradle*中。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
- lines 41-44 —
runner-1.7.0/androidx/test/runner/AndroidJUnit4.java.@Deprecated public final class AndroidJUnit4 extends Runner - line 49 — current non-deprecated runner; delegates to Robolectric on JVM and
junit-1.3.0/androidx/test/ext/junit/runners/AndroidJUnit4.javaon device.AndroidJUnit4ClassRunner - lines 270-372 — the runner class
runner-1.7.0/androidx/test/runner/AndroidJUnitRunner.javainvokes; lifecycle and orchestrator wait logic.am instrument - lines 54-99 — canonical list of every
runner-1.7.0/androidx/test/internal/runner/RunnerArgs.javakey the runner accepts.-e - line 34 —
monitor-1.8.0/androidx/test/InstrumentationRegistry.javalegacy registry; every member@Deprecated'd to the platform.app form.@InlineMe - — current canonical registry.
monitor-1.8.0/androidx/test/platform/app/InstrumentationRegistry.java - lines 1-100 —
rules-1.7.0/androidx/test/rule/GrantPermissionRule.java.static GrantPermissionRule grant(String...) - lines 39-58 —
runner-1.7.0/androidx/test/filters/SdkSuppress.java/minSdkVersion/maxSdkVersion/excludedSdks.codeName - — full runner / test-core deep dive (lines 269-740 for runner; 481-490 for the dual-
tasks/research/R1-androidx-test-core.mdconfusion).AndroidJUnit4 - Section H — instrumentation library coordinates and deprecation table.
docs/CORPUS.md - Sibling skill: — running these tests on emulators Gradle provisions/boots/tears down (reproducible in CI).
../../managed-devices/running-tests-on-gradle-managed-devices/SKILL.md - Cross-set: — invoking the runner directly via
../../../adb/tests/running-instrumented-tests-via-adb/SKILL.md.adb shell am instrument -w -r - Cross-set: — if the module still uses the legacy
../../../platform/legacy/migrating-from-android-test-classes/SKILL.mdclasses /android.test.*, migrate it onto this runner stack first.InstrumentationTestRunner
- 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
- 第 41-44 行 —
runner-1.7.0/androidx/test/runner/AndroidJUnit4.java。@Deprecated public final class AndroidJUnit4 extends Runner - 第 49 行 — 当前未弃用的 runner;在 JVM 上委托给
junit-1.3.0/androidx/test/ext/junit/runners/AndroidJUnit4.java,在设备上委托给Robolectric。AndroidJUnit4ClassRunner - 第 270-372 行 —
runner-1.7.0/androidx/test/runner/AndroidJUnitRunner.java调用的 runner 类;包含生命周期和 orchestrator 等待逻辑。am instrument - 第 54-99 行 — runner 支持的每个
runner-1.7.0/androidx/test/internal/runner/RunnerArgs.java键的规范列表。-e - 第 34 行 — 已弃用的旧版 registry;每个成员都通过
monitor-1.8.0/androidx/test/InstrumentationRegistry.java指向 platform.app 形式。@InlineMe - — 当前规范的 registry。
monitor-1.8.0/androidx/test/platform/app/InstrumentationRegistry.java - 第 1-100 行 —
rules-1.7.0/androidx/test/rule/GrantPermissionRule.java。static GrantPermissionRule grant(String...) - 第 39-58 行 —
runner-1.7.0/androidx/test/filters/SdkSuppress.java/minSdkVersion/maxSdkVersion/excludedSdks。codeName - — 对 runner / test-core 的深入分析(第 269-740 行介绍 runner;第 481-490 行介绍
tasks/research/R1-androidx-test-core.md混淆问题)。AndroidJUnit4 - Section H — instrumentation library 坐标和弃用对照表。
docs/CORPUS.md - 同类 skill:— 在 Gradle 预配、启动和销毁的模拟器上运行这些测试(可复现的 CI 环境)。
../../managed-devices/running-tests-on-gradle-managed-devices/SKILL.md - 跨领域 skill:— 通过
../../../adb/tests/running-instrumented-tests-via-adb/SKILL.md直接调用 runner。adb shell am instrument -w -r - 跨领域 skill:— 如果模块仍在使用旧版
../../../platform/legacy/migrating-from-android-test-classes/SKILL.md类 /android.test.*,请先将测试迁移到当前 runner 技术栈。InstrumentationTestRunner