插桩测试套件会将设备测试打包到模块默认 src/androidTest/ 目录之外的隔离 testApk APK 中。使用 Android Gradle 插件 (AGP) 测试套件 DSL 配置这些测试,以便通过专用依赖项、变体和设备定位来分离界面、集成或端到端检查。
要求
如需使用插桩测试套件,请确保您的项目满足以下要求:
- Android Studio Rabbit 3 Canary 3 或更高版本
- AGP 9.6.0-alpha03 或更高版本
- Gradle 9.7.1 或更高版本以及 JDK 17 或更高版本
com.android.application或com.android.library模块- 通过 Android 调试桥 (adb) 连接的设备或模拟器,或 build 管理的设备定义
如需详细了解预览版版本匹配,请参阅与 Android Gradle 插件预览版的兼容性。
设置插桩测试套件
如需向应用或库模块添加插桩测试套件,请完成以下步骤:
启用测试套件
在项目的 gradle.properties 文件中,启用测试套件支持:
android.experimental.testSuiteSupport=true
配置套件
在模块的 build.gradle.kts 文件中,使用 testApk 和 useJunitEngine 代码块以及 AgpTestSuiteInputParameters 枚举值在 testOptions.customSuites 代码块内创建一个套件:
import com.android.build.api.dsl.AgpTestSuiteInputParameters
android {
testOptions {
// Optional: define build-managed virtual devices and device groups.
managedDevices {
localDevices {
create("api34Atd") {
// Use a device profile from Android Studio.
device = "Pixel 6"
apiLevel = 34
systemImageSource = "aosp-atd"
}
}
groups {
create("ciPhones") {
targetDevices.add(allDevices.getByName("api34Atd"))
}
}
}
customSuites {
create("androidSuite") {
targetVariants += listOf("debug")
testApk {
dependencies {
implementation("junit:junit:4.13.2")
implementation("androidx.test.ext:junit:1.2.1")
implementation("androidx.test:runner:1.6.2")
}
}
useJunitEngine {
includeEngines += listOf("android-test-engine")
// Match the engine and listener versions to your AGP
// version.
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine:9.6.0-alpha03"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine-result-listener:9.6.0-alpha03"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
inputs += listOf(
// Omit TESTED_APKS in com.android.library modules.
AgpTestSuiteInputParameters.TESTED_APKS,
AgpTestSuiteInputParameters.TEST_APKS,
AgpTestSuiteInputParameters.ADB_EXECUTABLE,
AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
)
}
targets {
// Runs on connected adb devices.
create("default")
// Optional: runs on build-managed devices or groups in
// targetDevices.
create("managed") {
targetDevices += listOf("ciPhones")
}
}
}
}
}
}
AGP 会自动配置 AndroidJUnitRunner 测试运行程序和软件包 ID,而不会从 androidTestImplementation 配置继承依赖项。如需使用自定义运行程序,请在 src/{suiteName}/AndroidManifest.xml 文件中的 instrumentation 元素上设置 android:name 属性。
创建测试
将插桩测试以及任何可选的 res/ 或 assets/ 目录或 AndroidManifest.xml 文件放在 {module}/src/{suiteName}/kotlin/ 或 java/ 目录中。例如,创建 app/src/androidSuite/kotlin/com/example/myapp/AppContextSuiteTest.kt 文件:
package com.example.myapp
import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import org.junit.Assert.assertEquals
import org.junit.Test
import org.junit.runner.RunWith
@RunWith(AndroidJUnit4::class)
class AppContextSuiteTest {
@Test
fun useAppContext() {
val appContext =
InstrumentationRegistry.getInstrumentation().targetContext
assertEquals("com.example.myapp", appContext.packageName)
}
}
结合使用单元测试和插桩测试
如需在单个 Gradle 任务中运行本地 JVM 测试和插桩设备测试,请在一个套件中同时声明 hostJar 和 testApk 代码块。将主机测试放在 src/{suiteName}/test/ 目录中,将设备测试放在 src/{suiteName}/androidTest/ 目录中:
import com.android.build.api.dsl.AgpTestSuiteInputParameters
android {
testOptions {
customSuites {
create("combinedSuite") {
targetVariants += listOf("debug")
hostJar {
dependencies {
implementation(
"org.junit.jupiter:junit-jupiter-api:5.10.2"
)
}
}
testApk {
dependencies {
implementation("junit:junit:4.13.2")
implementation("androidx.test.ext:junit:1.2.1")
implementation("androidx.test:runner:1.6.2")
}
}
useJunitEngine {
includeEngines += listOf(
"junit-jupiter",
"android-test-engine",
)
enginesDependencies.add(
"org.junit.jupiter:junit-jupiter-engine:5.10.2"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine:9.6.0-alpha03"
)
enginesDependencies.add(
"com.android.tools.androidtest:" +
"android-test-engine-result-listener:9.6.0-alpha03"
)
enginesDependencies.add(
"org.junit.platform:junit-platform-launcher:1.10.2"
)
inputs += listOf(
// Omit TESTED_APKS in com.android.library modules.
AgpTestSuiteInputParameters.TESTED_APKS,
AgpTestSuiteInputParameters.TEST_APKS,
AgpTestSuiteInputParameters.ADB_EXECUTABLE,
AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
)
}
targets {
create("default")
}
}
}
}
}
运行测试并收集覆盖率
使用 Gradle 运行插桩套件、过滤测试用例并生成覆盖率报告。
在已连接的设备或 build 管理的设备上运行
在每个在线 adb 设备上运行连接的目标,或运行配置了 targetDevices 属性的目标:
# Run on connected adb devices. ./gradlew :app:testDebugAndroidSuiteDefaultTestSuite# Run on the ciPhones build-managed device group. ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
过滤插桩测试
使用 Gradle 的 --tests 选项或 AndroidJUnitRunner 参数过滤测试:
./gradlew :app:testDebugAndroidSuiteDefaultTestSuite \
--tests "com.example.myapp.AppContextSuiteTest.useAppContext"您还可以使用项目属性(例如 -Pandroid.testInstrumentationRunnerArguments.size=small)在命令行中传递 AndroidJUnitRunner 参数。如需在 useJunitEngine 代码块中设置默认运行程序参数,请调用 addInputProperty 方法,例如 addInputProperty("android-test.instrumentation-args", "size=small")。
收集设备端代码覆盖率
设备端代码覆盖率需要可调试 build 和搭载 Android 9(API 级别 28)或更高版本的设备。如需收集插桩套件或混合套件的覆盖率,请完成以下步骤:
- 在
gradle.properties文件中设置android.experimental.androidTest.coverage.useOnDeviceAgent=true属性。 - 在套件上将
codeCoverage属性设置为true。 - 如果连接了多个设备,请使用
ANDROID_SERIAL环境变量定位到一个设备。
如需详细了解代理要求,请参阅查看代码覆盖率报告(使用设备端代理)。
检查报告
测试运行完成后,AGP 会在以下路径中生成输出:
- HTML 测试报告:
{module}/build/reports/tests/{taskName}/index.html - thought
JUnit XML 结果:
{module}/build/test-results/{taskName}/ - 每个设备的 XML 和 logcat:
{module}/build/intermediates/{variant}/{taskName}/results/ - 代码覆盖率报告:
{module}/build/reports/coverage/{suiteName}/index.html