Android Gradle 插件中的测试套件

借助 Android Gradle 插件 (AGP),您可以在模块的 testOptions 代码块中将测试整理到命名的测试套件中。每个套件都会定义自己的源代码集、依赖项、JUnit 平台测试引擎和目标 build 变体。

为何要使用测试套件

默认情况下,Android 模块会提供一个用于本地单元测试的 test 源代码集和一个用于插桩测试的 androidTest 源代码集。测试套件将测试组织与这两个源代码集分离开来,以便您执行以下操作:

  • 按用途区分测试:将单元测试、Robolectric 测试、界面测试、屏幕截图测试和备份测试放在专用的 src/{suiteName}/ 目录中,而不是将它们混在 src/test/ 或 src/androidTest/ 目录中。
  • 隔离依赖项和引擎:配置每个套件的类路径和 JUnit 平台测试引擎,而无需向应用或 testImplementation 和 androidTestImplementation 配置添加依赖项。
  • 针对特定变体和设备:为每个套件选择 build 变体和设备,以便在本地运行快速检查,并在持续集成中运行较长的套件。

套房类型

AGP 包含用于专用工作流的内置测试套件,以及用于自定义套件的 AgpTestSuite 接口。下表列出了可用的套件类型:

套件类型 DSL 容器 用途
单元测试套件 testOptions.customSuites 使用 hostJar 代码块在本地 JVM 上运行 JUnit 5、JUnit 4 或 Robolectric 测试。
插桩测试套件 testOptions.customSuites 使用 testApk 代码块和 android-test-engine 测试引擎在连接的设备或 build 管理的设备上运行设备测试。
使用测试套件进行屏幕截图测试 testOptions.screenshotTests 在主机上渲染并比较 @PreviewTest 个 Compose 预览。
自动备份和恢复测试 testOptions.backupTests 验证本地、云端和设备到设备传输的应用数据。
Android Studio 历程 testOptions.customSuites 在已连接的设备上运行 AI 驱动的 XML 用户体验历程。
自定义资产或混合套件 testOptions.customSuites 使用自定义引擎运行静态测试定义,或将 hostJar、testApk 和 assets 块合并到一个套件中。

要求

如需使用自定义测试套件,请确保您的项目满足以下要求:

  • Android Studio Rabbit 3 Canary 3 或更高版本
  • AGP 9.6.0-alpha03 或更高版本
  • Gradle 9.7.1 或更高版本以及 JDK 17 或更高版本
  • com.android.application 或 com.android.library 模块

com.android.kotlin.multiplatform.library 或 com.android.test 模块不支持测试套件。如需详细了解预览版匹配,请参阅与 Android Gradle 插件预览版的兼容性。

设置自定义测试套件

如需查看分步设置指南,请参阅单元测试套件和插桩测试套件。如需定义您自己的自定义套件,请先在项目的 gradle.properties 文件中启用测试套件:

android.experimental.testSuiteSupport=true

接下来,在模块的 build.gradle.kts 文件的 testOptions.customSuites 代码块中声明一个套件。在 targets 块中指定 targetVariants 属性、一个或多个来源块、useJunitEngine 块以及至少一个目标:

import com.android.build.api.dsl.AgpTestSuiteInputParameters

android {
    testOptions {
        customSuites {
            create("mySuite") {
                // Exact variant names to test, such as "debug" or "demoDebug".
                targetVariants += listOf("debug")

                // Add one or more blocks: hostJar {}, testApk {}, or assets {}.
                assets {}

                useJunitEngine {
                    includeEngines += listOf("my-custom-engine")
                    enginesDependencies.add(
                        "com.example:my-custom-junit-engine:1.0.0"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    // Request build and SDK artifacts read by your engine.
                    inputs += listOf(
                        AgpTestSuiteInputParameters.STATIC_FILES,
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                    )
                }

                targets {
                    create("default")
                }
            }
        }
    }
}

在自定义 TestEngine 实现中,使用 TestSuiteExecutionClient.default 属性读取 AgpTestSuiteInputParameters 枚举值和标准 TestEngineInputProperty 常量(例如 SERIAL_IDS 和 RESULTS_DIR)。

源代码集目录

每个套件的目录布局取决于它是声明一个源代码块还是组合多个源代码块。下表列出了 {module}/src/{suiteName}/ 目录下的默认路径:

来源屏蔽 单一来源套件 混合套房
hostJar kotlin/、java/、resources/ test/kotlin/、test/java/、test/resources/
testApk kotlin/、java/、res/、assets/、AndroidManifest.xml androidTest/kotlin/、androidTest/java/、androidTest/res/、androidTest/assets/、androidTest/AndroidManifest.xml
assets 套件根目录 assetsTest/

请勿重复使用内置源代码集、变种、build 类型或变体名称(例如 main、androidTest 或 debug)作为套件名称。

每个变体的控制目标

如需为特定变体启用或停用套件目标,请通过 beforeVariants 块中的 HasTestSuitesBuilder.suites 属性配置 TestSuiteTargetBuilder 接口:

androidComponents {
    beforeVariants { variantBuilder ->
        if (variantBuilder.buildType == "release") {
            variantBuilder.suites["mySuite"]
                ?.targets
                ?.get("default")
                ?.enable = false
        }
    }
}

运行套件并检查报告

AGP 会为变体、套件和目标的每种组合创建一个 Gradle 任务。下表列出了任务模式:

任务类型 命名模式 示例命令
标准套件目标 test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
具有 targetDevices 属性的目标 test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
基准更新 (requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
模块报告汇总 testAllSuites ./gradlew :app:testAllSuites
模块和依赖项汇总 testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

test、connectedCheck 和 check 任务不会运行自定义套件,除非您使用 withTestTaskProviders 方法连接它们。如需启用 testAllSuites 和 testAllSuitesWithDependencies 任务,请在 gradle.properties 文件中设置 android.experimental.reportAggregationSupport=true 属性。

每次套件运行都会将输出写入以下位置:

  • HTML 测试报告:{module}/build/reports/tests/{taskName}/index.html
  • thought JUnit XML 结果:{module}/build/test-results/{taskName}/
  • 代码覆盖率报告: {module}/build/reports/coverage/{suiteName}/index.html
  • 汇总报告:{module}/build/reports/{aggregationTask}/test-report/index.html和 coverage-report/index.html

如需生成代码覆盖率报告,请在套件中将 codeCoverage 属性设置为 true。对于 Compose 屏幕截图套件,请在 build.gradle.kts 文件中使用 testOptions.customSuites.named("{suiteName}") { codeCoverage = true } 配置该套件。

已知问题和限制

测试套件具有以下限制:

  • IDE 集成:Android Studio 不支持自定义测试套件。即使 build 配置正确,代码编辑器也可能会在套件源文件中显示未解析的引用错误。请改为使用 Gradle 从命令行构建和运行测试套件。
  • 任务缓存:测试套件任务在调用时始终会重新运行,而不会从 Gradle 构建缓存中加载。没有测试文件的套件会被跳过,并显示 NO-SOURCE 状态。