Prueba de captura de pantalla de la vista previa de Compose

La prueba de capturas de pantalla es una forma eficaz de verificar cómo se ve tu IU para los usuarios. La herramienta de prueba de capturas de pantalla de la versión preliminar de Compose combina la simplicidad y las funciones de vistas previas componibles con las ganancias de productividad de ejecutar pruebas de capturas de pantalla del host. La prueba de capturas de pantalla de la versión preliminar de Compose está diseñada para ser tan sencilla de usar como las vistas previas componibles.

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

Con la herramienta de prueba de capturas de pantalla de la versión preliminar de Compose, puedes hacer lo siguiente:

  • Usar @PreviewTest para crear pruebas de capturas de pantalla para vistas previas componibles existentes o nuevas
  • Generar imágenes de referencia a partir de esas vistas previas componibles
  • Generar un informe HTML que identifique los cambios en esas vistas previas después de realizar cambios en el código
  • Usar parámetros @Preview, como uiMode o fontScale, y vistas previas múltiples para ayudarte a escalar tus pruebas
  • Modularizar tus pruebas con el nuevo conjunto de fuentes screenshotTest
Figura 1. Ejemplo de informe HTML.

Integración en IDE

Si bien puedes usar la herramienta de prueba de capturas de pantalla de la versión preliminar de Compose 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 en el IDE. Esto te permite generar imágenes de referencia, ejecutar pruebas y analizar 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 capturas de pantalla. Ejecuta pruebas específicamente para una sola función o para una clase completa.
    • Agregar o actualizar imágenes de referencia. Activa el flujo de actualización específicamente para el alcance seleccionado.

  • Administración de referencias interactivas. Actualizar imágenes de referencia ahora es más seguro y detallado.
    • Nuevo diálogo de generación de imágenes de referencia. En lugar de ejecutar una tarea de Gradle masiva, un nuevo diálogo te permite visualizar y seleccionar exactamente qué vistas previas generar o actualizar.
    • Variaciones de vista previa. El diálogo muestra todas las variaciones de 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. Visualiza los resultados sin salir del IDE.
    • Panel de ejecución unificado. Los resultados de las pruebas de capturas de pantalla aparecen en la ventana de herramientas Run estándar. Las pruebas se agrupan por clase y función, con el estado de aprobación o falla claramente marcado.
    • Herramienta de diferencias visuales. Cuando falla una prueba, la pestaña Screenshot te permite comparar las imágenes Reference, Actual y Diff en paralelo.
    • Atributos detallados. Una pestaña Attributes proporciona metadatos sobre las pruebas fallidas, incluido el porcentaje de coincidencias, las dimensiones de la imagen y la configuración de vista previa específica que se usó (por ejemplo, uiMode o fontScale).

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

Requisitos

Para usar la prueba de capturas de pantalla de la versión preliminar de Compose a través de la integración completa en el IDE, tu proyecto debe cumplir con los siguientes requisitos:

  • Android Studio Panda 1 Canary 4 o versiones posteriores
  • Complemento de Android para Gradle (AGP) versión 9.0 o posterior
  • Complemento de prueba de capturas de pantalla de la versión preliminar de Compose versión 0.0.1-alpha14 o posterior
  • 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 en el IDE, los requisitos son los siguientes:

  • Complemento de Android para Gradle (AGP) versión 8.5.0 o posterior
  • Complemento de prueba de capturas de pantalla de la versión preliminar de Compose versión 0.0.1-alpha14 o posterior
  • Kotlin versión 1.9.20 o posterior Te recomendamos que uses Kotlin 2.0 o una versión posterior para que puedas 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 prueba de capturas de pantalla de la versión preliminar de Compose. 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 fuentes screenshotTest.

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

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

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

      [versions]
agp = "9.0.0-rc03"
kotlin = "2.1.20"
screenshot = "0.0.1-alpha14"

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

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

      plugins {
    alias(libs.plugins.screenshot)
}

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

    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 a tu archivo build.gradle.kts a nivel del módulo:

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

Designa vistas previas componibles para usar en pruebas de capturas de pantalla

Para designar las vistas previas componibles que quieres usar para las pruebas de capturas de pantalla, marca las vistas previas con la anotación @PreviewTest. Las vistas previas deben ubicarse en el nuevo conjunto de fuentes 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 archivos creados en el mismo conjunto de fuentes.

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 realizar cambios en el código. Para generar imágenes de referencia para tus pruebas de capturas de pantalla de la versión preliminar de Compose, sigue las instrucciones de esta sección para la integración en el 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 Add/Update Reference Images. Selecciona las vistas previas en el diálogo y haz clic en Add.

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 en el 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 el nombre de la prueba en el panel Run. Selecciona la pestaña Screenshot para inspeccionar la diferencia de la imagen con los controles integrados de zoom y paneo.

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.

Problemas conocidos

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

Puedes encontrar la lista completa de problemas conocidos actuales en el componente de Issue Tracker de la herramienta . Informa cualquier otro comentario y problemas a través del Issue Tracker.

Actualizaciones de lanzamientos

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