Pengujian Screenshot Pratinjau Compose

Pengujian screenshot adalah cara efektif untuk memverifikasi tampilan UI Anda kepada pengguna. Alat Pengujian Screenshot Pratinjau Compose menggabungkan kesederhanaan dan fitur pratinjau composable dengan peningkatan produktivitas dari menjalankan pengujian screenshot sisi host. Pengujian Screenshot Pratinjau Compose dirancang agar mudah digunakan seperti pratinjau composable.

Pengujian screenshot adalah pengujian otomatis yang mengambil screenshot bagian UI, lalu membandingkannya dengan gambar referensi yang sebelumnya disetujui. Jika gambar tidak cocok, pengujian akan gagal dan menghasilkan laporan HTML untuk membantu Anda membandingkan dan menemukan perbedaannya.

Dengan alat Pengujian Screenshot Pratinjau Compose, Anda dapat:

• Menggunakan @PreviewTest untuk membuat pengujian screenshot untuk pratinjau composable yang ada atau baru.
• Membuat gambar referensi dari pratinjau composable tersebut.
• Membuat laporan HTML yang mengidentifikasi perubahan pada pratinjau tersebut setelah Anda melakukan perubahan kode.
• Menggunakan parameter @Preview, seperti uiMode atau fontScale, dan multi-pratinjau untuk membantu Anda menskalakan pengujian.
• Membuat pengujian Anda menjadi modular dengan kumpulan sumber screenshotTest baru.

Integrasi IDE

Meskipun Anda dapat menggunakan alat Pengujian Screenshot Pratinjau Compose dengan menjalankan tugas Gradle yang mendasarinya (updateScreenshotTest dan validateScreenshotTest) secara manual, Android Studio Otter 3 Feature Drop Canary 4 memperkenalkan integrasi IDE penuh. Hal ini memungkinkan Anda membuat gambar referensi, menjalankan pengujian, dan menganalisis kegagalan validasi sepenuhnya dalam IDE. Berikut beberapa fitur utamanya:

• Ikon gutter dalam editor. Sekarang Anda dapat menjalankan pengujian atau memperbarui gambar referensi langsung dari kode sumber. Ikon jalankan berwarna hijau muncul di gutter di samping composable dan class yang diberi anotasi dengan @PreviewTest.
  • Menjalankan pengujian screenshot. Menjalankan pengujian khusus untuk satu fungsi atau untuk seluruh class.
  • Menambahkan atau memperbarui gambar referensi. Memicu alur pembaruan khusus untuk cakupan yang dipilih.

• Pengelolaan referensi interaktif. Memperbarui gambar referensi kini lebih aman dan lebih terperinci.
  • Dialog pembuatan gambar referensi baru. Daripada menjalankan tugas Gradle massal, dialog baru memungkinkan Anda memvisualisasikan dan memilih pratinjau mana yang akan dibuat atau diperbarui.
  • Variasi pratinjau. Dialog ini mencantumkan semua variasi pratinjau (seperti tema terang atau tema gelap, atau perangkat yang berbeda) satu per satu, sehingga Anda dapat memilih atau menghapus item tertentu sebelum membuat gambar.

• Hasil pengujian terintegrasi dan penampil perbedaan. Lihat hasil tanpa keluar dari IDE.
  • Panel jalankan terpadu. Hasil pengujian screenshot muncul di jendela alat Run standar. Pengujian dikelompokkan berdasarkan class dan fungsi, dengan status lulus atau gagal yang ditandai dengan jelas.
  • Alat perbedaan visual. Jika pengujian gagal, tab Screenshot memungkinkan Anda membandingkan gambar Reference, Actual, dan Diff secara berdampingan.
  • Atribut mendetail. Tab Attributes menyediakan metadata tentang pengujian yang gagal, termasuk persentase kecocokan, dimensi gambar, dan konfigurasi pratinjau tertentu yang digunakan (misalnya, uiMode atau fontScale).

• Cakupan pengujian yang fleksibel. Sekarang Anda dapat menjalankan pengujian screenshot dengan berbagai cakupan langsung dari Tampilan Project. Klik kanan modul, direktori, file, atau class untuk menjalankan pengujian screenshot khusus untuk pilihan tersebut.

Persyaratan

Untuk menggunakan Pengujian Screenshot Pratinjau Compose melalui integrasi IDE penuh, project Anda harus memenuhi persyaratan berikut:

• Android Studio Panda 1 Canary 4 atau yang lebih tinggi.
• Plugin Android Gradle (AGP) versi 9.0 atau yang lebih tinggi.
• Plugin Pengujian Screenshot Pratinjau Compose versi 0.0.1-alpha14 atau yang lebih tinggi.
• Kotlin versi 2.2.10 atau yang lebih tinggi.
• JDK versi 17 atau yang lebih tinggi.
• Compose diaktifkan untuk project Anda. Sebaiknya aktifkan Compose menggunakan plugin Gradle Compose Compiler.

Jika Anda hanya ingin menggunakan tugas Gradle yang mendasarinya tanpa integrasi IDE, persyaratannya adalah sebagai berikut:

• Plugin Android Gradle (AGP) versi 8.5.0 atau yang lebih tinggi.
• Plugin Pengujian Screenshot Pratinjau Compose versi 0.0.1-alpha14 atau yang lebih tinggi.
• Kotlin versi 1.9.20 atau yang lebih tinggi. Sebaiknya gunakan Kotlin 2.0 atau yang lebih tinggi agar Anda dapat menggunakan plugin Gradle Compose Compiler.
• JDK versi 17 atau yang lebih tinggi.
• Compose diaktifkan untuk project Anda. Sebaiknya aktifkan Compose menggunakan plugin Gradle Compose Compiler.

Penyiapan

Alat terintegrasi dan tugas Gradle yang mendasarinya mengandalkan plugin Pengujian Screenshot Pratinjau Compose. Untuk menyiapkan plugin, ikuti langkah-langkah berikut:

1. Aktifkan properti eksperimental di file gradle.properties project Anda.

   android.experimental.enableScreenshotTest=true
   

2. Di blok android {} file build.gradle.kts tingkat modul, aktifkan flag eksperimental untuk menggunakan kumpulan sumber screenshotTest.

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

3. Tambahkan plugin com.android.compose.screenshot, versi 0.0.1-alpha14 ke project Anda.

   1. Tambahkan plugin ke file katalog versi Anda:

      [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. Di file build.gradle.kts tingkat modul, tambahkan plugin di blok plugins {}:

      plugins {
          alias(libs.plugins.screenshot)
      }
      

4. Tambahkan dependensi screenshot-validation-api dan ui-tooling.

   1. Tambahkan ke katalog versi Anda:

      [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. Tambahkan ke file build.gradle.kts tingkat modul Anda:

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

Menetapkan pratinjau composable yang akan digunakan untuk pengujian screenshot

Untuk menetapkan pratinjau composable yang ingin Anda gunakan untuk pengujian screenshot, tandai pratinjau dengan anotasi @PreviewTest. Pratinjau harus berada di kumpulan sumber screenshotTest baru, misalnya:

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

Anda dapat menambahkan lebih banyak composable atau pratinjau, termasuk multi-pratinjau, dalam file ini atau file lain yang dibuat dalam kumpulan sumber yang sama.

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

Membuat gambar referensi

Setelah menyiapkan class pengujian, Anda harus membuat gambar referensi untuk setiap pratinjau. Gambar referensi ini digunakan untuk mengidentifikasi perubahan nanti, setelah Anda melakukan perubahan kode. Untuk membuat gambar referensi untuk pengujian screenshot pratinjau composable, ikuti petunjuk di bagian ini untuk integrasi IDE atau untuk tugas Gradle.

Di IDE

Klik ikon gutter di samping fungsi @PreviewTest, lalu pilih Add/Update Reference Images. Pilih pratinjau dalam dialog, lalu klik Add.

Dengan tugas Gradle

Jalankan tugas Gradle berikut:

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

Setelah tugas selesai, temukan gambar referensi di app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference).

Membuat laporan pengujian

Setelah gambar referensi ada, buat laporan pengujian dengan mengikuti petunjuk di bagian ini untuk integrasi IDE atau untuk tugas Gradle.

Di IDE

Klik ikon gutter di samping fungsi @PreviewTest, lalu pilih Run 'ScreenshotTests'.

Jika pengujian gagal, klik nama pengujian di panel Run. Pilih tab Screenshot untuk memeriksa perbedaan gambar menggunakan kontrol zoom dan geser terintegrasi.

Dengan tugas Gradle

Jalankan tugas validasi untuk mengambil screenshot baru dan membandingkannya dengan gambar referensi:

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

Tugas verifikasi membuat laporan HTML di {module}/build/reports/screenshotTest/preview/{variant}/index.html.

Pemecahan masalah

Pengujian Screenshot Pratinjau Compose menjalankan pengujian sisi host, yang dapat menggunakan banyak memori. Anda dapat meningkatkan ukuran heap maksimum untuk JVM pengujian dengan menambahkan properti berikut ke file gradle.properties:

android.compose.screenshot.maxHeapSize=4g

Masalah umum

• Multiplatform Kotlin (KMP): IDE dan plugin yang mendasarinya direkayasa secara eksklusif untuk project Android. IDE dan plugin tersebut tidak mendukung target non-Android dalam project KMP.

Anda dapat menemukan daftar lengkap masalah umum saat ini di komponen pelacak masalah alat . Laporkan masukan dan masalah lainnya melalui pelacak masalah.

Update rilis

Untuk daftar lengkap update rilis, lihat catatan rilis.