单元测试套件

单元测试套件在模块默认 src/test/ 目录之外的隔离 hostJar 源代码集中运行本地 JVM 测试。使用 Android Gradle 插件 (AGP) 测试套件 DSL 配置这些测试,以便按变体隔离 JUnit 5、JUnit 4 或 Robolectric 测试。

要求

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

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

如需详细了解预览版版本匹配,请参阅与 Android Gradle 插件预览版的兼容性。

设置单元测试套件

如需向应用或库模块添加单元测试套件,请完成以下步骤:

启用测试套件

在项目的 gradle.properties 文件中,启用测试套件支持:

android.experimental.testSuiteSupport=true

配置套件

在模块的 build.gradle.kts 文件中,使用 hostJar 和 useJunitEngine 代码块在 testOptions.customSuites 代码块内创建一个套件:

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

                hostJar {
                    dependencies {
                        // JUnit 5 API for @org.junit.jupiter.api.Test.
                        implementation(
                            "org.junit.jupiter:junit-jupiter-api:5.10.2"
                        )
                        // Optional: JUnit 4 API for @org.junit.Test.
                        implementation("junit:junit:4.13.2")
                    }
                }

                useJunitEngine {
                    // Add "junit-jupiter" (JUnit 5), "junit-vintage" (JUnit 4),
                    // or both.
                    includeEngines += listOf("junit-jupiter", "junit-vintage")
                    enginesDependencies.add(
                        "org.junit.jupiter:junit-jupiter-engine:5.10.2"
                    )
                    enginesDependencies.add(
                        "org.junit.vintage:junit-vintage-engine:5.10.2"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )
                }

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

您的套件会自动访问目标变体的类和依赖项,而不会从 testImplementation 配置继承依赖项。

创建测试

将单元测试放在 {module}/src/{suiteName}/kotlin/ 或 java/ 目录中,并将 Java 测试资源放在 {module}/src/{suiteName}/resources/ 目录中。例如,创建 app/src/unitSuite/kotlin/com/example/myapp/CalculatorSuiteTest.kt 文件:

package com.example.myapp

import org.junit.jupiter.api.Assertions.assertEquals
import org.junit.jupiter.api.Test

class CalculatorSuiteTest {
    @Test
    fun addition_isCorrect() {
        assertEquals(4, 2 + 2)
    }
}

添加 Android 资源和 Robolectric

如需访问合并后的 Android 资源、资源、清单和 R 类(例如,对于 Robolectric 测试),请将 TestSuiteHostJarSpec 接口的 enableAndroidResources 属性设置为 true:

android {
    testOptions {
        customSuites {
            create("roboSuite") {
                targetVariants += listOf("debug")

                hostJar {
                    enableAndroidResources = true
                    dependencies {
                        implementation("junit:junit:4.13.2")
                        implementation("org.robolectric:robolectric:4.14.1")
                        implementation("androidx.test:core-ktx:1.6.1")
                    }
                }

                useJunitEngine {
                    includeEngines += listOf("junit-vintage")
                    enginesDependencies.add(
                        "org.junit.vintage:junit-vintage-engine:5.10.2"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )
                }

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

自定义任务和覆盖范围

使用 codeCoverage 属性在套件上启用 JaCoCo 覆盖率。如需针对每个目标自定义 Gradle Test 选项,请将配置 lambda 传递给 AgpTestSuiteTarget.configureTestTasks 方法,该方法会提供 TestTaskContext 实例。如需将验证任务附加到 check 任务,请使用 withTestTaskProviders 方法:

android {
    testOptions {
        customSuites {
            named("unitSuite") {
                // Generates JaCoCo HTML and XML coverage reports.
                codeCoverage = true

                targets.named("default") {
                    configureTestTasks { context ->
                        systemProperty("suite.variant", context.targetedVariant)
                        maxParallelForks = 2
                    }
                }

                withTestTaskProviders { context ->
                    if (!context.isUpdateTask) {
                        tasks.named("check") {
                            dependsOn(this@withTestTaskProviders)
                        }
                    }
                }
            }
        }
    }
}

如需将 Test 任务设置应用于套件中的每个目标,请改为对套件调用 AgpTestSuite.configureTestTasks 方法。

运行测试并检查报告

使用生成的 test{Variant}{SuiteName}{Target}TestSuite 任务从命令行运行套件:

./gradlew :app:testDebugUnitSuiteDefaultTestSuite

如需运行单个测试类或方法,请传递 Gradle 的 --tests 选项:

./gradlew :app:testDebugUnitSuiteDefaultTestSuite \
    --tests "com.example.myapp.CalculatorSuiteTest.addition_isCorrect"

测试运行完成后,AGP 会在以下路径中生成报告:

  • HTML 测试报告:{module}/build/reports/tests/{taskName}/index.html
  • thought JUnit XML 结果:{module}/build/test-results/{taskName}/
  • JaCoCo 覆盖率报告:{module}/build/reports/coverage/{suiteName}/index.html