插桩测试套件

插桩测试套件会将设备测试打包到模块默认 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)或更高版本的设备。如需收集插桩套件或混合套件的覆盖率,请完成以下步骤:

  1. 在 gradle.properties 文件中设置 android.experimental.androidTest.coverage.useOnDeviceAgent=true 属性。
  2. 在套件上将 codeCoverage 属性设置为 true。
  3. 如果连接了多个设备,请使用 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