Pengujian screenshot dengan rangkaian pengujian

Mulai dari Plugin Android Gradle (AGP) 9.5.0-alpha03 dan mesin Pengujian Screenshot Pratinjau Compose 0.0.1-alpha16, pengujian screenshot terintegrasi dengan framework suite pengujian native AGP.

Pendekatan ini menggantikan plugin screenshot mandiri (com.android.compose.screenshot). Sebaiknya gunakan rangkaian pengujian AGP karena alasan berikut:

• Siklus proses tugas Gradle native: Pengujian screenshot terintegrasi langsung ke dalam siklus proses pengujian Gradle dan AGP standar, sehingga meningkatkan isolasi tugas dan keandalan eksekusi uji.
• Dukungan rangkaian pengujian multi-varian dan kustom: Anda dapat membuat beberapa rangkaian pengujian screenshot yang berbeda (seperti screenshotTest, uiTests, atau smokeTests) dalam satu modul dan menargetkan varian build tertentu (seperti demoDebug atau release), bukan hanya terbatas pada satu set sumber yang telah dikonfigurasi sebelumnya.
• Peningkatan performa dan isolasi build: Suite pengujian AGP menggunakan transformasi artefak bawaan (seperti ekstraksi runtime Layoutlib) dan pemuatan class terisolasi, dengan dukungan penuh untuk Gradle Configuration Caching dan Project Isolation.

Persyaratan

Untuk menggunakan Pengujian Screenshot Compose dengan rangkaian pengujian, pastikan lingkungan Anda memenuhi persyaratan berikut:

• Android Studio Rabbit 1 Canary 4 atau yang lebih baru.
• Plugin Android Gradle (AGP) versi 9.5.0-alpha03 atau yang lebih tinggi.
• Compose Screenshot Engine versi 0.0.1-alpha16 atau yang lebih tinggi.
• JDK versi 17 atau yang lebih baru.
• Compose diaktifkan untuk project Anda. Sebaiknya aktifkan Compose menggunakan plugin Gradle Compose Compiler.

Penyiapan dan konfigurasi

Untuk mengonfigurasi pengujian screenshot Compose dengan rangkaian pengujian, selesaikan langkah-langkah berikut:

1. Mengaktifkan tanda eksperimental

Di file gradle.properties root project Anda, aktifkan pengujian screenshot dan dukungan suite pengujian:

android.experimental.enableScreenshotTest=true
android.experimental.testSuiteSupport=true

2. Mengonfigurasi suite pengujian dalam file build.gradle.kts

Dalam file build.gradle.kts modul Anda, tentukan suite pengujian screenshot dalam blok testOptions:

android {
    testOptions {
        screenshotTests.create("screenshotTest") { // suiteName can be customized (for example, "uiTests")
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug") // Add specific variants to test

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

3. Membuat set sumber pengujian

Buat direktori set sumber khusus yang cocok dengan nama rangkaian pengujian Anda:

{module}/src/{suiteName}/kotlin/

Misalnya, untuk rangkaian bernama screenshotTest:

feature/foryou/impl/src/screenshotTest/kotlin/com/example/app/ForYouScreenTest.kt

4. Menentukan pengujian pratinjau composable

Anotasikan composable dengan @PreviewTest dan anotasi multi-pratinjau atau @Preview standar:

package com.example.app

import androidx.compose.runtime.Composable
import androidx.compose.ui.tooling.preview.Preview
import com.android.tools.screenshot.PreviewTest
import com.example.app.ui.theme.AppTheme

@PreviewTest
@Preview(showBackground = true)
@Composable
fun ForYouScreenPreview() {
    AppTheme {
        ForYouScreen(isSyncing = false)
    }
}

Menjalankan pengujian screenshot

Kumpulan pengujian AGP menghasilkan tugas Gradle khusus berdasarkan nama, target, dan varian rangkaian pengujian Anda.

1. Membuat atau memperbarui gambar referensi

Render pratinjau composable dan simpan gambar referensi dasar pengukuran yang benar:

• Linux dan macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (misalnya, ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Gambar referensi dibuat dan disimpan di:

{module}/src/{suiteName}{Target}{Variant}/reference/

2. Memverifikasi dan menjalankan pengujian

Merender screenshot baru dan membandingkannya dengan gambar referensi:

• Linux dan macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (misalnya, ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Memeriksa laporan pengujian

Jika perbedaan terdeteksi atau pengujian gagal, AGP akan membuat laporan pengujian HTML.

• Lokasi laporan: {module}/build/reports/tests/{taskName}/index.html (misalnya, app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

Laporan yang diperbarui mencakup:

• Kartu metadata header: Menampilkan nama pengujian, metode pratinjau, varian, rangkaian pengujian, dan badge status.
• Pengategorian error: Menandai Reference Image Missing, Image Size Mismatch, atau Pixel Mismatch dengan jelas menggunakan rekaman aktivitas stack yang dapat disalin.
• Perbedaan visual dinamis: Menyoroti modifikasi halus dengan intensitas yang lebih rendah dan perubahan besar dengan penekanan kontras tinggi untuk mencegah elemen bertingkat tertelan.

Bermigrasi dari plugin mandiri lama

Untuk bermigrasi dari plugin screenshot mandiri lama ke rangkaian pengujian AGP, perbarui konfigurasi Gradle dan perintah tugas Anda.

Perbandingan DSL konfigurasi build

Plugin mandiri lama (tidak digunakan lagi)

// In build.gradle.kts
plugins {
    alias(libs.plugins.screenshot)
}

dependencies {
    screenshotTestImplementation(libs.androidx.compose.ui.tooling)
    screenshotTestImplementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
}

Rangkaian pengujian AGP (direkomendasikan)

// In build.gradle.kts
android {
    testOptions {
        screenshotTests.create("screenshotTest") {
            engineVersion = "0.0.1-alpha16"
            targetVariants.add("demoDebug")

            dependencies {
                implementation(libs.androidx.compose.ui.tooling)
                implementation("com.android.tools.screenshot:screenshot-validation-api:0.0.1-alpha16")
            }
        }
    }
}

Pemetaan tugas dan jalur