Test dello screenshot di anteprima di Scrivi

Sperimentale: il test degli screenshot di anteprima della composizione è ancora in fase di sviluppo. Le sue funzionalità e API sono soggette a modifiche sostanziali durante la fase alpha. Segnala eventuali feedback e problemi tramite lo strumento di monitoraggio dei problemi.

Il test degli screenshot è un modo efficace per verificare l'aspetto della tua 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à derivanti dall'esecuzione di test degli screenshot lato host. Il test degli screenshot dell'anteprima di composizione è progettato per essere semplice da usare come le anteprime componibili.

Un test dello 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 va a buon fine e viene generato un report HTML per aiutarti a confrontare e trovare le differenze.

Con lo strumento di test degli screenshot di anteprima della composizione, puoi:

• Utilizza @PreviewTest per creare test degli screenshot per le anteprime di componenti componibili esistenti o nuovi.
• Genera immagini di riferimento da queste anteprime componibili.
• Genera un report HTML che identifichi le modifiche apportate alle anteprime dopo aver modificato il codice.
• Utilizza i parametri @Preview, come uiMode o fontScale, e le anteprime multiple per aiutarti a scalare i test.
• Rendi modulari i tuoi test con il nuovo set di risorse screenshotTest.

Figura 1. Esempio di report HTML.

Integrazione con l'IDE

Anche se puoi utilizzare lo strumento di test degli screenshot di Compose Preview eseguendo manualmente le attività Gradle sottostanti (updateScreenshotTest e validateScreenshotTest), Android Studio Otter 3 Feature Drop Canary 4 introduce un'integrazione completa dell'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 della gutter nell'editor. Ora puoi eseguire test o aggiornare le immagini di riferimento direttamente dal codice sorgente. Le icone di esecuzione verdi vengono visualizzate nel gutter accanto ai composable e alle classi annotati con @PreviewTest.
  • Esegui test degli screenshot. Esegui test specifici per una singola funzione o per un'intera classe.
  • Aggiungi o aggiorna le immagini di riferimento. Attiva il flusso di aggiornamento in modo specifico 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 in blocco, 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.

• Visualizzatore delle differenze e risultati dei test integrati. Visualizza i risultati senza uscire dall'IDE.
  • Pannello di esecuzione unificato. I risultati del test degli screenshot vengono visualizzati nella finestra standard dello strumento Run. I test sono raggruppati per classe e funzione, con lo stato di superamento o non superamento chiaramente indicato.
  • Strumento di confronto visivo. Quando un test non va a buon fine, la scheda Screenshot ti consente di confrontare le immagini Riferimento, Effettivo e Differenza affiancate.
  • Attributi dettagliati. Una scheda Attributi fornisce i metadati relativi ai 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).

• Definizione flessibile dell'ambito del test. 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 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.
• Plugin di test degli screenshot di anteprima di Compose versione 0.0.1-alpha14 o successive.
• Kotlin versione 2.2.10 o successive.
• JDK versione 17 o successive.
• Compose è abilitato per il tuo 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 dell'IDE, i requisiti sono i seguenti:

• Plug-in Android per Gradle (AGP) versione 8.5.0 o successive.
• Plugin di test degli screenshot di anteprima di Compose versione 0.0.1-alpha14 o successive.
• Kotlin 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 successive.
• Compose è abilitato per il tuo progetto. Ti consigliamo di abilitare 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 dal compilatore Compose direttamente. Assicurati di utilizzare kotlinCompilerExtensionVersion versione 1.5.4 o successive.

Configura

Sia lo strumento integrato sia le attività Gradle sottostanti si basano sul plug-in di test degli screenshot di anteprima di Compose. Per configurare il plug-in:

1. Abilita la proprietà sperimentale nel file gradle.properties del tuo 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-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 dipendenze screenshot-validation-api e ui-tooling.

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

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

Designare le anteprime componibili da utilizzare per i test degli screenshot

Per indicare 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!")
    }
}

Generare 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 componibile, segui le istruzioni riportate in questa sezione per l'integrazione dell'IDE o per le attività Gradle.

Nell'IDE

Fai clic sull'icona della canaletta 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).

Nota: le immagini di riferimento vengono denominate con una concatenazione del nome completo della funzione di test e un hash dei parametri di anteprima, ad esempio com.sample.screenshottests.test1_da39a3ee_c2200e98_0.png.

Generare 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 della canaletta 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: se rinomini una funzione annotata con @PreviewTest, l'associazione con le immagini di riferimento esistenti viene interrotta. 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 all'indirizzo {module}/build/reports/screenshotTest/preview/{variant}/index.html.

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 di monitoraggio dei problemi dello strumento. Segnala eventuali altri feedback e problemi tramite lo strumento di monitoraggio dei problemi.

Aggiornamenti delle versioni

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