Test dello screenshot di anteprima di Scrivi

Attenzione: il plug-in com.android.compose.screenshot autonomo descritto in questa pagina non è più gestito. Ti consigliamo di configurare i test degli screenshot con le suite di test AGP utilizzando il plug-in Android per Gradle (AGP) 9.5 o versioni successive. Per cambiare, consulta Esegui la migrazione di un progetto esistente.

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

Competenze Android

Visualizza su GitHub

Crea test degli screenshot

Utilizza la competenza Android testing-setup per sviluppare una strategia di test e creare test degli screenshot.

Per installare lo skill dalla CLI Android, esegui:

android skills add testing-setup

Un test degli screenshot è un test automatico che acquisisce uno screenshot di una parte della UI e lo confronta con un'immagine di riferimento approvata in precedenza. Se le immagini non corrispondono, il test non va a buon fine e genera un report HTML per aiutarti a confrontare e trovare le differenze.

Con lo strumento di test degli screenshot di anteprima di Compose, puoi:

• Utilizza @PreviewTest per creare test degli screenshot per le anteprime componibili esistenti o nuove.
• Generare immagini di riferimento da queste anteprime componibili.
• Genera un report HTML che identifica le modifiche apportate a queste anteprime dopo aver apportato modifiche al codice.
• Utilizza i parametri @Preview, come uiMode o fontScale, e le anteprime multiple per scalare i test.
• Modularizza i test con il nuovo set di risorse screenshotTest.

Figura 1. Esempio di report HTML.

Integrazione con l'ambiente IDE

Sebweza puoi utilizzare lo strumento di test degli screenshot di anteprima di Compose eseguendo manualmente le attività Gradle sottostanti (updateScreenshotTest e validateScreenshotTest), Android Studio Otter 3 Feature Drop Canary 4 introduce un'integrazione completa con l'IDE. 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 del margine interno dell'editor. Ora puoi eseguire test o aggiornare le immagini di riferimento direttamente dal codice sorgente. Le icone di esecuzione verdi vengono visualizzate nel margine accanto ai componibili e alle classi annotate con @PreviewTest.
  • Esegui test degli screenshot. Esegui i 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.
  • Visualizza l'anteprima delle varianti. La finestra di dialogo elenca singolarmente tutte le varianti di 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 del test degli screenshot vengono visualizzati nella finestra degli strumenti standard Esegui. I test sono raggruppati per classe e funzione, con lo stato di superamento o mancato superamento chiaramente contrassegnato.
  • Strumento di confronto visivo. Quando un test non va a buon fine, la scheda Screenshot ti consente di confrontare le immagini Riferimento, Effettivo e Diff affiancate.
  • Attributi dettagliati. La scheda Attributi fornisce i metadati sui test non riusciti, tra cui la percentuale di corrispondenza, le dimensioni dell'immagine e la configurazione di anteprima specifica utilizzata (ad esempio uiMode o fontScale).

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

Requisiti

Nota: per i requisiti e le istruzioni di configurazione delle suite di test AGP, consulta Suite di test AGP.

Per utilizzare il test degli screenshot di anteprima di Compose tramite l'integrazione completa dell'IDE, il tuo 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 successive.
• Versione del plug-in Compose Preview Screenshot Testing 0.0.1-alpha16 o successiva.
• Kotlin versione 2.2.10 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.

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

• Plug-in Android per Gradle (AGP) versione 8.5.0 o successive.
• Versione del plug-in Compose Preview Screenshot Testing 0.0.1-alpha16 o successiva.
• Kotlin versione 1.9.20 o 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 successiva.
• Compose abilitato per il tuo progetto. Ti consigliamo di attivare Compose utilizzando il plug-in Gradle del compilatore Compose.

Nota: se non puoi utilizzare il plug-in Gradle del compilatore Compose, puoi attivare Compose dichiarando una dipendenza direttamente sul compilatore Compose. Assicurati di utilizzare la versione 1.5.4 o successive di kotlinCompilerExtensionVersion.

Configurazione

Sia lo strumento integrato sia le attività Gradle sottostanti si basano sul plug-in Compose Preview Screenshot Testing. Per impostare il plug-in, procedi nel seguente modo:

1. Attiva 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, attiva il flag sperimentale per utilizzare il set di risorse screenshotTest.

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

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

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

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

      plugins {
          alias(libs.plugins.screenshot)
      }
      

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

   1. Aggiungile ai tuoi 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 risorse 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 apportato modifiche al codice. Per generare immagini di riferimento per i test degli screenshot di anteprima componibili, segui le istruzioni riportate in questa sezione per l'integrazione dell'IDE o per le attività Gradle.

CLI Android

Scarica l'interfaccia a riga di comando Android

Prova la CLI Android per eseguire il rendering di un'anteprima di Compose

Prova CLI Android se non utilizzi Android Studio o preferisci eseguire le operazioni dalla riga di comando.

Ad esempio, utilizza il comando android studio render-compose-preview quando devi eseguire il rendering di un'anteprima di Compose per i test visivi.

android studio render-compose-preview

Nell'IDE

Fai clic sull'icona del margine 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 questa 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).

Nota: i nomi delle immagini di riferimento sono formati dalla concatenazione del nome completo della funzione di test e da un hash dei parametri di anteprima, ad esempio com.sample.screenshottests.test1_da39a3ee_c2200e98_0.png.

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 dell'IDE o per le attività Gradle.

Nell'IDE

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

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

Nota: la ridenominazione di una funzione annotata con @PreviewTest interrompe l'associazione con le immagini di riferimento esistenti. In questo caso, devi rigenerare le immagini di riferimento per il nuovo nome della funzione.

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

Compose Preview Screenshot Testing 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 target non Android nei progetti KMP.

Puoi trovare l'elenco completo dei problemi noti attuali nel componente Issue Tracker dello strumento. Segnala eventuali altri feedback e problemi tramite l'Issue Tracker.

Aggiornamenti della pubblicazione

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