Prueba de captura de pantalla de la vista previa de Compose

Las pruebas de captura de pantalla son una forma eficaz de verificar cómo se ve tu IU para los usuarios. La herramienta Compose Preview Screenshot Testing combina la simplicidad y las funciones de las vistas previas de componibilidad con las mejoras de productividad que se obtienen al ejecutar pruebas de captura de pantalla del host. Las pruebas de capturas de pantalla de la vista previa de Compose están diseñadas para ser tan fáciles de usar como las vistas previas de elementos de componibilidad.

Una prueba de captura de pantalla es una prueba automatizada que toma una captura de pantalla de un elemento de la IU y, luego, la compara con una imagen de referencia aprobada anteriormente. Si las imágenes no coinciden, la prueba falla y produce un informe HTML para ayudarte a comparar y encontrar las diferencias.

Con la herramienta Compose Preview Screenshot Testing, puedes hacer lo siguiente:

  • Usa @PreviewTest para crear pruebas de captura de pantalla para vistas previas de funciones de componibilidad nuevas o existentes.
  • Generar imágenes de referencia a partir de esas vistas previas de elementos componibles
  • Genera un informe HTML que identifique los cambios en esas vistas previas después de que realices cambios en el código.
  • Usa parámetros de @Preview, como uiMode o fontScale, y vistas previas múltiples para escalar tus pruebas.
  • Modulariza tus pruebas con el nuevo conjunto de orígenes screenshotTest.
Figura 1. Ejemplo de informe HTML.

Integración con IDE

Si bien puedes usar la herramienta de pruebas de capturas de pantalla de Compose Preview ejecutando las tareas de Gradle subyacentes (updateScreenshotTest y validateScreenshotTest) de forma manual, Android Studio Otter 3 Feature Drop Canary 4 presenta una integración completa del IDE. Esto te permite generar imágenes de referencia, ejecutar pruebas y analizar las fallas de validación por completo dentro del IDE. Estas son algunas de las funciones clave:

  • Íconos de margen en el editor Ahora puedes ejecutar pruebas o actualizar imágenes de referencia directamente desde el código fuente. Los íconos de ejecución verdes aparecen en el margen junto a los elementos componibles y las clases anotadas con @PreviewTest.
    • Ejecutar pruebas de captura de pantalla Ejecuta pruebas específicamente para una sola función o para una clase completa.
    • Agrega o actualiza imágenes de referencia. Activa el flujo de actualización específicamente para el permiso seleccionado.

  • Administración interactiva de referencias La actualización de las imágenes de referencia ahora es más segura y detallada.
    • Nuevo diálogo de generación de imágenes de referencia. En lugar de ejecutar una tarea de Gradle masiva, un diálogo nuevo te permite visualizar y seleccionar exactamente qué vistas previas generar o actualizar.
    • Obtén una vista previa de las variaciones. En el diálogo, se enumeran todas las variaciones de la vista previa (como el tema claro o el tema oscuro, o diferentes dispositivos) de forma individual, lo que te permite seleccionar o borrar elementos específicos antes de generar imágenes.

  • Resultados de pruebas integrados y visor de diferencias Consulta los resultados sin salir del IDE.
    • Panel de ejecución unificado. Los resultados de las pruebas de captura de pantalla aparecen en la ventana de herramientas estándar Run. Las pruebas se agrupan por clase y función, y se indica claramente si se aprobaron o no.
    • Herramienta de diferencias visuales. Cuando falla una prueba, la pestaña Captura de pantalla te permite comparar las imágenes de referencia, reales y de diferencia en paralelo.
    • Atributos detallados. La pestaña Attributes proporciona metadatos sobre las pruebas con errores, incluido el porcentaje de coincidencia, las dimensiones de la imagen y la configuración de vista previa específica que se usó (por ejemplo, uiMode o fontScale).

  • Alcance de pruebas flexible. Ahora puedes ejecutar pruebas de capturas de pantalla con varios alcances directamente desde la vista Project. Haz clic con el botón derecho en un módulo, directorio, archivo o clase para ejecutar pruebas de captura de pantalla específicamente para esa selección.

Requisitos

Para usar las pruebas de capturas de pantalla de la vista previa de Compose a través de la integración completa del IDE, tu proyecto debe cumplir con los siguientes requisitos:

  • Android Studio Panda 1 Canary 4 o una versión posterior
  • Complemento de Android para Gradle (AGP) versión 9.0 o posterior
  • Versión 0.0.1-alpha16 o posterior del complemento de Compose Preview Screenshot Testing
  • Kotlin versión 2.2.10 o posterior
  • JDK versión 17 o posterior
  • Compose habilitado para tu proyecto Te recomendamos que habilites Compose con el complemento de Gradle del compilador de Compose.

Si solo quieres usar las tareas de Gradle subyacentes sin la integración del IDE, los requisitos son los siguientes:

  • Complemento de Android para Gradle (AGP) versión 8.5.0 o posterior
  • Versión 0.0.1-alpha16 o posterior del complemento de Compose Preview Screenshot Testing
  • Kotlin versión 1.9.20 o posterior Te recomendamos que uses Kotlin 2.0 o una versión posterior para poder usar el complemento de Gradle del compilador de Compose.
  • JDK versión 17 o posterior
  • Compose habilitado para tu proyecto Te recomendamos que habilites Compose con el complemento de Gradle del compilador de Compose.

Configuración

Tanto la herramienta integrada como las tareas de Gradle subyacentes dependen del complemento de Compose Preview Screenshot Testing. Para configurar el complemento, sigue estos pasos:

  1. Habilita la propiedad experimental en el archivo gradle.properties de tu proyecto.

    android.experimental.enableScreenshotTest=true

  2. En el bloque android {} de tu archivo build.gradle.kts a nivel del módulo, habilita la marca experimental para usar el conjunto de orígenes screenshotTest.

    android {
    experimentalProperties["android.experimental.enableScreenshotTest"] = true
}

  3. Agrega el complemento com.android.compose.screenshot, versión 0.0.1-alpha16, a tu proyecto.

    1. Agrega el complemento a tu archivo de catálogos de versiones:

      [versions]
agp = "9.0.0-rc03"
kotlin = "2.2.10"
screenshot = "0.0.1-alpha16"

[plugins]
screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}

    2. En el archivo build.gradle.kts a nivel del módulo, agrega el complemento en el bloque plugins {}:

      plugins {
    alias(libs.plugins.screenshot)
}

  4. Agrega las dependencias screenshot-validation-api y ui-tooling.

    1. Agrégalas a tus catálogos de versiones:

      [libraries]
screenshot-validation-api = { group = "com.android.tools.screenshot", name = "screenshot-validation-api", version.ref = "screenshot"}
androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling"}

    2. Agrégalas al archivo build.gradle.kts a nivel del módulo:

      dependencies {
  screenshotTestImplementation(libs.screenshot.validation.api)
  screenshotTestImplementation(libs.androidx.ui.tooling)
}

Designa vistas previas de funciones de componibilidad para usarlas en las pruebas de captura de pantalla

Para designar las vistas previas de funciones de componibilidad que quieras usar en las pruebas de captura de pantalla, márcalas con la anotación @PreviewTest. Las vistas previas deben ubicarse en el nuevo conjunto de orígenes screenshotTest, por ejemplo:

app/src/screenshotTest/kotlin/com/example/yourapp/ ExamplePreviewScreenshotTest.kt

Puedes agregar más elementos componibles o vistas previas, incluidas las vistas previas múltiples, en este archivo o en otros creados en el mismo conjunto de orígenes.

package com.example.yourapp

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

@PreviewTest
@Preview(showBackground = true)
@Composable
fun GreetingPreview() {
    MyApplicationTheme {
        Greeting("Android!")
    }
}

Genera imágenes de referencia

Después de configurar una clase de prueba, debes generar imágenes de referencia para cada vista previa. Estas imágenes de referencia se usan para identificar cambios más adelante, después de que realices cambios en el código. Para generar imágenes de referencia para tus pruebas de captura de pantalla de vista previa de elementos componibles, sigue las instrucciones de esta sección para la integración del IDE o para las tareas de Gradle.

En el IDE

Haz clic en el ícono de margen junto a una función @PreviewTest y selecciona Agregar/actualizar imágenes de referencia. Selecciona las vistas previas en el cuadro de diálogo y haz clic en Agregar.

Con las tareas de Gradle

Ejecuta la siguiente tarea de Gradle:

  • Linux y macOS: ./gradlew updateDebugScreenshotTest (./gradlew :{module}:update{Variant}ScreenshotTest)
  • Windows: gradlew updateDebugScreenshotTest (gradlew :{module}:update{Variant}ScreenshotTest)

Una vez que se complete la tarea, busca las imágenes de referencia en app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Genera un informe de prueba

Una vez que existan las imágenes de referencia, genera un informe de prueba siguiendo las instrucciones de esta sección para la integración del IDE o para las tareas de Gradle.

En el IDE

Haz clic en el ícono de margen junto a una función @PreviewTest y selecciona Run 'ScreenshotTests'.

Si una prueba falla, haz clic en su nombre en el panel Run. Selecciona la pestaña Screenshot para inspeccionar la diferencia de imagen con los controles integrados de zoom y desplazamiento lateral.

Con las tareas de Gradle

Ejecuta la tarea de validación para tomar una nueva captura de pantalla y compararla con la imagen de referencia:

  • Linux y macOS: ./gradlew validateDebugScreenshotTest (./gradlew :{module}:validate{Variant}ScreenshotTest)
  • Windows: gradlew validateDebugScreenshotTest (gradlew :{module}:validate{Variant}ScreenshotTest)

La tarea de verificación crea un informe HTML en {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Solución de problemas

Las pruebas de captura de pantalla de la vista previa de Compose ejecutan pruebas del lado del host, que pueden consumir mucha memoria. Puedes aumentar el tamaño máximo del montón para la JVM de prueba agregando la siguiente propiedad a tu archivo gradle.properties:

android.compose.screenshot.maxHeapSize=4g

Problemas conocidos

  • Kotlin Multiplatform (KMP): Tanto el IDE como el complemento subyacente están diseñados exclusivamente para proyectos de Android. No admiten destinos que no sean de Android en proyectos de KMP.

Puedes encontrar la lista completa de los problemas conocidos actuales en el componente de seguimiento de errores de la herramienta. Informa cualquier otro comentario y problema a través de la herramienta de seguimiento de errores.

Actualizaciones de lanzamientos

Para obtener una lista completa de las actualizaciones de la versión, consulta las notas de la versión.