Ö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 Önizlemesi Ekran Görüntüsü Test Aracı, composable önizlemelerin basitliğini ve özelliklerini, ana makine tarafındaki ekran görüntüsü testlerini çalıştırmanın üretkenlik avantajlarıyla birleştirir. Compose Preview Screenshot Testing, oluşturulabilir önizlemeler kadar kolay kullanılacak şekilde tasarlanmıştır.

android skills add testing-setup

Ekran görüntüsü testi, kullanıcı arayüzünün bir bölümünün ekran görüntüsünü alan ve ardından bunu daha önce onaylanmış bir referans görselle 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.

Compose Önizleme Ekran Görüntüsü Test Aracı ile şunları yapabilirsiniz:

• Mevcut veya yeni composable önizlemeler için ekran görüntüsü testleri oluşturmak üzere @PreviewTest kullanın.
• Bu birleştirilebilir önizlemelerden referans görseller oluşturun.
• Kod değişiklikleri yaptıktan sonra bu önizlemelerdeki değişiklikleri tanımlayan bir HTML raporu oluşturun.
• Testlerinizi ölçeklendirmek için uiMode veya fontScale gibi @Preview parametrelerini ve çoklu önizlemeleri kullanın.
• Yeni screenshotTest kaynak grubuyla testlerinizi modüler hale getirin.

IDE entegrasyonu

Compose Preview Ekran Görüntüsü Testi aracını, temel Gradle görevlerini (updateScreenshotTest ve validateScreenshotTest) manuel olarak çalıştırarak kullanabilirsiniz. Android Studio Otter 3 Feature Drop Canary 4 ise tam IDE entegrasyonu sunar. Bu sayede referans görseller oluşturabilir, testler çalıştırabilir ve doğrulama hatalarını tamamen IDE içinde analiz edebilirsiniz. Önemli özelliklerden bazıları şunlardır:

• Düzenleyici içi boşluk simgeleri. Artık testleri çalıştırabilir veya referans görselleri doğrudan kaynak kodundan güncelleyebilirsiniz. @PreviewTest ile ek açıklama eklenmiş composable'ların ve sınıfların yanındaki boşlukta yeşil çalıştırma simgeleri görünür.
  • Ekran görüntüsü testleri çalıştırma Testleri tek bir işlev veya tüm sınıf için çalıştırabilirsiniz.
  • Referans görseller ekleme veya güncelleme 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 ayrıntılı.
  • Yeni referans görsel oluşturma iletişim kutusu. Yeni bir iletişim kutusu, toplu bir Gradle görevi çalıştırmak yerine, tam olarak hangi önizlemelerin oluşturulacağını veya güncelleneceğini görselleştirmenize ve seçmenize olanak tanır.
  • Varyasyonları önizleme İletişim kutusunda tüm önizleme varyasyonları (ör. açık tema veya koyu tema ya da farklı cihazlar) ayrı ayrı listelenir. Böylece, yapay görüntü oluşturmadan önce belirli öğeleri seçebilir veya temizleyebilirsiniz.

• Entegre test sonuçları ve fark görüntüleyici. IDE'den ayrılmadan sonuçları görüntüleyebilirsiniz.
  • Birleştirilmiş çalıştırma paneli. Ekran görüntüsü test sonuçları, standart Çalıştır araç penceresinde görünür. Testler, sınıf ve işleve göre gruplandırılır. Başarılı veya başarısız olma durumu açıkça belirtilir.
  • Görsel fark aracı. Bir test başarısız olduğunda Ekran görüntüsü sekmesi, Referans, Gerçek ve Fark resimlerini yan yana karşılaştırmanıza olanak tanır.
  • Ayrıntılı özellikler. Özellikler sekmesi, başarısız testlerle ilgili meta veriler sağlar. Bu veriler arasında eşleşme yüzdesi, resim boyutları ve kullanılan belirli önizleme yapılandırması (ör. uiMode veya fontScale) yer alır.

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

Şartlar

Oluşturma Önizlemesi Ekran Görüntüsü Testi'ni tam IDE entegrasyonu aracılığıyla 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-alpha16 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 etkinleştirildi. Compose Derleyici Gradle eklentisini kullanarak Compose'u etkinleştirmenizi öneririz.

IDE entegrasyonu olmadan yalnızca temel Gradle görevlerini kullanmak istiyorsanız gereksinimler aşağıdaki gibidir:

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

Kurulum

Hem entegre araç hem de temel Gradle görevleri, Compose Önizleme Ekran Görüntüsü Testi eklentisini kullanır. Eklentiyi ayarlamak için aşağıdaki adımları izleyin:

1. Projenizin gradle.properties dosyasında deneysel özelliği etkinleştirin.

   android.experimental.enableScreenshotTest=true
   

2. screenshotTest kaynak grubunu kullanmak için modül düzeyindeki build.gradle.kts dosyanızın android {} bloğunda deneysel işareti etkinleştirin.

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

3. com.android.compose.screenshot eklentisinin 0.0.1-alpha16 sürümünü projenize ekleyin.

   1. Eklentiyi sürüm katalogları dosyanıza ekleyin:

      [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. Modül düzeyindeki build.gradle.kts dosyanızda, eklentiyi plugins {} bloğuna 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 önizlemeleri belirleme

Ekran görüntüsü testleri için kullanmak istediğiniz composable önizlemeleri belirlemek üzere ö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 daha fazla composable ya da önizleme (çoklu önizlemeler dahil) 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 görseller oluşturmanız gerekir. Bu referans görseller, kod değişiklikleri yaptıktan sonra değişiklikleri belirlemek için kullanılır. Oluşturulabilir önizleme ekran görüntüsü testleriniz için referans görseller oluşturmak istiyorsanız IDE entegrasyonu veya Gradle görevleri için bu bölümdeki talimatları uygulayın.

android studio render-compose-preview

IDE'de

Bir @PreviewTest işlevinin yanındaki gutter simgesini tıklayın ve Referans Görsel Ekle/Güncelle'yi seçin. İletişim kutusunda ö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 görselleri app/src/screenshotTestDebug/reference ({module}/src/screenshotTest{Variant}/reference) içinde bulabilirsiniz.

Test raporu oluşturma

Referans görseller oluşturulduktan sonra, IDE entegrasyonu veya Gradle görevleri için bu bölümdeki talimatları uygulayarak bir test raporu oluşturun.

IDE'de

Bir @PreviewTest işlevinin yanındaki gutter simgesini tıklayın ve Run 'ScreenshotTests' (ScreenshotTests'i çalıştır) 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 farkı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 görselle 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 konumunda bir HTML raporu oluşturur.

Sorun giderme

Compose Preview Screenshot Testing, ana makine tarafında testler çalıştırır. Bu testler, bellek açısından yoğun olabilir. gradle.properties dosyanıza aşağıdaki özelliği ekleyerek test JVM'si için maksimum yığın boyutunu artırabilirsiniz:

android.compose.screenshot.maxHeapSize=4g

Bilinen sorunlar

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

Bilinen sorunların tam listesini aracın Issue Tracker bileşeninde bulabilirsiniz. Diğer geri bildirimleri ve sorunları Issue Tracker üzerinden bildirin.

Yayın güncellemeleri

Sürüm güncellemelerinin tam listesi için sürüm notlarına bakın.