Pruebas de capturas de pantalla con paquetes de pruebas

A partir del complemento de Android para Gradle (AGP) 9.5.0-alpha03 y el motor de pruebas de capturas de pantalla de Compose Preview 0.0.1-alpha16, las pruebas de capturas de pantalla se integran en el framework nativo de suites de pruebas de AGP.

Este enfoque reemplaza el complemento independiente de capturas de pantalla (com.android.compose.screenshot). Te recomendamos que adoptes los conjuntos de pruebas del AGP por los siguientes motivos:

• Ciclo de vida de tareas de Gradle nativo: Las pruebas de capturas de pantalla se integran directamente en los ciclos de vida de pruebas estándar de Gradle y AGP, lo que mejora el aislamiento de tareas y la confiabilidad de la ejecución de pruebas.
• Compatibilidad con suites personalizadas y de múltiples variantes: Puedes crear múltiples suites de pruebas de capturas de pantalla distintas (como screenshotTest, uiTests o smokeTests) dentro de un solo módulo y orientarlas a variantes de compilación específicas (como demoDebug o release), en lugar de estar restringido a un solo conjunto de orígenes preconfigurado.
• Rendimiento y aislamiento de compilación mejorados: Los conjuntos de pruebas de AGP usan transformaciones de artefactos integradas (como la extracción del tiempo de ejecución de Layoutlib) y la carga de clases aislada, con compatibilidad total para el almacenamiento en caché de la configuración de Gradle y el aislamiento de proyectos.

Requisitos

Para usar Compose Screenshot Testing con conjuntos de pruebas, asegúrate de que tu entorno cumpla con los siguientes requisitos:

• Android Studio Rabbit 1 Canary 4 o una versión posterior
• Versión 9.5.0-alpha03 o posterior del complemento de Android para Gradle (AGP)
• Versión 0.0.1-alpha16 o posterior de Compose Screenshot Engine
• JDK versión 17 o posterior
• La función de redacción está habilitada para tu proyecto. Te recomendamos que habilites Compose con el complemento de Gradle de Compose Compiler.

Instalación y configuración

Para configurar las pruebas de capturas de pantalla de Compose con conjuntos de pruebas, completa los siguientes pasos:

1. Cómo habilitar marcas experimentales

En el archivo gradle.properties raíz de tu proyecto, habilita las pruebas de capturas de pantalla y la compatibilidad con el paquete de pruebas:

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. Configura el paquete de pruebas en el archivo build.gradle.kts

En el archivo build.gradle.kts de tu módulo, define un paquete de pruebas de capturas de pantalla dentro del bloque testOptions:

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. Crea el conjunto de orígenes de prueba

Crea un directorio de conjunto de orígenes dedicado que coincida con el nombre de tu suite:

{module}/src/{suiteName}/kotlin/

Por ejemplo, para un conjunto de pruebas llamado screenshotTest, usa lo siguiente:

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. Cómo definir pruebas de vista previa de elementos componibles

Anota los elementos componibles con @PreviewTest y anotaciones estándar de @Preview o de vista previa múltiple:

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

Ejecuta pruebas de capturas de pantalla

Los conjuntos de pruebas del AGP generan tareas de Gradle específicas según el nombre, el destino y las variantes del conjunto.

1. Genera o actualiza imágenes de referencia

Renderiza vistas previas componibles y almacena las imágenes de referencia de la línea de base dorada:

• Linux y macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (por ejemplo, ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Las imágenes de referencia se generan y guardan en la siguiente ubicación:

{module}/src/{suiteName}{Target}{Variant}/reference/

2. Verifica y ejecuta pruebas

Renderiza capturas de pantalla nuevas y compáralas con imágenes de referencia:

• Linux y macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (por ejemplo, ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Cómo inspeccionar los informes de pruebas

Si se detectan diferencias o fallan las pruebas, AGP genera un informe de prueba en HTML.

• Ubicación del informe: {module}/build/reports/tests/{taskName}/index.html (por ejemplo, app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

El informe actualizado incluye lo siguiente:

• Tarjeta de metadatos del encabezado: Muestra el nombre de la prueba, el método de vista previa, la variante, el conjunto y la insignia de estado.
• Categorización de errores: Marca claramente Reference Image Missing, Image Size Mismatch o Pixel Mismatch con seguimientos de pila que se pueden copiar.
• Diferencia visual dinámica: Destaca las modificaciones sutiles con menor intensidad y los cambios importantes con un énfasis de alto contraste para evitar la pérdida de elementos anidados.

Migra desde el complemento independiente heredado

Para migrar del complemento heredado independiente de capturas de pantalla a los conjuntos de pruebas del AGP, actualiza la configuración de Gradle y los comandos de tareas.

Comparación del DSL de configuración de compilación

Complemento independiente heredado (obsoleto)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

Paquetes de pruebas de AGP (recomendado)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

Asignación de tareas y rutas