單元測試套件

單元測試套件會在模組預設 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
  • JUnit XML 結果:{module}/build/test-results/{taskName}/
  • JaCoCo 涵蓋率報表: {module}/build/reports/coverage/{suiteName}/index.html