Suite di test strumentati

Le suite di test strumentati pacchettizzano i test dei dispositivi in APK testApk isolati al di fuori della directory src/androidTest/ predefinita del modulo. Configurale con il DSL delle suite di test del plug-in Android per Gradle (AGP) per separare i controlli di UI, integrazione o end-to-end con dipendenze, varianti e targeting per dispositivo dedicati.

Requisiti

Per utilizzare le suite di test di instrumentazione, assicurati che il tuo progetto soddisfi i seguenti requisiti:

  • Android Studio Rabbit 3 Canary 3 o versioni successive
  • AGP 9.6.0-alpha03 o versioni successive
  • Gradle 9.7.1 o versioni successive e JDK 17 o versioni successive
  • Un modulo com.android.application o com.android.library
  • Un dispositivo o un emulatore connesso tramite Android Debug Bridge (ADB) o una definizione di dispositivo gestito dalla build

Per saperne di più sulla corrispondenza delle versioni di anteprima, consulta Compatibilità con le anteprime del plug-in Android per Gradle.

Configura una suite di test di instrumentazione

Per aggiungere una suite di test di instrumentazione a un modulo di app o libreria, completa i seguenti passaggi:

Abilita le suite di test

Nel file gradle.properties del progetto, attiva il supporto della suite di test:

android.experimental.testSuiteSupport=true

Configura la suite

Nel file build.gradle.kts del modulo, crea una suite all'interno del blocco testOptions.customSuites con i blocchi testApk e useJunitEngine e i valori dell'enum 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 configura automaticamente gli ID pacchetto e l'esecutore di test AndroidJUnitRunner senza ereditare le dipendenze dalla configurazione androidTestImplementation. Per utilizzare un runner personalizzato, imposta l'attributo android:name sull'elemento instrumentation nel file src/{suiteName}/AndroidManifest.xml.

Crea test

Inserisci i test di instrumentazione nella directory {module}/src/{suiteName}/kotlin/ o java/, insieme a eventuali directory res/ o assets/ facoltative o a un file AndroidManifest.xml. Ad esempio, crea il file 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)
    }
}

Combina test delle unità e test di instrumentazione

Per eseguire test JVM locali e test dei dispositivi con strumentazione in un'unica attività Gradle, dichiara i blocchi hostJar e testApk in un'unica suite. Inserisci i test host nella directory src/{suiteName}/test/ e i test dei dispositivi nella directory 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")
                }
            }
        }
    }
}

Esegui i test e raccogli i dati di copertura

Utilizza Gradle per eseguire suite strumentate, filtrare gli scenari di test e generare report sulla copertura.

Esegui su dispositivi connessi o gestiti dalla build

Esegui una destinazione connessa su ogni dispositivo adb online o esegui una destinazione configurata con la proprietà targetDevices:

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

Filtra i test di instrumentazione

Filtra i test con l'opzione --tests di Gradle o gli argomenti AndroidJUnitRunner:

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

Puoi anche passare gli argomenti AndroidJUnitRunner sulla riga di comando con una proprietà del progetto come -Pandroid.testInstrumentationRunnerArguments.size=small. Per impostare gli argomenti predefiniti del runner nel blocco useJunitEngine, chiama il metodo addInputProperty, ad esempio addInputProperty("android-test.instrumentation-args", "size=small").

Raccogli la copertura del codice on-device

La copertura del codice on-device richiede una build abilitata al debug e un dispositivo con Android 9 (livello API 28) o versioni successive. Per raccogliere la copertura per una suite strumentata o mista, completa i seguenti passaggi:

  1. Imposta la proprietà android.experimental.androidTest.coverage.useOnDeviceAgent=true nel file gradle.properties.
  2. Imposta la proprietà codeCoverage su true nella suite.
  3. Se sono connessi più dispositivi, scegli come target un dispositivo con la variabile di ambiente ANDROID_SERIAL.

Per saperne di più sui requisiti dell'agente, consulta Visualizza i report sulla copertura del codice (con l'agente on-device).

Ispeziona i report

Al termine di un'esecuzione di test, AGP genera output nei seguenti percorsi:

  • Report di test HTML: {module}/build/reports/tests/{taskName}/index.html
  • Risultati XML JUnit: {module}/build/test-results/{taskName}/
  • XML e logcat per dispositivo: {module}/build/intermediates/{variant}/{taskName}/results/
  • Report sulla copertura del codice: {module}/build/reports/coverage/{suiteName}/index.html