Test dello screenshot di anteprima di Scrivi

Il test degli screenshot è un modo efficace per verificare l'aspetto dell'interfaccia utente per gli utenti. Lo strumento di test degli screenshot dell'anteprima di Compose combina la semplicità e le funzionalità delle anteprime componibili con i vantaggi in termini di produttività derivanti dall'esecuzione di test degli screenshot lato host. Il test degli screenshot dell'anteprima di Compose è progettato per essere semplice da usare come le anteprime componibili.

Un test degli screenshot è un test automatizzato che acquisisce uno screenshot di una parte dell'interfaccia utente e lo confronta con un'immagine di riferimento approvata in precedenza. Se le immagini non corrispondono, il test non riesce e genera un report HTML per aiutarti a confrontare e trovare le differenze.

Con lo strumento di test degli screenshot dell'anteprima di Compose puoi:

  • Utilizzare @PreviewTest per creare test degli screenshot per le anteprime componibili esistenti o nuove.
  • Generare immagini di riferimento da queste anteprime componibili.
  • Generare un report HTML che identifichi le modifiche apportate a queste anteprime dopo aver modificato il codice.
  • Utilizzare i parametri @Preview, come uiMode o fontScale, e le anteprime multiple per scalare i test.
  • Modularizzare i test con il nuovo set di origine screenshotTest.
Figura 1. Report HTML di esempio.

Integrazione con l'ambiente IDE

Sebbene tu possa utilizzare lo strumento di test degli screenshot dell'anteprima di Compose eseguendo manualmente le attività Gradle sottostanti (updateScreenshotTest e validateScreenshotTest), Android Studio Otter 3 Feature Drop Canary 4 introduce un'integrazione IDE completa. In questo modo puoi generare immagini di riferimento, eseguire test e analizzare gli errori di convalida interamente all'interno dell'IDE. Ecco alcune delle funzionalità principali:

  • Icone nella gutter dell'editor. Ora puoi eseguire test o aggiornare le immagini di riferimento direttamente dal codice sorgente. Nella gutter accanto ai componibili e alle classi annotate con @PreviewTest vengono visualizzate icone di esecuzione verdi.
    • Esegui test degli screenshot. Esegui test specificamente per una singola funzione o per un'intera classe.
    • Aggiungi o aggiorna le immagini di riferimento. Attiva il flusso di aggiornamento specificamente per l'ambito selezionato.

  • Gestione interattiva dei riferimenti. L'aggiornamento delle immagini di riferimento è ora più sicuro e granulare.
    • Nuova finestra di dialogo per la generazione di immagini di riferimento. Anziché eseguire un'attività Gradle collettiva, una nuova finestra di dialogo ti consente di visualizzare e selezionare esattamente le anteprime da generare o aggiornare.
    • Variazioni dell'anteprima. La finestra di dialogo elenca singolarmente tutte le varianti dell'anteprima (ad esempio tema chiaro o tema scuro o dispositivi diversi), consentendoti di selezionare o deselezionare elementi specifici prima di generare le immagini.

  • Risultati dei test integrati e visualizzatore delle differenze. Visualizza i risultati senza uscire dall'IDE.
    • Riquadro di esecuzione unificato. I risultati dei test degli screenshot vengono visualizzati nella finestra degli strumenti Esegui standard. I test sono raggruppati per classe e funzione, con lo stato di superamento o errore chiaramente indicato.
    • Strumento di differenze visive. Quando un test non riesce, la scheda Screenshot ti consente di confrontare le immagini Riferimento, Effettiva e Differenza affiancate.
    • Attributi dettagliati. Una scheda Attributi fornisce i metadati sui test non riusciti, inclusa la percentuale di corrispondenza, le dimensioni dell'immagine e la configurazione dell'anteprima specifica utilizzata (ad esempio, uiMode o fontScale).

  • Ambito di test flessibile. Ora puoi eseguire test degli screenshot con vari ambiti direttamente dalla visualizzazione Progetto. Fai clic con il tasto destro del mouse su un modulo, una directory, un file o una classe per eseguire test degli screenshot specificamente per la selezione.

Requisiti

Per utilizzare il test degli screenshot dell'anteprima di Compose tramite l'integrazione IDE completa, il progetto deve soddisfare i seguenti requisiti:

  • Android Studio Panda 1 Canary 4 o versioni successive.
  • Plug-in Android per Gradle (AGP) versione 9.0 o versioni successive.
  • Plug-in di test degli screenshot dell'anteprima di Compose versione 0.0.1-alpha14 o versioni successive.
  • Kotlin versione 2.2.10 o versioni successive.
  • JDK versione 17 o versioni successive.
  • Compose abilitato per il progetto. Ti consigliamo di abilitare Compose utilizzando il plug-in Gradle del compilatore Compose.

Se vuoi utilizzare solo le attività Gradle sottostanti senza l'integrazione IDE, i requisiti sono i seguenti:

  • Plug-in Android per Gradle (AGP) versione 8.5.0 o versioni successive.
  • Plug-in di test degli screenshot dell'anteprima di Compose versione 0.0.1-alpha14 o versioni successive.
  • Kotlin versione 1.9.20 o versioni successive. Ti consigliamo di utilizzare Kotlin 2.0 o versioni successive per poter utilizzare il plug-in Gradle del compilatore Compose.
  • JDK versione 17 o versioni successive.
  • Compose abilitato per il progetto. Ti consigliamo di abilitare Compose utilizzando il plug-in Gradle del compilatore Compose.

Configurazione

Sia lo strumento integrato sia le attività Gradle sottostanti si basano sul plug-in di test degli screenshot dell'anteprima di Compose. Per impostare il plug-in, procedi nel seguente modo:

  1. Abilita la proprietà sperimentale nel file gradle.properties del progetto.

    android.experimental.enableScreenshotTest=true

  2. Nel blocco android {} del file build.gradle.kts a livello di modulo, abilita il flag sperimentale per utilizzare il set di origine screenshotTest.

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

  3. Aggiungi il plug-in com.android.compose.screenshot, versione 0.0.1-alpha14, al tuo progetto.

    1. Aggiungi il plug-in al file dei cataloghi delle versioni:

      [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. Nel file build.gradle.kts a livello di modulo, aggiungi il plug-in nel blocco plugins {}:

      plugins {
    alias(libs.plugins.screenshot)
}

  4. Aggiungi le screenshot-validation-api e ui-tooling dipendenze.

    1. Aggiungile ai cataloghi delle versioni:

      [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. Aggiungile al file build.gradle.kts a livello di modulo:

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

Designa le anteprime componibili da utilizzare per i test degli screenshot

Per designare le anteprime componibili che vuoi utilizzare per i test degli screenshot, contrassegnale con l'annotazione @PreviewTest. Le anteprime devono trovarsi nel nuovo set di origine screenshotTest, ad esempio:

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

Puoi aggiungere altri componibili o anteprime, incluse le anteprime multiple, in questo file o in altri file creati nello stesso set di risorse.

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 immagini di riferimento

Dopo aver configurato una classe di test, devi generare immagini di riferimento per ogni anteprima. Queste immagini di riferimento vengono utilizzate per identificare le modifiche in un secondo momento, dopo aver modificato il codice. Per generare immagini di riferimento per i test degli screenshot dell'anteprima componibile, segui le istruzioni riportate in questa sezione per l'integrazione IDE o per le attività Gradle.

Nell'IDE

Fai clic sull'icona nella gutter accanto a una funzione @PreviewTest e seleziona Aggiungi/aggiorna immagini di riferimento. Seleziona le anteprime nella finestra di dialogo e fai clic su Aggiungi.

Con le attività Gradle

Esegui la seguente attività Gradle:

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

Al termine dell'attività, trova le immagini di riferimento in app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Genera un report di test

Una volta create le immagini di riferimento, genera un report di test seguendo le istruzioni riportate in questa sezione per l'integrazione IDE o per le attività Gradle.

Nell'IDE

Fai clic sull'icona nella gutter accanto a una funzione @PreviewTest e seleziona Esegui "ScreenshotTests".

Se un test non riesce, fai clic sul nome del test nel riquadro Esegui. Seleziona la scheda Screenshot per esaminare la differenza tra le immagini utilizzando i controlli di zoom e panoramica integrati.

Con le attività Gradle

Esegui l'attività di convalida per acquisire un nuovo screenshot e confrontarlo con l'immagine di riferimento:

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

L'attività di verifica crea un report HTML in {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Risoluzione dei problemi

Il test degli screenshot dell'anteprima di Compose esegue test lato host, che possono richiedere molta memoria. Puoi aumentare la dimensione massima dell'heap per la JVM di test aggiungendo la seguente proprietà al file gradle.properties:

android.compose.screenshot.maxHeapSize=4g

Problemi noti

  • Kotlin Multiplatform (KMP): sia l'IDE sia il plug-in sottostante sono progettati esclusivamente per i progetti Android. Non supportano i target non Android nei progetti KMP.

Puoi trovare l'elenco completo dei problemi noti attuali nel componente di monitoraggio dei problemi dello strumento issue tracker. Segnala eventuali altri feedback e problemi tramite lo strumento di monitoraggio dei problemi.

Aggiornamenti della pubblicazione

Per un elenco completo degli aggiornamenti della pubblicazione, consulta le note di rilascio.