ชุดโปรแกรมทดสอบในปลั๊กอิน Android Gradle

ปลั๊กอิน Android Gradle (AGP) ช่วยให้คุณจัดระเบียบการทดสอบเป็นชุดโปรแกรมทดสอบที่มีชื่อในบล็อก testOptions ของโมดูลได้ ชุดโปรแกรมแต่ละชุดจะกำหนดชุดซอร์ส, ทรัพยากร Dependency, เครื่องมือทดสอบแพลตฟอร์ม JUnit และตัวแปรบิลด์เป้าหมายของตนเอง

เหตุผลที่ควรใช้ชุดโปรแกรมทดสอบ

โดยค่าเริ่มต้น โมดูล Android จะมีชุดซอร์ส test 1 ชุดสำหรับการทำ Unit Test ในเครื่อง และชุดซอร์ส androidTest 1 ชุดสำหรับการทดสอบการวัดคุม ชุดโปรแกรมทดสอบจะแยกองค์กรการทดสอบออกจากชุดซอร์สทั้ง 2 ชุดดังกล่าวเพื่อให้คุณทำสิ่งต่อไปนี้ได้

  • แยกการทดสอบตามวัตถุประสงค์: เก็บการทดสอบหน่วย, Robolectric, UI, ภาพหน้าจอ และการสำรองข้อมูลไว้ในไดเรกทอรี src/{suiteName}/ โดยเฉพาะ แทนที่จะรวมไว้ในไดเรกทอรี src/test/ หรือ src/androidTest/
  • แยกทรัพยากร Dependency และเครื่องมือ: กำหนดค่าคลาสพาธของแต่ละชุดและเครื่องมือทดสอบแพลตฟอร์ม JUnit โดยไม่ต้องเพิ่มทรัพยากร Dependency ลงในแอปหรือการกำหนดค่า testImplementation และ androidTestImplementation
  • กำหนดเป้าหมายตัวแปรและอุปกรณ์ที่เฉพาะเจาะจง: เลือกตัวแปรบิลด์และอุปกรณ์ต่อชุดเพื่อให้การตรวจสอบอย่างรวดเร็วทำงานในเครื่องและชุดที่ใช้เวลานานกว่าทำงานในการรวมอย่างต่อเนื่อง

ประเภทห้องสวีท

AGP มีชุดโปรแกรมทดสอบในตัวสำหรับเวิร์กโฟลว์เฉพาะทางและอินเทอร์เฟซ AgpTestSuite สำหรับชุดโปรแกรมที่กำหนดเอง ตารางต่อไปนี้แสดงประเภทชุดที่พร้อมให้บริการ

ประเภทห้องสวีท คอนเทนเนอร์ DSL วัตถุประสงค์
ชุดโปรแกรมทดสอบ Unit Test testOptions.customSuites เรียกใช้การทดสอบ JUnit 5, JUnit 4 หรือ Robolectric ใน JVM ในเครื่องด้วยบล็อก hostJar
ชุดโปรแกรมทดสอบที่มีการใช้เครื่องมือวัด testOptions.customSuites ทำการทดสอบอุปกรณ์ในอุปกรณ์ที่เชื่อมต่อหรืออุปกรณ์ที่จัดการโดยบิลด์ด้วยบล็อก testApk และเครื่องมือทดสอบ android-test-engine
การทดสอบภาพหน้าจอด้วยชุดโปรแกรมทดสอบ testOptions.screenshotTests แสดงผลและเปรียบเทียบตัวอย่าง Compose @PreviewTest รายการในโฮสต์
การทดสอบการสำรองและกู้คืนข้อมูลอัตโนมัติ testOptions.backupTests ยืนยันข้อมูลแอปในการโอนในเครื่อง ระบบคลาวด์ และระหว่างอุปกรณ์
เส้นทางสำหรับ Android Studio testOptions.customSuites เรียกใช้เส้นทางของผู้ใช้ XML ที่ขับเคลื่อนด้วย AI ในอุปกรณ์ที่เชื่อมต่อ
ชุดชิ้นงานที่กำหนดเองหรือแบบผสม 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

จากนั้นประกาศชุดทดสอบในบล็อก testOptions.customSuites ของไฟล์ build.gradle.kts ของโมดูล ระบุพร็อพเพอร์ตี้ targetVariants, บล็อกต้นทางอย่างน้อย 1 บล็อก, บล็อก useJunitEngine และเป้าหมายอย่างน้อย 1 รายการในบล็อก targets ดังนี้

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 เพื่ออ่านค่า enum 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/

อย่าใช้ชื่อชุดซอร์ส, เวอร์ชัน, ประเภทบิลด์ หรือตัวแปรในตัวซ้ำ เช่น main, androidTest หรือ debug เป็นชื่อชุดทดสอบ

เป้าหมายการควบคุมต่อตัวแปร

หากต้องการเปิดหรือปิดใช้เป้าหมายชุดทดสอบสำหรับตัวแปรที่เฉพาะเจาะจง ให้กำหนดค่าอินเทอร์เฟซ TestSuiteTargetBuilder ผ่านพร็อพเพอร์ตี้ HasTestSuitesBuilder.suites ในบล็อก beforeVariants ดังนี้

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
การรวมโมดูลและทรัพยากร Dependency testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

งาน test, connectedCheck และ check จะไม่เรียกใช้ชุดการทดสอบที่กำหนดเอง เว้นแต่คุณจะเชื่อมโยงงานเหล่านั้นด้วยเมธอด withTestTaskProviders หากต้องการเปิดใช้ภารกิจ testAllSuites และ testAllSuitesWithDependencies ให้ตั้งค่าพร็อพเพอร์ตี้ android.experimental.reportAggregationSupport=true ในไฟล์ gradle.properties

การเรียกใช้ชุดทดสอบแต่ละครั้งจะเขียนเอาต์พุตไปยังตำแหน่งต่อไปนี้

  • รายงานการทดสอบ HTML: {module}/build/reports/tests/{taskName}/index.html
  • ผลลัพธ์ 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 ไม่รองรับชุดโปรแกรมทดสอบที่กำหนดเอง ตัวแก้ไขโค้ดอาจแสดงข้อผิดพลาดการอ้างอิงที่ยังไม่ได้รับการแก้ไขในไฟล์ต้นฉบับของชุดทดสอบ แม้ว่าบิลด์จะได้รับการกำหนดค่าอย่างถูกต้องแล้วก็ตาม สร้างและเรียกใช้ชุดโปรแกรมทดสอบจากบรรทัดคำสั่งโดยใช้ Gradle แทน
  • การแคชงาน: งานชุดโปรแกรมทดสอบจะทำงานซ้ำเสมอเมื่อมีการเรียกใช้ และจะไม่โหลดจากแคชบิลด์ Gradle ระบบจะข้ามชุดโปรแกรมที่ไม่มีไฟล์ทดสอบโดยมีสถานะ NO-SOURCE