Android Gradle eklentisindeki test paketleri

Android Gradle eklentisi (AGP), modülünüzün testOptions bloğunda testleri adlandırılmış test paketleri halinde düzenlemenize olanak tanır. Her paket kendi kaynak gruplarını, bağımlılıklarını, JUnit Platform test motorlarını ve hedef derleme varyantlarını tanımlar.

Test paketlerini neden kullanmalısınız?

Varsayılan olarak bir Android modülü, yerel birim testleri için bir test kaynak grubu ve enstrümantasyon testleri için bir androidTest kaynak grubu sağlar. Test paketleri, test organizasyonunu bu iki kaynak grubundan ayırır. Böylece şunları yapabilirsiniz:

  • Testleri amaca göre ayırın: Birim, Robolectric, kullanıcı arayüzü, ekran görüntüsü ve yedekleme testlerini src/test/ veya src/androidTest/ dizinlerinde karıştırmak yerine özel src/{suiteName}/ dizinlerinde tutun.
  • Bağımlılıkları ve motorları izole etme: Uygulamanıza veya testImplementation ve androidTestImplementation yapılandırmalarına bağımlılık eklemeden her paketin sınıf yolunu ve JUnit Platform test motorunu yapılandırın.
  • Belirli derleme değişkenlerini ve cihazları hedefleme: Hızlı kontrollerin yerel olarak, daha uzun süren paketlerin ise sürekli entegrasyonda çalıştırılması için her paket için derleme değişkenlerini ve cihazları seçin.

Süit türleri

AGP, özel iş akışları için yerleşik test paketleri ve özel paketler için AgpTestSuite arayüzünü içerir. Aşağıdaki tabloda, kullanılabilir paket türleri listelenmiştir:

Paket türü DSL kapsayıcısı Amaç
Birim testi paketleri testOptions.customSuites hostJar bloğuyla yerel JVM'de JUnit 5, JUnit 4 veya Robolectric testleri çalıştırın.
Araçlı test paketleri testOptions.customSuites testApk bloğu ve android-test-engine test motoruyla bağlı veya derleme tarafından yönetilen cihazlarda cihaz testleri çalıştırın.
Test paketleriyle ekran görüntüsü testi testOptions.screenshotTests Ana makinede @PreviewTest Compose önizlemesini oluşturun ve karşılaştırın.
Otomatik yedekleme ve geri yükleme testi testOptions.backupTests Yerel, bulut ve cihazlar arası aktarımlarda uygulama verilerini doğrulayın.
Android Studio için Kullanıcı Akışları testOptions.customSuites Bağlı cihazlarda yapay zeka destekli XML kullanıcı yolculukları çalıştırın.
Özel öğe veya karma paketler testOptions.customSuites Özel bir motorla statik test tanımları çalıştırın veya hostJar, testApk ve assets bloklarını tek bir pakette birleştirin.

Şartlar

Özel test paketlerini kullanmak için projenizin aşağıdaki koşulları karşıladığından emin olun:

  • Android Studio Rabbit 3 Canary 3 veya sonraki sürümler
  • AGP 9.6.0-alpha03 veya sonraki sürümler
  • Gradle 9.7.1 veya sonraki sürümler ve JDK 17 veya sonraki sürümler
  • com.android.application veya com.android.library modülü

Test paketleri com.android.kotlin.multiplatform.library veya com.android.test modüllerinde desteklenmez. Önizleme sürümü eşleştirme hakkında daha fazla bilgi için Android Gradle eklentisi önizlemeleriyle uyumluluk bölümüne bakın.

Özel test paketi oluşturma

Adım adım kurulum kılavuzları için Birim testi paketleri ve Araçlı test paketleri başlıklı makaleleri inceleyin. Kendi özel paketinizi tanımlamak için önce projenizin gradle.properties dosyasında test paketlerini etkinleştirin:

android.experimental.testSuiteSupport=true

Ardından, modülünüzün build.gradle.kts dosyasının testOptions.customSuites bloğunda bir paket tanımlayın. targetVariants özelliğini, bir veya daha fazla kaynak bloğunu, useJunitEngine bloğunu ve targets bloğunda en az bir hedefi belirtin:

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")
                }
            }
        }
    }
}

Özel bir TestEngine uygulamasında, AgpTestSuiteInputParameters enum değerlerini ve SERIAL_IDS ile RESULTS_DIR gibi standart TestEngineInputProperty sabitlerini okumak için TestSuiteExecutionClient.default özelliğini kullanın.

Kaynak grubu dizinleri

Her paketin dizin düzeni, bir kaynak blok mu tanımladığına yoksa birden fazla kaynak bloğu mu birleştirdiğine bağlıdır. Aşağıdaki tabloda, {module}/src/{suiteName}/ dizini altındaki varsayılan yollar listelenmiştir:

Kaynak blok Tek kaynaklı paket Karma süit
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 Paket kök dizini assetsTest/

main, androidTest veya debug gibi yerleşik kaynak grubu, varyant, derleme türü ya da varyant adlarını paket adı olarak yeniden kullanmayın.

Varyant başına kontrol hedefi sayısı

Belirli varyantlar için bir paket hedefini etkinleştirmek veya devre dışı bırakmak istiyorsanız beforeVariants bloğundaki HasTestSuitesBuilder.suites özelliği aracılığıyla TestSuiteTargetBuilder arayüzünü yapılandırın:

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

Paketleri çalıştırma ve raporları inceleme

AGP; varyant, paket ve hedef kombinasyonlarının her biri için bir Gradle görevi oluşturur. Aşağıdaki tabloda görev kalıpları listelenmiştir:

Görev türü Adlandırma kalıbı Örnek komut
Standart süit hedefi test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
targetDevices özelliğiyle hedefleme test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Referans güncellemesi (requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
Modül raporu toplama testAllSuites ./gradlew :app:testAllSuites
Modül ve bağımlılık toplama testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

test, connectedCheck ve check görevleri, withTestTaskProviders yöntemiyle bağlamadığınız sürece özel paketleri çalıştırmaz. testAllSuites ve testAllSuitesWithDependencies görevlerini etkinleştirmek için gradle.properties dosyanızda android.experimental.reportAggregationSupport=true özelliğini ayarlayın.

Her paket çalıştırması, çıkışları aşağıdaki konumlara yazar:

  • HTML test raporu: {module}/build/reports/tests/{taskName}/index.html
  • JUnit XML sonuçları: {module}/build/test-results/{taskName}/
  • Kod kapsamı raporu: {module}/build/reports/coverage/{suiteName}/index.html
  • Toplu raporlar: {module}/build/reports/{aggregationTask}/test-report/index.html ve coverage-report/index.html

Kod kapsamı raporları oluşturmak için paketteki codeCoverage özelliğini true olarak ayarlayın. Oluşturma ekran görüntüsü paketleri için build.gradle.kts dosyanızdaki paketi testOptions.customSuites.named("{suiteName}") { codeCoverage = true } ile yapılandırın.

Bilinen sorunlar ve sınırlamalar

Test paketlerinde aşağıdaki sınırlamalar vardır:

  • IDE entegrasyonu: Android Studio'da özel test paketleri desteklenmez. Derlemeniz doğru şekilde yapılandırılmış olsa bile kod düzenleyici, paket kaynak dosyalarında çözümlenmemiş referans hataları gösterebilir. Bunun yerine, Gradle'ı kullanarak komut satırından test paketleri oluşturup çalıştırın.
  • Görev önbelleğe alma: Test paketi görevleri, çağrıldığında her zaman yeniden çalıştırılır ve Gradle derleme önbelleğinden yüklenmez. Test dosyası içermeyen paketler NO-SOURCE durumuyla atlanır.