Test paketleriyle ekran görüntüsü testi

Android Gradle Eklentisi (AGP) 9.5.0-alpha03 ve Compose Preview Screenshot Testing motorundan 0.0.1-alpha16 itibaren ekran görüntüsü testi, AGP'nin yerel test paketleri çerçevesine entegre edilmiştir.

Bu yaklaşım, bağımsız ekran görüntüsü eklentisinin (com.android.compose.screenshot) yerini alır. Aşağıdaki nedenlerden dolayı AGP test paketlerini kullanmanızı öneririz:

• Doğal Gradle görevi yaşam döngüsü: Ekran görüntüsü testleri, doğrudan standart Gradle ve AGP test yaşam döngülerine entegre edilerek görev izolasyonunu ve test yürütme güvenilirliğini artırır.
• Çok varyantlı ve özel paket desteği: Tek bir modülde birden fazla farklı ekran görüntüsü test paketi (ör. screenshotTest, uiTests veya smokeTests) oluşturabilir ve tek bir önceden yapılandırılmış kaynak grubuyla sınırlı kalmak yerine belirli derleme varyantlarını (ör. demoDebug veya release) hedefleyebilirsiniz.
• Gelişmiş derleme performansı ve izolasyon: AGP test paketleri, Gradle yapılandırma önbelleğe alma ve proje izolasyonu için tam destekle birlikte yerleşik yapay nesne dönüşümleri (ör. Layoutlib çalışma zamanı ayıklama) ve izole edilmiş sınıf yükleme kullanır.

Şartlar

Test paketleriyle Compose ekran görüntüsü testini kullanmak için ortamınızın aşağıdaki koşulları karşıladığından emin olun:

• Android Studio Rabbit 1 Canary 4 veya sonraki sürümler.
• Android Gradle eklentisinin (AGP) 9.5.0-alpha03 veya sonraki bir sürümü.
• Compose Screenshot Engine 0.0.1-alpha16 veya sonraki bir sürüm.
• JDK 17 veya sonraki sürümler.
• Projeniz için Compose'un etkinleştirilmesi gerekir. Compose Compiler Gradle eklentisini kullanarak Compose'u etkinleştirmenizi öneririz.

Kurulum ve yapılandırma

Test paketleriyle Compose ekran görüntüsü testini yapılandırmak için aşağıdaki adımları tamamlayın:

1. Deneysel bayrakları etkinleştirme

Projenizin kök gradle.properties dosyasında ekran görüntüsü testini ve test paketi desteğini etkinleştirin:

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

2. Test paketini build.gradle.kts dosyasında yapılandırma

Modülünüzün build.gradle.kts dosyasında, testOptions bloğunda bir ekran görüntüsü testi paketi tanımlayın:

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. Test kaynak grubunu oluşturma

Paket adınızla eşleşen özel bir kaynak grubu dizini oluşturun:

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

Örneğin, screenshotTest adlı bir paket için:

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

4. Oluşturulabilir önizleme testlerini tanımlama

Birleştirilebilir işlevlere @PreviewTest ve standart @Preview ya da çoklu önizleme ek açıklamaları ekleyin:

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

Ekran görüntüsü testleri çalıştırma

AGP test paketleri, paket adınıza, hedefinize ve varyantlarınıza göre özel Gradle görevleri oluşturur.

1. Referans resim oluşturma veya güncelleme

Birleştirilebilir önizlemeler oluşturun ve altın başlangıç çizgisi referans resimlerini saklayın:

• Linux ve macOS: ./gradlew update{SuiteName}{Target}{Variant}TestSuite (örneğin, ./gradlew updateScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew updateScreenshotTestDefaultDemoDebugTestSuite

Referans resimler oluşturulup şu konuma kaydedilir:

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

2. Doğrulama ve test çalıştırma

Yeni ekran görüntüleri oluşturun ve bunları referans resimlerle karşılaştırın:

• Linux ve macOS: ./gradlew test{SuiteName}{Target}{Variant}TestSuite (örneğin, ./gradlew testScreenshotTestDefaultDemoDebugTestSuite)
• Windows: gradlew testScreenshotTestDefaultDemoDebugTestSuite

Test raporlarını inceleme

Farklılıklar algılanırsa veya testler başarısız olursa AGP bir HTML test raporu oluşturur.

• Raporun konumu: {module}/build/reports/tests/{taskName}/index.html (örneğin, app/build/reports/tests/testScreenshotTestDefaultDemoDebugTestSuite/index.html)

Güncellenen rapor şunları içerir:

• Başlık meta verileri kartı: Test adı, önizleme yöntemi, varyant, paket ve durum rozetini gösterir.
• Hata sınıflandırması: Reference Image Missing, Image Size Mismatch veya Pixel Mismatch, kopyalanabilir yığın izleriyle net bir şekilde işaretlenir.
• Dinamik görsel karşılaştırma: İç içe yerleştirilmiş öğelerin yutulmasını önlemek için küçük değişiklikleri daha düşük yoğunlukta, büyük değişiklikleri ise yüksek kontrastlı vurgularla öne çıkarır.

Eski bağımsız eklentiden taşıma

Eski bağımsız ekran görüntüsü eklentisinden AGP test paketlerine geçmek için Gradle yapılandırmanızı ve görev komutlarınızı güncelleyin.

Derleme yapılandırması DSL karşılaştırması

Eski bağımsız eklenti (kullanımdan kaldırıldı)

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

AGP test paketleri (önerilen)

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

Görev ve yol eşleme