Paquetes de pruebas en el complemento de Android para Gradle

El complemento de Android para Gradle (AGP) te permite organizar las pruebas en paquetes de pruebas con nombre en el bloque testOptions de tu módulo. Cada paquete define sus propios conjuntos de orígenes, dependencias, motores de prueba de la plataforma JUnit y variantes de compilación de destino.

Por qué usar paquetes de pruebas

De forma predeterminada, un módulo de Android proporciona un conjunto de orígenes test para las pruebas de unidades locales y un conjunto de orígenes androidTest para las pruebas de instrumentación. Los paquetes de pruebas separan la organización de las pruebas de esos dos conjuntos de orígenes para que puedas hacer lo siguiente:

  • Separa las pruebas por propósito: Mantén las pruebas de unidades, Robolectric, IU, capturas de pantalla y copia de seguridad en directorios src/{suiteName}/ dedicados en lugar de mezclarlas en los directorios src/test/ o src/androidTest/.
  • Aísla las dependencias y los motores: Configura la ruta de clase de cada paquete y el motor de pruebas de JUnit Platform sin agregar dependencias a tu app ni a las configuraciones de testImplementation y androidTestImplementation.
  • Orienta las pruebas a variantes y dispositivos específicos: Selecciona variantes de compilación y dispositivos por paquete para que las verificaciones rápidas se ejecuten de forma local y los paquetes más largos se ejecuten en la integración continua.

Tipos de suites

El AGP incluye paquetes de pruebas integrados para flujos de trabajo especializados y la interfaz AgpTestSuite para paquetes personalizados. En la siguiente tabla, se enumeran los tipos de paquetes disponibles:

Tipo de suite Contenedor de DSL Objetivo
Paquetes de pruebas de unidades testOptions.customSuites Ejecuta pruebas de JUnit 5, JUnit 4 o Robolectric en la JVM local con el bloque hostJar.
Paquetes de pruebas instrumentadas testOptions.customSuites Ejecuta pruebas de dispositivos en dispositivos conectados o administrados por compilaciones con el bloque testApk y el motor de pruebas android-test-engine.
Pruebas de capturas de pantalla con paquetes de pruebas testOptions.screenshotTests Renderiza y compara las vistas previas de Compose de @PreviewTest en el host.
Pruebas automatizadas de copia de seguridad y restablecimiento testOptions.backupTests Verifica los datos de la app en las transferencias locales, en la nube y de dispositivo a dispositivo.
Recorridos para Android Studio testOptions.customSuites Ejecuta recorridos del usuario en XML impulsados por IA en dispositivos conectados.
Recursos personalizados o conjuntos mixtos testOptions.customSuites Ejecuta definiciones de pruebas estáticas con un motor personalizado o combina los bloques hostJar, testApk y assets en un paquete.

Requisitos

Para usar paquetes de pruebas personalizados, 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

Los paquetes de pruebas no se admiten en los módulos com.android.kotlin.multiplatform.library ni com.android.test. Para obtener más información sobre la coincidencia de versiones preliminares, consulta Compatibilidad con las versiones preliminares del complemento de Android para Gradle.

Cómo configurar un paquete de pruebas personalizado

Para obtener guías de configuración paso a paso, consulta Paquetes de pruebas de unidades y Paquetes de pruebas de instrumentación. Para definir tu propio paquete personalizado, primero habilita los paquetes de pruebas en el archivo gradle.properties de tu proyecto:

android.experimental.testSuiteSupport=true

Luego, declara un paquete en el bloque testOptions.customSuites del archivo build.gradle.kts de tu módulo. Especifica la propiedad targetVariants, uno o más bloques de origen, el bloque useJunitEngine y, al menos, un destino en el bloque 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")
                }
            }
        }
    }
}

Dentro de una implementación personalizada de TestEngine, usa la propiedad TestSuiteExecutionClient.default para leer los valores de la enumeración AgpTestSuiteInputParameters y las constantes estándar TestEngineInputProperty, como SERIAL_IDS y RESULTS_DIR.

Directorios de conjuntos de orígenes

El diseño del directorio de cada paquete depende de si declara un bloque de origen o combina varios bloques de origen. En la siguiente tabla, se enumeran las rutas de acceso predeterminadas en el directorio {module}/src/{suiteName}/:

Bloque de origen Paquete de fuente única Suite mixta
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 Directorio raíz del paquete assetsTest/

No reutilices nombres de conjuntos de orígenes, variantes de productos, tipos de compilación o variantes integrados, como main, androidTest o debug, como nombre de un paquete.

Objetivos de control por variante

Para habilitar o inhabilitar un destino de paquete para variantes específicas, configura la interfaz TestSuiteTargetBuilder a través de la propiedad HasTestSuitesBuilder.suites en el bloque beforeVariants:

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

Ejecuta paquetes y, luego, inspecciona los informes

El AGP crea una tarea de Gradle para cada combinación de variante, paquete y destino. En la siguiente tabla, se enumeran los patrones de tareas:

Tipo de tarea Patrón de nombres Comando de ejemplo
Objetivo de suite estándar test{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:testDebugMySuiteDefaultTestSuite
Segmentación con la propiedad targetDevices test{Variant}{SuiteName}{Target}{Devices}TestSuite ./gradlew :app:testDebugAndroidSuiteManagedCiPhonesTestSuite
Actualización de Baseline (requiresUpdateTask = true) update{Variant}{SuiteName}{Target}TestSuite ./gradlew :app:updateDebugScreenshotTestDefaultTestSuite
Agregación de informes de módulos testAllSuites ./gradlew :app:testAllSuites
Agregación de módulos y dependencias testAllSuitesWithDependencies ./gradlew :app:testAllSuitesWithDependencies

Las tareas test, connectedCheck y check no ejecutan conjuntos personalizados, a menos que los conectes con el método withTestTaskProviders. Para habilitar las tareas testAllSuites y testAllSuitesWithDependencies, configura la propiedad android.experimental.reportAggregationSupport=true en tu archivo gradle.properties.

Cada ejecución del paquete escribe resultados en las siguientes ubicaciones:

  • Informe de prueba HTML: {module}/build/reports/tests/{taskName}/index.html
  • Resultados XML de JUnit: {module}/build/test-results/{taskName}/
  • Informe de cobertura de código: {module}/build/reports/coverage/{suiteName}/index.html
  • Informes agregados: {module}/build/reports/{aggregationTask}/test-report/index.html y coverage-report/index.html

Para generar informes de cobertura de código, establece la propiedad codeCoverage en true en el paquete. Para los conjuntos de capturas de pantalla de Compose, configura el conjunto en tu archivo build.gradle.kts con testOptions.customSuites.named("{suiteName}") { codeCoverage = true }.

Problemas conocidos y limitaciones

Los paquetes de pruebas tienen las siguientes limitaciones:

  • Integración en el IDE: No está disponible la compatibilidad de Android Studio con los paquetes de pruebas personalizados. Es posible que el editor de código muestre errores de referencia sin resolver en los archivos de origen del paquete, incluso cuando la compilación esté configurada correctamente. En su lugar, compila y ejecuta paquetes de pruebas desde la línea de comandos con Gradle.
  • Almacenamiento en caché de tareas: Las tareas del paquete de pruebas siempre se vuelven a ejecutar cuando se invocan y no se cargan desde la caché de compilación de Gradle. Los paquetes sin archivos de prueba se omiten con el estado NO-SOURCE.