Zestawy testów instrumentowanych

Zinstrumentowane zestawy testów pakują testy urządzeń w odizolowane pliki APK testApk poza domyślnym katalogiem src/androidTest/ modułu. Skonfiguruj je za pomocą pakietów testowych DSL wtyczki Androida do obsługi Gradle (AGP), aby oddzielić testy interfejsu, integracji lub kompleksowe testy z dedykowanymi zależnościami, wariantami i urządzeniami docelowymi.

Wymagania

Aby korzystać z zestawów testów z instrumentacją, 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,
  • urządzenie lub emulator połączone przez Android Debug Bridge (adb) albo definicję urządzenia zarządzanego przez kompilację.

Więcej informacji o dopasowywaniu wersji testowych znajdziesz w artykule o zgodności z wersjami testowymi wtyczki Androida do obsługi Gradle.

Konfigurowanie zestawu testów z instrumentacją

Aby dodać zestaw testów z instrumentacją do modułu aplikacji lub biblioteki, wykonaj te czynności:

Włączanie zestawów testów

W pliku gradle.properties projektu włącz obsługę zestawu testów:

android.experimental.testSuiteSupport=true

Konfigurowanie pakietu

W pliku build.gradle.kts modułu utwórz zestaw w bloku testOptions.customSuites z blokami testApk i useJunitEngine oraz wartościami typu wyliczeniowego AgpTestSuiteInputParameters:

import com.android.build.api.dsl.AgpTestSuiteInputParameters

android {
    testOptions {
        // Optional: define build-managed virtual devices and device groups.
        managedDevices {
            localDevices {
                create("api34Atd") {
                    // Use a device profile from Android Studio.
                    device = "Pixel 6"
                    apiLevel = 34
                    systemImageSource = "aosp-atd"
                }
            }
            groups {
                create("ciPhones") {
                    targetDevices.add(allDevices.getByName("api34Atd"))
                }
            }
        }

        customSuites {
            create("androidSuite") {
                targetVariants += listOf("debug")

                testApk {
                    dependencies {
                        implementation("junit:junit:4.13.2")
                        implementation("androidx.test.ext:junit:1.2.1")
                        implementation("androidx.test:runner:1.6.2")
                    }
                }

                useJunitEngine {
                    includeEngines += listOf("android-test-engine")
                    // Match the engine and listener versions to your AGP
                    // version.
                    enginesDependencies.add(
                        "com.android.tools.androidtest:" +
                            "android-test-engine:9.6.0-alpha03"
                    )
                    enginesDependencies.add(
                        "com.android.tools.androidtest:" +
                            "android-test-engine-result-listener:9.6.0-alpha03"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    inputs += listOf(
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.TEST_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                        AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
                    )
                }

                targets {
                    // Runs on connected adb devices.
                    create("default")
                    // Optional: runs on build-managed devices or groups in
                    // targetDevices.
                    create("managed") {
                        targetDevices += listOf("ciPhones")
                    }
                }
            }
        }
    }
}

AGP automatycznie konfiguruje identyfikatory modułu uruchamiającego testy i pakietu AndroidJUnitRunner bez dziedziczenia zależności z konfiguracji androidTestImplementation. Aby użyć niestandardowego modułu uruchamiającego, ustaw atrybut android:name w elemencie instrumentation w pliku src/{suiteName}/AndroidManifest.xml.

Tworzenie testów

Umieść testy z instrumentacją w katalogu {module}/src/{suiteName}/kotlin/ lub java/ wraz z opcjonalnymi katalogami res/ lub assets/ albo plikiem AndroidManifest.xml. Na przykład utwórz plik app/src/androidSuite/kotlin/com/example/myapp/AppContextSuiteTest.kt:

package com.example.myapp

import androidx.test.ext.junit.runners.AndroidJUnit4
import androidx.test.platform.app.InstrumentationRegistry
import org.junit.Assert.assertEquals
import org.junit.Test
import org.junit.runner.RunWith

@RunWith(AndroidJUnit4::class)
class AppContextSuiteTest {
    @Test
    fun useAppContext() {
        val appContext =
            InstrumentationRegistry.getInstrumentation().targetContext
        assertEquals("com.example.myapp", appContext.packageName)
    }
}

Łączenie testów jednostkowych i testów z instrumentacją

Aby uruchomić lokalne testy JVM i testy na urządzeniu z instrumentacją w ramach jednego zadania Gradle, zadeklaruj bloki hostJar i testApk w jednym pakiecie. Umieść testy hosta w katalogu src/{suiteName}/test/, a testy urządzenia w katalogu src/{suiteName}/androidTest/:

import com.android.build.api.dsl.AgpTestSuiteInputParameters

android {
    testOptions {
        customSuites {
            create("combinedSuite") {
                targetVariants += listOf("debug")

                hostJar {
                    dependencies {
                        implementation(
                            "org.junit.jupiter:junit-jupiter-api:5.10.2"
                        )
                    }
                }

                testApk {
                    dependencies {
                        implementation("junit:junit:4.13.2")
                        implementation("androidx.test.ext:junit:1.2.1")
                        implementation("androidx.test:runner:1.6.2")
                    }
                }

                useJunitEngine {
                    includeEngines += listOf(
                        "junit-jupiter",
                        "android-test-engine",
                    )
                    enginesDependencies.add(
                        "org.junit.jupiter:junit-jupiter-engine:5.10.2"
                    )
                    enginesDependencies.add(
                        "com.android.tools.androidtest:" +
                            "android-test-engine:9.6.0-alpha03"
                    )
                    enginesDependencies.add(
                        "com.android.tools.androidtest:" +
                            "android-test-engine-result-listener:9.6.0-alpha03"
                    )
                    enginesDependencies.add(
                        "org.junit.platform:junit-platform-launcher:1.10.2"
                    )

                    inputs += listOf(
                        // Omit TESTED_APKS in com.android.library modules.
                        AgpTestSuiteInputParameters.TESTED_APKS,
                        AgpTestSuiteInputParameters.TEST_APKS,
                        AgpTestSuiteInputParameters.ADB_EXECUTABLE,
                        AgpTestSuiteInputParameters.AAPT2_EXECUTABLE,
                    )
                }

                targets {
                    create("default")
                }
            }
        }
    }
}

Uruchamianie testów i zbieranie danych o pokryciu

Używaj Gradle do uruchamiania zestawów instrumentowanych, filtrowania elementów testowania i generowania raportów o pokryciu.

Uruchamianie na połączonych urządzeniach lub urządzeniach zarządzanych przez kompilację

Uruchom połączony element docelowy na każdym urządzeniu adb online lub uruchom element docelowy skonfigurowany za pomocą właściwości targetDevices:

# Run on connected adb devices.
./gradlew :app:testDebugAndroidSuiteDefaultTestSuite
# Run on the ciPhones build-managed device group.
./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite

Filtrowanie testów z instrumentacją

Filtruj testy za pomocą opcji --tests Gradle lub argumentów AndroidJUnitRunner:

./gradlew :app:testDebugAndroidSuiteDefaultTestSuite \
    --tests "com.example.myapp.AppContextSuiteTest.useAppContext"

Możesz też przekazać argumenty AndroidJUnitRunner w wierszu poleceń za pomocą właściwości projektu, takiej jak -Pandroid.testInstrumentationRunnerArguments.size=small. Aby ustawić domyślne argumenty modułu uruchamiającego w bloku useJunitEngine, wywołaj metodę addInputProperty, np. addInputProperty("android-test.instrumentation-args", "size=small").

Zbieranie informacji o pokryciu kodu na urządzeniu

Pokrycie kodu na urządzeniu wymaga kompilacji z możliwością debugowania i urządzenia z Androidem 9 (poziom API 28) lub nowszym. Aby zebrać dane o pokryciu w przypadku pakietu instrumentowanego lub mieszanego, wykonaj te czynności:

  1. Ustaw właściwość android.experimental.androidTest.coverage.useOnDeviceAgent=true w pliku gradle.properties.
  2. Ustaw właściwość codeCoverage na true w pakiecie.
  3. Jeśli podłączonych jest kilka urządzeń, wybierz jedno z nich za pomocą zmiennej środowiskowej ANDROID_SERIAL.

Więcej informacji o wymaganiach dotyczących agenta znajdziesz w artykule Wyświetlanie raportów o pokryciu kodu (z agentem na urządzeniu).

Sprawdzanie raportów

Po zakończeniu uruchomienia testowego AGP generuje dane wyjściowe w tych ścieżkach:

  • Raport z testu w formacie HTML: {module}/build/reports/tests/{taskName}/index.html
  • Wyniki JUnit XML: {module}/build/test-results/{taskName}/
  • Plik XML i logcat dla poszczególnych urządzeń: {module}/build/intermediates/{variant}/{taskName}/results/
  • Raport o pokryciu kodu: {module}/build/reports/coverage/{suiteName}/index.html