Önizleme Ekran Görüntüsü Testi Oluşturma

Ekran görüntüsü testi, kullanıcı arayüzünüzün kullanıcılara nasıl göründüğünü doğrulamanın etkili bir yoludur. Compose Önizleme Ekran Görüntüsü Testi aracı, composable önizlemelerin basitliğini ve özelliklerini, ana makine tarafında ekran görüntüsü testleri çalıştırmanın verimlilik avantajlarıyla birleştirir. Oluşturma Önizlemesi Ekran görüntüsü testi, oluşturulabilir önizlemeler kadar kolay kullanılacak şekilde tasarlanmıştır.

Ekran görüntüsü testi, bir kullanıcı arayüzü parçasının ekran görüntüsünü alan ve ardından bunu daha önce onaylanmış bir referans resimle karşılaştıran otomatik bir testtir. Resimler eşleşmezse test başarısız olur ve farklılıkları karşılaştırıp bulmanıza yardımcı olacak bir HTML raporu oluşturulur.

E-posta Oluşturma Önizlemesi Ekran Görüntüsü Testi aracıyla şunları yapabilirsiniz:

  • Mevcut veya yeni composable önizlemeler için ekran görüntüsü testleri oluşturmak üzere @PreviewTest simgesini kullanın.
  • Oluşturulabilir önizlemelerden referans görüntüler oluşturun.
  • Kod değişiklikleri yaptıktan sonra bu önizlemelerde yapılan değişiklikleri belirleyen bir HTML raporu oluşturun.
  • Testlerinizi ölçeklendirmenize yardımcı olmak için uiMode veya fontScale gibi @Preview parametrelerini ve çoklu önizlemeleri kullanın.
  • Yeni screenshotTest kaynak grubuyla testlerinizi modüler hale getirin.
Şekil 1. Örnek HTML raporu.

IDE entegrasyonu

Temel Gradle görevlerini (updateScreenshotTest ve validateScreenshotTest) manuel olarak çalıştırarak Compose Preview Screenshot Testing aracını kullanabilirsiniz ancak Android Studio Otter 3 Feature Drop Canary 4, tam IDE entegrasyonu sunar. Bu sayede, referans resimler oluşturabilir, testler çalıştırabilir ve doğrulama hatalarını tamamen IDE içinde analiz edebilirsiniz. Temel özelliklerden bazıları şunlardır:

  • Düzenleyicideki oluk simgeleri. Artık doğrudan kaynak kodundan test çalıştırabilir veya referans resimleri güncelleyebilirsiniz. @PreviewTest ile açıklama eklenmiş composable'ların ve sınıfların yanındaki olukta yeşil çalıştırma simgeleri görünür.
    • Ekran görüntüsü testleri yapın. Testleri özellikle tek bir işlev veya tüm sınıf için yürütün.
    • Referans resim ekleyin veya güncelleyin. Güncelleme akışını özellikle seçili kapsam için tetikleyin.

  • Etkileşimli referans yönetimi Referans görselleri güncellemek artık daha güvenli ve daha ayrıntılı.
    • Yeni referans görsel oluşturma iletişim kutusu. Toplu Gradle görevi çalıştırmak yerine, yeni bir iletişim kutusu sayesinde hangi önizlemelerin oluşturulacağını veya güncelleneceğini tam olarak görselleştirip seçebilirsiniz.
    • Varyasyonları önizleyin. İletişim kutusunda tüm önizleme varyasyonları (ör. açık veya koyu mod ya da farklı cihazlar) ayrı ayrı listelenir. Böylece, resim oluşturmadan önce belirli öğeleri işaretleyebilir veya işaretini kaldırabilirsiniz.

  • Entegre test sonuçları ve fark görüntüleyici. IDE'den ayrılmadan sonuçları görüntüleyin.
    • Birleştirilmiş çalıştırma paneli. Ekran görüntüsü testi sonuçları standart Çalıştır araç penceresinde görünür. Testler, sınıf ve işlevlere göre gruplandırılır. Geçti veya kaldı durumu açıkça belirtilir.
    • Görsel fark aracı. Bir test başarısız olduğunda Ekran görüntüsü sekmesinde Referans, Gerçek ve Fark resimlerini yan yana karşılaştırabilirsiniz.
    • Ayrıntılı özellikler. Özellikler sekmesinde, eşleşme yüzdesi, resim boyutları ve kullanılan belirli önizleme yapılandırması (örneğin, uiMode veya fontScale) dahil olmak üzere başarısız testlerle ilgili meta veriler yer alır.

  • Esnek test kapsamı. Artık doğrudan Proje Görünümü'nden çeşitli kapsamlarla ekran görüntüsü testleri yürütebilirsiniz. Ekran görüntüsü testlerini yalnızca bu seçim için çalıştırmak üzere bir modülü, dizini, dosyayı veya sınıfı sağ tıklayın.

Şartlar

Tam IDE entegrasyonu aracılığıyla Compose Preview'da ekran görüntüsü testini kullanmak için projenizin aşağıdaki koşulları karşılaması gerekir:

  • Android Studio Panda 1 Canary 4 veya sonraki sürümler.
  • Android Gradle eklentisi (AGP) 9.0 veya sonraki sürümler.
  • Compose Preview Screenshot Testing eklentisinin 0.0.1-alpha13 veya sonraki bir sürümü.
  • Kotlin 2.2.10 veya sonraki sürümler.
  • JDK 17 veya sonraki sürümler.
  • Projeniz için Compose'u etkinleştirin. Compose Compiler Gradle eklentisini kullanarak Compose'u etkinleştirmenizi öneririz.

Yalnızca IDE entegrasyonu olmadan temel Gradle görevlerini kullanmak istiyorsanız:

  • Android Gradle eklentisi (AGP) 8.5.0 veya sonraki sürümler.
  • Compose Preview Screenshot Testing eklentisinin 0.0.1-alpha13 veya sonraki bir sürümü.
  • Kotlin 1.9.20 veya sonraki bir sürüm. Compose Compiler Gradle eklentisini kullanabilmek için Kotlin 2.0 veya sonraki bir sürümü kullanmanızı öneririz.
  • JDK 17 veya sonraki sürümler.
  • Projeniz için Compose'u etkinleştirin. Compose Compiler Gradle eklentisini kullanarak Compose'u etkinleştirmenizi öneririz.

Kurulum

Hem entegre araç hem de temel Gradle görevleri, Compose Preview Screenshot Testing eklentisini kullanır. Eklentiyi ayarlamak için aşağıdaki adımları uygulayın:

  1. Projenizin gradle.properties dosyasında deneysel özelliği etkinleştirin. 
          android.experimental.enableScreenshotTest=true
  2. Modül düzeyindeki build.gradle.kts dosyanızın android {} bloğunda, screenshotTest kaynak kümesini kullanmak için deneysel işareti etkinleştirin. 
          android {
          experimentalProperties["android.experimental.enableScreenshotTest"] = true
      }
  3. Projenize com.android.compose.screenshot eklentisini (sürüm 0.0.1-alpha13) ekleyin.
    1. Eklentiyi sürüm katalogları dosyanıza ekleyin: 
                [versions]
          agp = "9.0.0-rc03"
          kotlin = "2.1.20"
          screenshot = "0.0.1-alpha13"

          [plugins]
          screenshot = { id = "com.android.compose.screenshot", version.ref = "screenshot"}
    2. Modül düzeyindeki build.gradle.kts dosyanızda, plugins {} bloğuna eklentiyi ekleyin: 
                plugins {
              alias(libs.plugins.screenshot)
          }
  4. screenshot-validation-api ve ui-tooling bağımlılıklarını ekleyin.
    1. Bunları sürüm kataloglarınıza ekleyin: 
                [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. Bunları modül düzeyindeki build.gradle.kts dosyanıza ekleyin: 
                dependencies {
            screenshotTestImplementation(libs.screenshot.validation.api)
            screenshotTestImplementation(libs.androidx.ui.tooling)
          }

Ekran görüntüsü testlerinde kullanılacak composable önizlemelerini belirleme

Ekran görüntüsü testlerinde kullanmak istediğiniz composable önizlemeleri belirtmek için önizlemeleri @PreviewTest ek açıklamasıyla işaretleyin. Önizlemeler, yeni screenshotTest kaynak grubunda bulunmalıdır. Örneğin:

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

Bu dosyaya veya aynı kaynak grubunda oluşturulan diğer dosyalara çoklu önizlemeler de dahil olmak üzere daha fazla composable ve/veya önizleme ekleyebilirsiniz.

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

Referans resimler oluşturma

Test sınıfı oluşturduktan sonra her önizleme için referans resimler oluşturmanız gerekir. Bu referans resimler, kod değişiklikleri yaptıktan sonra değişiklikleri belirlemek için kullanılır. Birleştirilebilir önizleme ekran görüntüsü testleriniz için referans resimler oluşturmak üzere IDE entegrasyonu veya Gradle görevleriyle ilgili aşağıdaki talimatları uygulayın.

IDE'de

Bir @PreviewTest işlevinin yanındaki oluk simgesini tıklayın ve Referans Resimleri Ekle/Güncelle'yi seçin. İletişim kutusunda istediğiniz önizlemeleri seçip Ekle'yi tıklayın.

Gradle görevleriyle

Aşağıdaki Gradle görevini çalıştırın:

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

Görev tamamlandıktan sonra referans resimleri app/src/screenshotTestDebug/reference({module}/src/screenshotTest{Variant}/reference) içinde bulabilirsiniz.

Test raporu oluşturma

Referans resimler oluşturulduktan sonra IDE entegrasyonu veya Gradle görevleriyle ilgili aşağıdaki talimatları uygulayarak bir test raporu oluşturun.

IDE'de

Bir @PreviewTest işlevinin yanındaki oluk simgesini tıklayın ve Run '...ScreenshotTests' seçeneğini belirleyin.

Bir test başarısız olursa Çalıştır panelinde test adını tıklayın. Entegre yakınlaştırma ve kaydırma kontrollerini kullanarak resim farklılığını incelemek için Ekran görüntüsü sekmesini seçin.

Gradle görevleriyle

Yeni bir ekran görüntüsü almak ve bunu referans resimle karşılaştırmak için doğrulama görevini çalıştırın:

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

Doğrulama görevi, {module}/build/reports/screenshotTest/preview/{variant}/index.html adresinde bir HTML raporu oluşturur.

Bilinen sorunlar

  • Kotlin Multiplatform (KMP): Hem IDE hem de temel eklenti yalnızca Android projeleri için tasarlanmıştır. KMP projelerinde Android dışı hedefler desteklenmez.

Aracın sorun izleme bileşeninde, bilinen sorunların güncel listesinin tamamını bulabilirsiniz. Diğer geri bildirimleri ve sorunları sorun izleyici üzerinden bildirin.

Yayın güncellemeleri

0.0.1-alpha13

Bu sürümde sunulanlar:

  • JDK 17 veya sonraki sürümlerle uyumluluk.
  • Hata düzeltmeleri ve Android Studio ile entegrasyonun iyileştirilmesi.

0.0.1-alpha12

Bu sürümde sunulanlar:

  • Android Gradle Eklentisi (AGP) 9.0 ile uyumluluk.
  • JDK 24 ve sonraki sürümlerde ekran görüntüsü testlerinin çalıştırılması desteklenir.
  • Maksimum yığın boyutunu yapılandırma desteği.
  • Oluşturma hataları düzeltildi ve test kararlılığı iyileştirildi.
  • Yeni ve referans resimlerle ilgili yüzde farkı ve diğer meta verileri içerecek şekilde raporlama geliştirildi.

0.0.1-alpha11

Bu sürümde sunulanlar:

  • Android Gradle eklentisi (AGP) 8.13 ile uyumluluk.
  • Ana makinenin yerel ayarından bağımsız olarak ondalık değerlere sahip XML çizilebilir öğelerinin ayrıştırılması için destek eklendi.
  • JDK 24 veya sonraki bir sürümü kullanan bir ana makine için, uyumlu bir JDK (11-23) yüklüyse bu JDK seçilir.

0.0.1-alpha10

Bu sürümde sunulanlar:

  • Bu sürümden itibaren tüm önizleme işlevlerinizi @PreviewTest ek açıklamasıyla işaretlemeniz gerekir. Açıklama içermeyen önizlemeler yürütülmez.

  • Referans resim dizini {module}/src/{variant}/screenshotTest/reference olarak değiştirildi.{module}/src/screenshotTest{Variant}/reference Bunun nedeni, oluşturulan referans resimlerin üretim kodunun bir parçası olmamasını sağlamak ve diğer test türlerinin dizin yapısıyla uyumlu olmaktır.

  • {variant}PreviewScreenshotRender görevi kaldırılır. Görüntü oluşturma işlemi JUnit Test Motoruna taşındı.

  • update{Variant}ScreenshotTest görevi, güncellemeden önce yeni oluşturulan görüntüleri referans görüntülerle karşılaştırır. Yalnızca belirtilen eşikten daha büyük farklılıklar içeren resimleri günceller. --updateFilter komut satırı işareti kaldırıldı.

0.0.1-alpha06

Bu sürümde sunulanlar:

Resim Farkı Eşiği: Bu yeni genel eşik ayarı, ekran görüntüsü karşılaştırmaları üzerinde daha hassas kontrol sahibi olmanızı sağlar. Yapılandırmak için modülünüzün build.gradle.kts dosyasını güncelleyin:

android {
    testOptions {
        screenshotTests {
            imageDifferenceThreshold = 0.0001f // 0.01%
        }
    }
}

Bu eşik, modülde tanımlanan tüm ekran görüntüsü testlerine uygulanır.

  • Hata Düzeltmeleri: Bazı Compose Renderer hataları giderildi ve boş compose desteği eklendi.
  • Performans iyileştirmeleri: Görüntü karşılaştırma algoritması daha hızlı olacak şekilde güncellendi.