Suite pengujian di plugin Android Gradle

Plugin Android Gradle (AGP) memungkinkan Anda mengatur pengujian ke dalam suite pengujian bernama di blok testOptions modul Anda. Setiap suite menentukan set sumber, dependensi, mesin pengujian JUnit Platform, dan varian build targetnya sendiri.

Alasan menggunakan suite pengujian

Secara default, modul Android menyediakan satu set sumber test untuk pengujian unit lokal dan satu set sumber androidTest untuk pengujian berinstrumen. Suite pengujian memisahkan organisasi pengujian dari kedua set sumber tersebut sehingga Anda dapat melakukan hal berikut:

  • Pisahkan pengujian berdasarkan tujuan: Simpan pengujian unit, Robolectric, UI, screenshot, dan cadangan di direktori src/{suiteName}/ khusus, bukan mencampurnya di direktori src/test/ atau src/androidTest/.
  • Mengisolasi dependensi dan mesin: Konfigurasikan classpath dan mesin pengujian Platform JUnit setiap suite tanpa menambahkan dependensi ke aplikasi Anda atau konfigurasi testImplementation dan androidTestImplementation.
  • Targetkan varian dan perangkat tertentu: Pilih varian build dan perangkat per suite sehingga pemeriksaan cepat berjalan secara lokal dan suite yang lebih panjang berjalan dalam continuous integration.

Jenis suite

AGP menyertakan suite pengujian bawaan untuk alur kerja khusus dan antarmuka AgpTestSuite untuk suite kustom. Tabel berikut mencantumkan jenis suite yang tersedia:

Jenis suite Penampung DSL Tujuan
Suite pengujian unit testOptions.customSuites Jalankan pengujian JUnit 5, JUnit 4, atau Robolectric di JVM lokal dengan blok hostJar.
Suite pengujian berinstrumen testOptions.customSuites Jalankan pengujian perangkat di perangkat yang terhubung atau dikelola build dengan blok testApk dan mesin pengujian android-test-engine.
Pengujian screenshot dengan suite pengujian testOptions.screenshotTests Render dan bandingkan @PreviewTest pratinjau Compose di host.
Pengujian pencadangan dan pemulihan otomatis testOptions.backupTests Verifikasi data aplikasi di seluruh transfer lokal, cloud, dan perangkat ke perangkat.
Rangkaian Deskripsi Langkah untuk Android Studio testOptions.customSuites Menjalankan perjalanan pengguna XML berbasis AI di perangkat terhubung.
Suite aset kustom atau campuran testOptions.customSuites Jalankan definisi pengujian statis dengan mesin kustom atau gabungkan blok hostJar, testApk, dan assets dalam satu suite.

Persyaratan

Untuk menggunakan suite pengujian kustom, pastikan project Anda memenuhi persyaratan berikut:

  • Android Studio Rabbit 3 Canary 3 atau yang lebih baru
  • AGP 9.6.0-alpha03 atau yang lebih tinggi
  • Gradle 9.7.1 atau yang lebih tinggi dan JDK 17 atau yang lebih tinggi
  • Modul com.android.application atau com.android.library

Suite pengujian tidak didukung dalam modul com.android.kotlin.multiplatform.library atau com.android.test. Untuk mengetahui informasi selengkapnya tentang pencocokan versi pratinjau, lihat Kompatibilitas dengan pratinjau plugin Android Gradle.

Menyiapkan suite pengujian kustom

Untuk panduan penyiapan langkah demi langkah, lihat Suite pengujian unit dan Suite pengujian berinstrumen. Untuk menentukan suite kustom Anda sendiri, aktifkan suite pengujian terlebih dahulu di file gradle.properties project Anda:

android.experimental.testSuiteSupport=true

Selanjutnya, deklarasikan suite di blok testOptions.customSuites file build.gradle.kts modul Anda. Tentukan properti targetVariants, satu atau beberapa blok sumber, blok useJunitEngine, dan setidaknya satu target di blok 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")
                }
            }
        }
    }
}

Di dalam implementasi TestEngine kustom, gunakan properti TestSuiteExecutionClient.default untuk membaca nilai enum AgpTestSuiteInputParameters dan konstanta TestEngineInputProperty standar seperti SERIAL_IDS dan RESULTS_DIR.

Direktori set sumber

Tata letak direktori setiap suite bergantung pada apakah suite tersebut mendeklarasikan satu blok sumber atau menggabungkan beberapa blok sumber. Tabel berikut mencantumkan jalur default di direktori {module}/src/{suiteName}/:

Blok sumber Suite sumber tunggal Suite campuran
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 Direktori root suite assetsTest/

Jangan gunakan kembali set sumber, ragam, jenis build, atau nama varian bawaan seperti main, androidTest, atau debug sebagai nama suite.

Target kontrol per varian

Untuk mengaktifkan atau menonaktifkan target suite untuk varian tertentu, konfigurasikan antarmuka TestSuiteTargetBuilder melalui properti HasTestSuitesBuilder.suites di blok beforeVariants:

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

Menjalankan suite dan memeriksa laporan

AGP membuat tugas Gradle untuk setiap kombinasi varian, suite, dan target. Tabel berikut mencantumkan pola tugas:

Jenis tugas Pola penamaan Contoh perintah
Target suite standar test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
Target dengan properti targetDevices test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Update dasar pengukuran (requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
Agregasi laporan modul testAllSuites ./gradlew :app:testAllSuites
Agregasi modul dan dependensi testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

Tugas test, connectedCheck, dan check tidak menjalankan suite kustom kecuali jika Anda menghubungkannya dengan metode withTestTaskProviders. Untuk mengaktifkan tugas testAllSuites dan testAllSuitesWithDependencies, tetapkan properti android.experimental.reportAggregationSupport=true di file gradle.properties.

Setiap suite yang dijalankan akan menulis output ke lokasi berikut:

  • Laporan pengujian HTML: {module}/build/reports/tests/{taskName}/index.html
  • Hasil XML JUnit: {module}/build/test-results/{taskName}/
  • Laporan cakupan kode: {module}/build/reports/coverage/{suiteName}/index.html
  • Laporan gabungan: {module}/build/reports/{aggregationTask}/test-report/index.html dan coverage-report/index.html

Untuk membuat laporan cakupan kode, tetapkan properti codeCoverage ke true di suite. Untuk suite screenshot Compose, konfigurasikan suite di file build.gradle.kts dengan testOptions.customSuites.named("{suiteName}") { codeCoverage = true }.

Masalah umum dan batasan

Suite pengujian memiliki batasan berikut:

  • Integrasi IDE: Dukungan Android Studio untuk suite pengujian kustom tidak tersedia. Editor kode mungkin menampilkan error referensi yang belum terselesaikan dalam file sumber suite meskipun build Anda dikonfigurasi dengan benar. Build dan jalankan suite pengujian dari command line menggunakan Gradle.
  • Caching tugas: Tugas suite pengujian selalu dijalankan ulang saat dipanggil dan tidak dimuat dari cache build Gradle. Suite tanpa file pengujian akan dilewati dengan status NO-SOURCE.