Testowanie zrzutu ekranu w podglądzie tworzenia

Testowanie zrzutów ekranu to skuteczny sposób na sprawdzenie, jak interfejs użytkownika wygląda dla użytkowników. Narzędzie do testowania zrzutów ekranu w podglądzie funkcji Compose łączy prostotę i funkcje podglądów funkcji do komponowania ze wzrostem produktywności wynikającym z przeprowadzania testów zrzutów ekranu po stronie hosta. Testowanie zrzutów ekranu w widoku tworzenia jest tak samo proste w użyciu jak podglądy komponentów.

Test zrzutu ekranu to test automatyczny, który robi zrzut ekranu fragmentu interfejsu, a następnie porównuje go z wcześniej zatwierdzonym obrazem referencyjnym. Jeśli obrazy nie pasują do siebie, test zakończy się niepowodzeniem i wygeneruje raport HTML, który pomoże Ci porównać obrazy i znaleźć różnice.

Za pomocą narzędzia do testowania zrzutów ekranu podglądu tworzenia możesz:

• Użyj @PreviewTest, aby utworzyć testy zrzutów ekranu dla istniejących lub nowych podglądów komponentów.
• Generowanie obrazów referencyjnych na podstawie tych podglądów.
• Wygeneruj raport HTML, który po wprowadzeniu zmian w kodzie będzie zawierać informacje o zmianach w tych podglądach.
• Używaj parametrów @Preview, takich jak uiMode lub fontScale, oraz wielu podglądów, aby skalować testy.
• Podziel testy na moduły za pomocą nowego zbioru źródeł screenshotTest.

Integracja z IDE

Narzędzia do testowania zrzutów ekranu w Compose Preview możesz używać, ręcznie uruchamiając podstawowe zadania Gradle (updateScreenshotTest i validateScreenshotTest), ale pakiet nowych funkcji Android Studio Otter 3 Canary 4 wprowadza pełną integrację z IDE. Dzięki temu możesz generować obrazy referencyjne, przeprowadzać testy i analizować błędy weryfikacji w środowisku IDE. Oto niektóre z najważniejszych funkcji:

• Ikony na marginesie w edytorze. Możesz teraz uruchamiać testy lub aktualizować obrazy referencyjne bezpośrednio z kodu źródłowego. Zielone ikony uruchomienia pojawiają się w marginesie obok funkcji kompozycyjnych i klas oznaczonych adnotacją @PreviewTest.
  • Przeprowadzanie testów zrzutów ekranu Uruchamiaj testy dotyczące konkretnej funkcji lub całej klasy.
  • Dodaj lub zaktualizuj obrazy referencyjne. Uruchom proces aktualizacji dla wybranego zakresu.

• Interaktywne zarządzanie odwołaniami. Aktualizowanie obrazów referencyjnych jest teraz bezpieczniejsze i bardziej szczegółowe.
  • Nowe okno generowania obrazu referencyjnego. Zamiast uruchamiać zadanie Gradle w trybie zbiorczym, możesz w nowym oknie wybrać, które podglądy chcesz wygenerować lub zaktualizować.
  • Wyświetl podgląd odmian. W oknie dialogowym wyświetlają się wszystkie wersje podglądu (np. motyw jasny lub ciemny albo różne urządzenia), co umożliwia zaznaczenie lub odznaczenie poszczególnych elementów przed wygenerowaniem obrazów.

• Zintegrowane wyniki testów i przeglądarka różnic. Wyświetlaj wyniki bez opuszczania środowiska IDE.
  • Ujednolicony panel uruchamiania Wyniki testu zrzutu ekranu pojawią się w standardowym oknie narzędzia Uruchom. Testy są pogrupowane według klasy i funkcji, a stan zaliczenia lub niezaliczenia jest wyraźnie oznaczony.
  • Narzędzie do porównywania wizualnego Jeśli test się nie powiedzie, na karcie Zrzut ekranu możesz porównać obok siebie obrazy Referencyjny, Rzeczywisty i Różnica.
  • Szczegółowe atrybuty Karta Atrybuty zawiera metadane dotyczące nieudanych testów, w tym procent dopasowania, wymiary obrazu i użytą konfigurację podglądu (np. uiMode lub fontScale).

• Elastyczny zakres testów. Możesz teraz przeprowadzać testy zrzutów ekranu w różnych zakresach bezpośrednio z widoku projektu. Kliknij prawym przyciskiem myszy moduł, katalog, plik lub klasę, aby uruchomić testy zrzutów ekranu dla wybranego elementu.

Wymagania

Aby korzystać z testowania zrzutów ekranu podglądu Compose w ramach pełnej integracji z IDE, projekt musi spełniać te wymagania:

• Android Studio Panda 1 Canary 4 lub nowszy.
• Wtyczka Androida do obsługi Gradle (AGP) w wersji 9.0 lub nowszej.
• Wtyczka do testowania zrzutów ekranu w widoku tworzenia w wersji 0.0.1-alpha14 lub nowszej.
• Kotlin w wersji 2.2.10 lub nowszej.
• JDK w wersji 17 lub nowszej.
• Compose jest włączony w Twoim projekcie. Zalecamy włączenie Compose za pomocą wtyczki Gradle kompilatora Compose.

Jeśli chcesz używać tylko podstawowych zadań Gradle bez integracji z IDE, musisz spełnić te wymagania:

• Wtyczka Androida do obsługi Gradle (AGP) w wersji 8.5.0 lub nowszej.
• Wtyczka do testowania zrzutów ekranu w widoku tworzenia w wersji 0.0.1-alpha14 lub nowszej.
• Kotlin w wersji 1.9.20 lub nowszej. Zalecamy używanie Kotlin w wersji 2.0 lub nowszej, aby móc korzystać z wtyczki Gradle kompilatora Compose.
• JDK w wersji 17 lub nowszej.
• Compose jest włączony w Twoim projekcie. Zalecamy włączenie Compose za pomocą wtyczki Gradle kompilatora Compose.

Konfiguracja

Zarówno zintegrowane narzędzie, jak i powiązane z nim zadania Gradle korzystają z wtyczki Compose Preview Screenshot Testing. Aby skonfigurować wtyczkę, wykonaj te czynności:

1. Włącz właściwość eksperymentalną w pliku gradle.properties projektu.

   android.experimental.enableScreenshotTest=true
   

2. W bloku android {} pliku build.gradle.kts na poziomie modułu włącz flagę eksperymentalną, aby używać zbioru źródeł screenshotTest.

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

3. Dodaj wtyczkę com.android.compose.screenshot w wersji 0.0.1-alpha14 do projektu.

   1. Dodaj wtyczkę do pliku katalogów wersji:

      [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. W pliku build.gradle.kts na poziomie modułu dodaj wtyczkę w bloku plugins {}:

      plugins {
          alias(libs.plugins.screenshot)
      }
      

4. Dodaj zależności screenshot-validation-api i ui-tooling.

   1. Dodaj je do katalogów wersji:

      [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. Dodaj je do pliku build.gradle.kts na poziomie modułu:

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

Wyznaczanie podglądów kompozycyjnych do użycia w testach zrzutów ekranu

Aby wskazać podglądy funkcji kompozycyjnych, których chcesz użyć w testach zrzutów ekranu, oznacz je adnotacją @PreviewTest. Wersje przedpremierowe muszą znajdować się w nowym zestawie źródeł screenshotTest, np.:

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

W tym pliku lub w innych plikach utworzonych w tym samym zestawie źródeł możesz dodać więcej funkcji kompozycyjnych lub podglądów, w tym podglądów wielokrotnych.

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

Generowanie obrazów referencyjnych

Po skonfigurowaniu klasy testowej musisz wygenerować obrazy referencyjne dla każdego podglądu. Obrazy referencyjne są używane do identyfikowania zmian w późniejszym czasie, po wprowadzeniu zmian w kodzie. Aby wygenerować obrazy referencyjne do testów zrzutów ekranu kompozycji podglądu, postępuj zgodnie z instrukcjami w tej sekcji dotyczącymi integracji z IDE lub zadań Gradle.

W IDE

Kliknij ikonę rynny obok funkcji @PreviewTest i wybierz Dodaj/zaktualizuj obrazy referencyjne. Wybierz podglądy w oknie i kliknij Dodaj.

Za pomocą zadań w Gradle

Uruchom to zadanie Gradle:

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

Po zakończeniu zadania znajdź obrazy referencyjne w folderze app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Generowanie raportu testowego

Gdy obrazy referencyjne będą już dostępne, wygeneruj raport z testu, postępując zgodnie z instrukcjami w tej sekcji dotyczącymi integracji IDE lub zadań Gradle.

W IDE

Kliknij ikonę rynny obok funkcji @PreviewTest i wybierz Uruchom „ScreenshotTests”.

Jeśli test się nie powiedzie, w panelu Uruchom kliknij nazwę testu. Aby sprawdzić różnice w obrazie, wybierz kartę Zrzut ekranu i użyj zintegrowanych elementów sterujących powiększaniem i przesuwaniem.

Za pomocą zadań w Gradle

Uruchom zadanie weryfikacji, aby zrobić nowy zrzut ekranu i porównać go z obrazem referencyjnym:

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

Zadanie związane z weryfikacją tworzy raport HTML w lokalizacji {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Znane problemy

• Kotlin Multiplatform (KMP): zarówno IDE, jak i wtyczka bazowa są przeznaczone wyłącznie do projektów na Androida. Nie obsługują one w projektach KMP platform innych niż Android.

Pełną listę aktualnych znanych problemów znajdziesz w komponencie narzędzia do śledzenia problemów. Inne opinie i problemy zgłaszaj za pomocą narzędzia do śledzenia problemów.

Aktualizacje wersji

Pełną listę zmian znajdziesz w informacjach o wersji.