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 directoriossrc/test/osrc/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
testImplementationyandroidTestImplementation. - 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.applicationocom.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.htmlycoverage-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.