Testowanie zrzutu ekranu w podglądzie tworzenia

Testowanie zrzutów ekranu to skuteczny sposób na sprawdzenie, jak interfejs wygląda dla użytkowników. Narzędzie do testowania zrzutów ekranu w podglądzie widoku tworzenia łączy prostotę i funkcje podglądów funkcji kompozycyjnych ze wzrostem produktywności dzięki przeprowadzaniu testów zrzutów ekranu po stronie hosta. Testowanie zrzutów ekranu w widoku tworzenia podglądu zostało zaprojektowane tak, aby było równie proste w użyciu jak podglądy funkcji kompozycyjnych.

Test zrzutu ekranu to automatyczny test, który polega na zrobieniu zrzutu ekranu fragmentu interfejsu, a następnie porównaniu go z zatwierdzonym wcześniej obrazem referencyjnym. Jeśli obrazy nie są zgodne, test kończy się niepowodzeniem i generuje raport HTML, który pomaga porównać obrazy i znaleźć różnice.

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

  • Użyj @PreviewTest, aby utworzyć testy zrzutów ekranu dla istniejących lub nowych podglądów funkcji kompozycyjnych.
  • wygenerować obrazy referencyjne z tych podglądów funkcji kompozycyjnych.
  • Wygeneruj raport HTML, który po wprowadzeniu zmian w kodzie identyfikuje zmiany w tych podglądach.
  • Używaj parametrów @Preview, takich jak uiMode lub fontScale, oraz funkcji Multi Preview, aby skalować testy.
  • Zmodularyzuj testy za pomocą nowego zbioru źródeł screenshotTest.
Rysunek 1. Przykładowy raport HTML.

Integracja z IDE

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

  • Ikony w kolumnie edytora. Możesz teraz przeprowadzać testy lub aktualizować obrazy referencyjne bezpośrednio z kodu źródłowego. W rynnie obok funkcji kompozycyjnych i klas oznaczonych adnotacją @PreviewTest pojawiają się zielone ikony uruchamiania.
    • Przeprowadź testy zrzutów ekranu. wykonywać testy dla pojedynczej funkcji lub całej klasy;
    • Dodaj lub zaktualizuj obrazy referencyjne. Uruchom proces aktualizacji dla wybranego zakresu.

  • Interaktywne zarządzanie plikami referencyjnymi. Aktualizowanie obrazów referencyjnych jest teraz bezpieczniejsze i bardziej szczegółowe.
    • Nowe okno generowania obrazu referencyjnego. Zamiast uruchamiać zbiorcze zadanie Gradle, możesz teraz skorzystać z nowego okna, które pozwala wyświetlić i wybrać dokładnie te podglądy, które chcesz wygenerować lub zaktualizować.
    • Wyświetl podgląd odmian. W oknie dialogowym wyświetlane są wszystkie wersje podglądu (np. jasny lub ciemny motyw albo różne urządzenia), co pozwala wybrać lub odznaczyć konkretne elementy przed wygenerowaniem obrazów generatywnych.

  • Zintegrowane wyniki testów i przeglądarka różnic. Wyświetlaj wyniki bez opuszczania IDE.
    • Ujednolicony panel uruchamiania. Wyniki testu zrzutu ekranu pojawiają się w standardowym oknie narzędzia Uruchom. Testy są pogrupowane według klasy i funkcji, a ich stan (powodzenie lub niepowodzenie) jest wyraźnie oznaczony.
    • Narzędzie do wizualnego porównywania zmian. Jeśli test się nie powiedzie, na karcie Zrzut ekranu możesz porównać 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 konkretną konfigurację Preview (np. uiMode lub fontScale).

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

Wymagania

Aby korzystać z testowania zrzutów ekranu w podglądzie Compose w ramach pełnej integracji ze środowiskiem IDE, Twój projekt musi spełniać te wymagania:

  • Android Studio Panda 1 Canary 4 lub nowsza wersja.
  • Wtyczka Androida do obsługi Gradle (AGP) w wersji 9.0 lub nowszej.
  • Wtyczka Compose Preview Screenshot Testing w wersji 0.0.1-alpha16 lub nowszej.
  • Kotlin w wersji 2.2.10 lub nowszej.
  • JDK w wersji 17 lub nowszej.
  • Funkcja Compose została włączona 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, wymagania są następujące:

  • Wtyczka Androida do obsługi Gradle (AGP) w wersji 8.5.0 lub nowszej.
  • Wtyczka Compose Preview Screenshot Testing w wersji 0.0.1-alpha16 lub nowszej.
  • Kotlin w wersji 1.9.20 lub nowszej. Zalecamy używanie Kotlina w wersji 2.0 lub nowszej, aby móc korzystać z wtyczki Gradle kompilatora Compose.
  • JDK w wersji 17 lub nowszej.
  • Funkcja Compose została włączona w Twoim projekcie. Zalecamy włączenie Compose za pomocą wtyczki Gradle kompilatora Compose.

Konfiguracja

Zarówno zintegrowane narzędzie, jak i podstawowe zadania Gradle korzystają z wtyczki Compose Preview Screenshot Testing. Aby to zrobić, wykonaj poniższe 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 do projektu wtyczkę com.android.compose.screenshot w wersji 0.0.1-alpha16.

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

      [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. 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 funkcji kompozycyjnych do użycia w testach zrzutów ekranu

Aby wskazać podglądy funkcji kompozycyjnych, których chcesz używać do testów zrzutów ekranu, oznacz je adnotacją @PreviewTest. Podglądy muszą znajdować się w nowym zbiorze źródeł screenshotTest, na przykład:

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

W tym pliku lub w innych plikach utworzonych w tym samym zbiorze ź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. Te obrazy referencyjne są używane do identyfikowania zmian po wprowadzeniu zmian w kodzie. Aby wygenerować obrazy referencyjne do testów zrzutów ekranu w podglądzie funkcji kompozycyjnej, postępuj zgodnie z instrukcjami w tej sekcji dotyczącymi integracji IDE lub zadań Gradle.

W środowisku 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 app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Generowanie raportu z testu

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

W środowisku IDE

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

Jeśli test się nie powiedzie, kliknij jego nazwę w panelu Uruchom. Kliknij kartę Zrzut ekranu, aby sprawdzić różnice między obrazami za pomocą zintegrowanych elementów sterujących powiększaniem i przesuwaniem.

Za pomocą zadań w Gradle

Uruchom zadanie sprawdzania, 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 {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Rozwiązywanie problemów

Testowanie zrzutów ekranu w podglądzie tworzenia wiadomości przeprowadza testy po stronie hosta, które mogą wymagać dużej ilości pamięci. Możesz zwiększyć maksymalny rozmiar sterty dla testowej maszyny JVM, dodając do pliku gradle.properties tę właściwość:

android.compose.screenshot.maxHeapSize=4g

Znane problemy

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

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

Aktualizacje wersji

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