Zestawy testów we wtyczce Androida do obsługi Gradle

Wtyczka Androida do obsługi Gradle (AGP) umożliwia organizowanie testów w nazwane zestawy testów w bloku testOptions modułu. Każdy zestaw definiuje własne zbiory źródeł, zależności, silniki testowe platformy JUnit i docelowe warianty kompilacji.

Dlaczego warto używać zestawów testów

Domyślnie moduł Androida udostępnia 1 zbiór źródeł test na potrzeby lokalnych testów jednostkowych i 1 zbiór źródeł androidTest na potrzeby testów z instrumentacją. Zestawy testów oddzielają organizację testów od tych 2 zbiorów źródeł, dzięki czemu możesz:

  • Oddziel testy według celu: testy jednostkowe, Robolectric, UI, zrzutów ekranu i kopii zapasowych przechowuj w osobnych katalogach src/{suiteName}/, a nie w katalogach src/test/ lub src/androidTest/.
  • Izolowanie zależności i silników: skonfiguruj ścieżkę klasy każdego pakietu i silnik testowy platformy JUnit bez dodawania zależności do aplikacji ani konfiguracji testImplementation i androidTestImplementation.
  • Kierowanie na konkretne warianty i urządzenia: wybierz warianty kompilacji i urządzenia dla każdego pakietu, aby szybkie testy były uruchamiane lokalnie, a dłuższe pakiety – w trybie ciągłej integracji.

Typy apartamentów

AGP zawiera wbudowane zestawy testów do specjalistycznych przepływów pracy oraz interfejs AgpTestSuite do niestandardowych zestawów. W tabeli poniżej znajdziesz dostępne typy pakietów:

Typ apartamentu Kontener DSL Cel
Zestawy testów jednostkowych testOptions.customSuites Uruchamiaj testy JUnit 5, JUnit 4 lub Robolectric na lokalnej maszynie JVM za pomocą bloku hostJar.
Zestawy testów instrumentowanych testOptions.customSuites Uruchamiaj testy urządzeń na połączonych urządzeniach lub urządzeniach zarządzanych przez kompilację za pomocą bloku testApk i silnika testowego android-test-engine.
Testowanie zrzutów ekranu za pomocą pakietów testów testOptions.screenshotTests Renderuj i porównuj podglądy Compose w @PreviewTest na hoście.
Automatyczne testowanie tworzenia i przywracania kopii zapasowych testOptions.backupTests Sprawdź dane aplikacji w przypadku transferów lokalnych, w chmurze i między urządzeniami.
Journeys w Android Studio testOptions.customSuites Uruchamiaj na połączonych urządzeniach ścieżki użytkownika XML oparte na AI.
Komponent niestandardowy lub zestawy mieszane testOptions.customSuites Uruchamiaj statyczne definicje testów za pomocą niestandardowego silnika lub połącz bloki hostJar, testApk i assets w jeden pakiet.

Wymagania

Aby korzystać z niestandardowych pakietów testów, upewnij się, że Twój projekt spełnia te wymagania:

  • Android Studio Rabbit 3 Canary 3 lub nowszy,
  • AGP w wersji 9.6.0-alpha03 lub nowszej,
  • Gradle 9.7.1 lub nowszy i JDK 17 lub nowszy
  • moduł com.android.application lub com.android.library,

Zestawy testów nie są obsługiwane w modułach com.android.kotlin.multiplatform.library ani com.android.test. Więcej informacji o dopasowywaniu wersji testowych znajdziesz w sekcji Zgodność z wersjami testowymi wtyczki Androida do obsługi Gradle.

Konfigurowanie niestandardowego zestawu testów

Szczegółowe instrukcje znajdziesz w artykułach Zestawy testów jednostkowych i Zestawy testów instrumentowanych. Aby zdefiniować własny zestaw, najpierw włącz zestawy testów w pliku gradle.properties projektu:

android.experimental.testSuiteSupport=true

Następnie zadeklaruj pakiet w bloku testOptions.customSuites pliku build.gradle.kts modułu. Określ właściwość targetVariants, co najmniej 1 blok źródłowy, blok useJunitEngine i co najmniej 1 cel w bloku 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")
                }
            }
        }
    }
}

W niestandardowej implementacji TestEngine użyj właściwości TestSuiteExecutionClient.default, aby odczytać wartości wyliczeniowe AgpTestSuiteInputParameters i standardowe stałe TestEngineInputProperty, takie jak SERIAL_IDS i RESULTS_DIR.

Katalogi zbioru źródeł

Układ katalogu każdego pakietu zależy od tego, czy deklaruje on 1 blok źródłowy, czy łączy wiele bloków źródłowych. W tabeli poniżej znajdziesz domyślne ścieżki w katalogu {module}/src/{suiteName}/:

Blok źródłowy Pakiet z jednego źródła Przedział mieszany
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 Katalog główny pakietu assetsTest/

Nie używaj ponownie wbudowanego zbioru źródeł, wersji, typu kompilacji ani nazw wariantów, takich jak main, androidTest lub debug, jako nazwy pakietu.

Cele kontrolne na wariant

Aby włączyć lub wyłączyć cel pakietu dla konkretnych wariantów, skonfiguruj interfejs TestSuiteTargetBuilder za pomocą właściwości HasTestSuitesBuilder.suites w bloku beforeVariants:

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

Uruchamianie pakietów i sprawdzanie raportów

AGP tworzy zadanie Gradle dla każdej kombinacji wariantu, pakietu i celu. W poniższej tabeli znajdziesz wzorce zadań:

Typ zadania Wzorzec nazewnictwa Przykładowe polecenie
Standardowy cel pakietu test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
Cel z właściwością targetDevices test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Aktualizacja punktu odniesienia (requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
Agregacja raportów modułów testAllSuites ./gradlew :app:testAllSuites
Agregacja modułów i zależności testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

Zadania test, connectedCheck i check nie uruchamiają pakietów niestandardowych, chyba że połączysz je za pomocą metody withTestTaskProviders. Aby włączyć zadania testAllSuites i testAllSuitesWithDependencies, ustaw właściwość android.experimental.reportAggregationSupport=true w pliku gradle.properties.

Każde uruchomienie pakietu zapisuje dane wyjściowe w tych lokalizacjach:

  • Raport z testu w formacie HTML: {module}/build/reports/tests/{taskName}/index.html
  • Wyniki JUnit XML: {module}/build/test-results/{taskName}/
  • Raport o pokryciu kodu: {module}/build/reports/coverage/{suiteName}/index.html
  • Raporty zbiorcze: {module}/build/reports/{aggregationTask}/test-report/index.html i coverage-report/index.html

Aby wygenerować raporty o pokryciu kodu, ustaw właściwość codeCoverage na true w pakiecie. W przypadku pakietów zrzutów ekranu Compose skonfiguruj pakiet w pliku build.gradle.kts za pomocą testOptions.customSuites.named("{suiteName}") { codeCoverage = true }.

Znane problemy i ograniczenia

Zestawy testów mają te ograniczenia:

  • Integracja ze środowiskiem IDE: obsługa niestandardowych zestawów testów w Android Studio jest niedostępna. Edytor kodu może wyświetlać błędy nierozwiązanych odwołań w plikach źródłowych pakietu, nawet jeśli kompilacja jest prawidłowo skonfigurowana. Zamiast tego twórz i uruchamiaj pakiety testów z wiersza poleceń za pomocą Gradle.
  • Buforowanie zadań: zadania zestawu testów są zawsze uruchamiane ponownie po wywołaniu i nie są wczytywane z pamięci podręcznej kompilacji Gradle. Zestawy bez plików testowych są pomijane i mają stan NO-SOURCE.