Paquetes de pruebas instrumentadas

Los paquetes de pruebas de instrumentación empaquetan las pruebas de dispositivos en APKs testApk aislados fuera del directorio src/androidTest/ predeterminado de tu módulo. Configúralas con el DSL de paquetes de pruebas del complemento de Android para Gradle (AGP) para separar las verificaciones de IU, integración o de extremo a extremo con dependencias, variantes y segmentación por dispositivo dedicados.

Requisitos

Para usar paquetes de pruebas de instrumentación, asegúrate de que tu proyecto cumpla con los siguientes requisitos:

  • Android Studio Rabbit 3 Canary 3 o una versión posterior
  • AGP 9.6.0-alpha03 o una versión posterior
  • Gradle 9.7.1 o una versión posterior, y JDK 17 o una versión posterior
  • Un módulo com.android.application o com.android.library
  • Un dispositivo o emulador conectado a través de Android Debug Bridge (adb) o una definición de dispositivo administrado por compilación

Para obtener más información sobre la coincidencia de versiones preliminares, consulta Compatibilidad con las versiones preliminares del complemento de Android para Gradle.

Configura un paquete de pruebas de instrumentación

Para agregar un paquete de pruebas de instrumentación a una app o un módulo de biblioteca, completa los siguientes pasos:

Habilita los paquetes de pruebas

En el archivo gradle.properties de tu proyecto, habilita la compatibilidad con el paquete de pruebas:

android.experimental.testSuiteSupport=true

Configura el paquete

En el archivo build.gradle.kts de tu módulo, crea un paquete dentro del bloque testOptions.customSuites con los bloques testApk y useJunitEngine, y los valores de enumeración 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")
                    }
                }
            }
        }
    }
}

El AGP configura automáticamente el ejecutor de pruebas AndroidJUnitRunner y los IDs de paquete sin heredar dependencias de la configuración de androidTestImplementation. Para usar un ejecutor personalizado, configura el atributo android:name en el elemento instrumentation de tu archivo src/{suiteName}/AndroidManifest.xml.

Cómo crear pruebas

Coloca tus pruebas de instrumentación en el directorio {module}/src/{suiteName}/kotlin/ o java/, junto con los directorios opcionales res/ o assets/, o un archivo AndroidManifest.xml. Por ejemplo, crea el archivo 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 pruebas de unidades y pruebas de instrumentación

Para ejecutar pruebas de JVM locales y pruebas de dispositivos instrumentadas en una sola tarea de Gradle, declara los bloques hostJar y testApk en un paquete. Coloca las pruebas del host en el directorio src/{suiteName}/test/ y las pruebas del dispositivo en el directorio 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")
                }
            }
        }
    }
}

Ejecuta pruebas y recopila la cobertura

Usa Gradle para ejecutar conjuntos de pruebas instrumentadas, filtrar casos de prueba y generar informes de cobertura.

Ejecuta pruebas en dispositivos conectados o administrados por la compilación

Ejecuta un destino conectado en cada dispositivo adb en línea o ejecuta un destino configurado con la propiedad targetDevices:

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

Cómo filtrar pruebas de instrumentación

Filtra las pruebas con la opción --tests o los argumentos AndroidJUnitRunner de Gradle:

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

También puedes pasar argumentos de AndroidJUnitRunner en la línea de comandos con una propiedad del proyecto, como -Pandroid.testInstrumentationRunnerArguments.size=small. Para establecer argumentos predeterminados del ejecutor en el bloque useJunitEngine, llama al método addInputProperty, como addInputProperty("android-test.instrumentation-args", "size=small").

Recopila la cobertura de código integrada en el dispositivo

La cobertura de código integrada en el dispositivo requiere una compilación depurable y un dispositivo que ejecute Android 9 (nivel de API 28) o una versión posterior. Para recopilar la cobertura de un paquete de pruebas instrumentadas o mixtas, completa los siguientes pasos:

  1. Establece la propiedad android.experimental.androidTest.coverage.useOnDeviceAgent=true en tu archivo gradle.properties.
  2. Establece la propiedad codeCoverage en true en el paquete.
  3. Si hay varios dispositivos conectados, orienta uno con la variable de entorno ANDROID_SERIAL.

Para obtener más información sobre los requisitos del agente, consulta Cómo ver informes de cobertura de código (con el agente integrado en el dispositivo).

Inspecciona los informes

Una vez que se completa una ejecución de prueba, el AGP genera resultados en las siguientes rutas de acceso:

  • Informe de prueba HTML: {module}/build/reports/tests/{taskName}/index.html
  • Resultados XML de JUnit: {module}/build/test-results/{taskName}/
  • XML y logcat por dispositivo: {module}/build/intermediates/{variant}/{taskName}/results/
  • Informe de cobertura de código: {module}/build/reports/coverage/{suiteName}/index.html