Test degli screenshot con le suite di test

A partire dal plug-in Android per Gradle (AGP) 9.5.0-alpha03 e dal motore di test degli screenshot di anteprima di Compose 0.0.1-alpha16, il test degli screenshot è integrato con il framework nativo delle suite di test di AGP.

Questo approccio sostituisce il plug-in di screenshot autonomo (com.android.compose.screenshot). Ti consigliamo di adottare le suite di test AGP per i seguenti motivi:

• Ciclo di vita nativo delle attività Gradle: i test degli screenshot si integrano direttamente nei cicli di vita standard dei test Gradle e AGP, migliorando l'isolamento delle attività e l'affidabilità dell'esecuzione dei test.
• Supporto di suite personalizzate e multivariante: puoi creare più suite di test degli screenshot distinte (ad esempio screenshotTest, uiTests o smokeTests) all'interno di un singolo modulo e scegliere come target varianti di compilazione specifiche (ad esempio demoDebug o release), anziché essere limitato a un singolo set di risorse preconfigurato.
• Isolamento e prestazioni di build migliorati: le suite di test AGP utilizzano trasformazioni di artefatti integrate (come l'estrazione di Layoutlib runtime) e il caricamento isolato delle classi, con supporto completo per la memorizzazione nella cache della configurazione Gradle e l'isolamento del progetto.

Requisiti

Per utilizzare Compose Screenshot Testing con le suite di test, assicurati che il tuo ambiente soddisfi i seguenti requisiti:

• Android Studio Rabbit 1 Canary 4 o versioni successive.
• Plug-in Android per Gradle (AGP) versione 9.5.0-alpha03 o successive.
• Compose Screenshot Engine versione 0.0.1-alpha16 o successive.
• JDK versione 17 o successiva.
• Compose è abilitato per il tuo progetto. Ti consigliamo di attivare Compose utilizzando il plug-in Gradle del compilatore Compose.

Impostazione e configurazione

Per configurare i test degli screenshot di Compose con le suite di test, completa i seguenti passaggi:

1. Abilita i flag sperimentali

Nel file gradle.properties nella radice del progetto, attiva i test degli screenshot e il supporto della suite di test:

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

2. Configura la suite di test nel file build.gradle.kts

Nel file build.gradle.kts del modulo, definisci una suite di test degli screenshot all'interno del blocco 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 il set di risorse di test

Crea una directory di set di risorse dedicata che corrisponda al nome della suite:

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

Ad esempio, per una suite denominata screenshotTest:

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

4. Definisci test di anteprima componibili

Annota i composable con @PreviewTest e le annotazioni standard @Preview o multi-preview:

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)
    }
}

Eseguire test degli screenshot

Le suite di test AGP generano attività Gradle dedicate in base al nome della suite, al target e alle varianti.

1. Generare o aggiornare le immagini di riferimento

Esegui il rendering delle anteprime componibili e memorizza le immagini di riferimento di base dorata:

• Linux e macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (ad esempio, ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Le immagini di riferimento vengono generate e salvate in:

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

2. Verifica ed esegui i test

Esegui il rendering di nuovi screenshot e confrontali con le immagini di riferimento:

• Linux e macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (ad esempio, ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Esaminare i report di test

Se vengono rilevate differenze o i test non riescono, AGP genera un report di test HTML.

• Posizione del report: {module}/build/reports/tests/{taskName}/index.html (ad esempio, app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

Il report aggiornato include:

• Scheda dei metadati dell'intestazione: mostra il nome del test, il metodo di anteprima, la variante, la suite e il badge di stato.
• Categorizzazione degli errori: contrassegna chiaramente Reference Image Missing, Image Size Mismatch o Pixel Mismatch con stack trace copiabili.
• Differenza visiva dinamica: evidenzia le modifiche lievi con un'intensità inferiore e quelle principali con un contrasto elevato per evitare l'incorporamento di elementi nidificati.

Esegui la migrazione dal plug-in autonomo legacy

Per eseguire la migrazione dal plug-in legacy autonomo per gli screenshot alle suite di test AGP, aggiorna la configurazione Gradle e i comandi delle attività.

Confronto tra DSL di configurazione di compilazione

Plug-in autonomo legacy (deprecato)

// 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")
}

Suite di test AGP (consigliate)

// 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")
            }
        }
    }
}

Mappatura di attività e percorsi