Golden Test — nedir, snapshot testi nasıl çalışır ve uygulaması

Golden Test nedir ve nasıl çalışır?

Golden Test, bir bileşenin görsel görünümünün bir referansla piksel piksel karşılaştırılarak otomatik olarak kontrol edilmesidir. Süreç: (1) geliştirici veya testçi bileşenin ilk anlık görüntüsünü oluşturur — bu “golden” (referans)dır. (2) Golden dosyası, testin yanında depoda kaydedilir. (3) Sonraki çalıştırmalarda, test bileşeni yeniden oluşturur ve kaydedilen golden ile karşılaştırır. (4) Görüntüler eşleşirse — test yeşil. Farklıysa — test kırmızı ve diff gösterir. Karar: ya değişiklikler bekleniyordur (golden güncellenir) ya da bu bir hatadır.

Golden nasıl oluşturulur — kütüphane, bileşeni gerçek bir ekran olmadan ekran dışı tampona (Android: Canvas, iOS: UIGraphicsImageRenderer) oluşturur. Bu, golden testlerin ekran öykünücüsü (sanal ekran) olmadan CI'da çalıştığı ve yürütmeyi hızlandırdığı anlamına gelir. Android'de Paparazzi, Android Studio'nun Layoutlib'ini — Layout Editor'ün kullandığı aynı motoru — kullanır. iOSSnapshotTestCase, CGImage'da UIKit oluşturmayı kullanır. Sonuç, sabit boyutlu bir PNG dosyasıdır.

Golden dosyalarının boyutu ve depolama yönetimi

Golden dosyaları — bir ekranın (1080x1920) PNG anlık görüntüsü, karmaşıklığa bağlı olarak 200–800 KB yer kaplar. 500 golden testi olan bir proje için, depoda ~100–400 MB'dir. Çözümler: (1) golden'ı Git LFS'de saklayın. (2) PNG sıkıştırma (pngcrush, oxipng) kullanın. (3) Golden'ı ayrı bir depolamada (S3) saklayın ve derleme sırasında indirin. IT Sectr'de, golden dosyalarını dosya başına 1 MB eşikle Git LFS'de saklıyoruz — bu testlerin %90'ı için yeterlidir.

Dengesiz (Flaky) golden testleri ve çözümü

Dengesiz golden testler — golden testlerin ana sorunu. Farklı GPU'lar, yazı tipi sürümleri ve kenar yumuşatma, piksellerde mikro farklılıklar oluşturur. Çözümler: eşik (izin verilen farklı piksel yüzdesi), bulanık karşılaştırma ve aynı CI aracılarında çalıştırma (aynı GPU, OS, öykünücü sürümü). Paparazzi piksel-mükemmel karşılaştırma kullanır, bu nedenle CI aracıları aynı olmalıdır.

Golden Test vs Screenshot Test: farkı nedir?

Golden Test, sabit bir referansa sahip bir ekran görüntüsü testi türüdür. “Golden” terimi, referansın ekip tarafından onaylandığı ve depoda saklandığı anlamına gelir. Herhangi bir görüntü değişikliği, geliştiricinin bilinçli bir karar vermesini gerektirir: golden'ı güncellemek veya kodu düzeltmek. Golden Test, tek tek bileşenler (Composable, UIView) düzeyinde çalışır ve gerçek bir cihaz gerektirmez.

Screenshot Test daha geniş bir kavramdır. Bir ekran görüntüsü testi, gerçek veriler, gezinme, sistem durum çubuğu ve animasyonlarla tam bir ekranı yakalayabilir. Ekran görüntüsü testleri genellikle UI Automator (Android) veya XCUITest (iOS) aracılığıyla gerçek cihazlarda veya öykünücülerde çalıştırılır. Golden testler, birim test ortamında (JVM, XCTest) öykünücü olmadan çalışır ve yalnızca tek bir bileşeni yakalar.

Kapsama stratejisi: golden vs screenshot

Golden vs Screenshot — her işlemede tek tek UI bileşenlerini (düğme, kart, iletişim kutusu) kontrol etmek için golden testler. Yayınlamadan önce tüm ekranların uçtan uca (E2E) kontrolü için ekran görüntüsü testleri. Golden testler geliştiriciye hızlı geri bildirim sağlar, ekran görüntüsü testleri tüm uygulamanın bütünlüğüne güven verir. IT Sectr'de, Pull Request'ler için golden testler (3–5 dakika) ve gecelik ekran görüntüsü testleri (30–60 dakika) kullanıyoruz.

Paparazzi ve Roborazzi: Android'de snapshot testi

Paparazzi — Cash App (Square) tarafından Android View ve Jetpack Compose bileşenlerini öykünücü olmadan PNG'ye dönüştüren bir kütüphane. Layoutlib'i (Android Studio Preview ile aynı motor) kullanır. Kurulum: Gradle eklentisini ekleyin, @Test ve @RunWith(PaparazziRule::class) ile bir test yazın, paparazzi.snapshot(view) çağrısı yapın. Paparazzi animasyonları, videoları veya gerçek cihazları desteklemez — yalnızca statik bileşen oluşturma.

// build.gradle.kts (module)
plugins {
    id("app.cash.paparazzi") version "1.3.1"
}

// Compose bileşeni için Golden test
class ButtonGoldenTest {

    @get:Rule
    val paparazzi = Paparazzi(
        Paparazzi.PaparazziSnapshotConfig(
            deviceConfig = DeviceConfig.PIXEL_6,
            theme = "android:Theme.Material.Light.NoActionBar"
        )
    )

    @Test
    fun primary_button() {
        paparazzi.snapshot {
            Button(
                onClick = { },
                modifier = Modifier.width(200.dp)
            ) {
                Text("Submit")
            }
        }
    }
}

Roborazzi — Compose, View ve görüntü karşılaştırmasını destekleyen Paparazzi'ye bir alternatif. Fark: Roborazzi, Robolectric aracılığıyla çalışır ve bir eşiği (izin verilen piksel farkı yüzdesi) destekler. Bu, CI'da farklı GPU'larla dengesizliği azaltır. Roborazzi ayrıca değişikliklerin GIF animasyonlarını (önce/sonra/diff) oluşturabilir, bu da kod incelemesi için kullanışlıdır. Dosya biçimi: PNG + JSON meta verileri.

Golden'ı güncelleme — kasıtlı bir UI değişikliğinden sonra, geliştirici eski golden dosyalarını siler ve testleri record bayrağıyla çalıştırır. Paparazzi tüm golden dosyalarını yeniden oluşturur. Ardından geliştirici, kod değişikliğiyle birlikte yeni golden dosyalarını iletir. Kod incelemesinde, inceleyici eski ve yeni golden dosyalarının diff'ini görür. Değişiklikler onaylanırsa — PR birleştirilir. Onaylanmazsa — geliştirici kodu düzeltir ve testleri yeniden başlatır. Golden dosyalarını CI'da asla otomatik olarak güncellemeyin — yalnızca yerel olarak.

iOS'te SwiftSnapshotTesting ve iOSSnapshotTestCase

SwiftSnapshotTesting — pointfree.co'nun kütüphanesi, Composable Architecture'ın yaratıcıları. UIView, UIViewController, CALayer ve SwiftUI View'i destekler. İlke: assertSnapshot(matching: view, as: .image). İlk çalıştırmada, golden otomatik olarak oluşturulur. Sonraki çalıştırmalarda karşılaştırılır. Fark izin verilen eşiği aşarsa test başarısız olur. SwiftSnapshotTesting, CI (Xcode Cloud, GitHub Actions) ile uyumlu olan UIGraphicsImageRenderer aracılığıyla çalışır.

import SnapshotTesting
import XCTest

final class ProfileCardSnapshotTests: XCTestCase {

    func test_profile_card_default() {
        let card = ProfileCard(
            name: "Alice",
            avatar: UIImage.testImage(),
            badge: "Pro"
        )
        let controller = UIHostingController(rootView: card)

        assertSnapshot(
            matching: controller,
            as: .image(on: .iPhoneSe),
            record: ProcessInfo.processInfo
                .environment["RECORD"] != nil
        )
    }
}

iOSSnapshotTestCase (eski adıyla FBSnapshotTestCase) — Uber'in UIKit için kütüphanesi. SwiftSnapshotTesting'in aksine, iOSSnapshotTestCase ekran boyutu ve yönünün belirtilmesini gerektirir. Golden dosyaları, ReferenceImages klasöründeki PNG'lerdir. Avantajı: SwiftUI olmadan UIKit ile çalışır ve iOS 12+'yı destekler. Dezavantajı: golden'ı otomatik olarak güncellemez — record bayrağıyla çalıştırılmalıdır. SwiftSnapshotTesting daha moderndir ve yeni projeler için önerilir.

Cihaza özel golden — golden dosyaları farklı ekran boyutları ve yönleri için farklılık gösterir. Standart yaklaşım: golden dosyalarını TestName@3x~iPhone14.png olarak adlandırın. SwiftSnapshotTesting, .image(on: .iPhoneSe) parametresi belirtilmişse otomatik olarak bir cihaz soneki ekler. Android'de Paparazzi, boyutu ayarlamak için DeviceConfig kullanır. Desteklenen her cihaz form faktörü için golden'ı ayrı ayrı saklayın. Farklı boyutlar için tek bir golden kullanmayın — bu dengesiz testlere yol açar.

CI'da golden dosyalarıyla çalışma ve güncelleme yönetimi

CI hattı — golden testler her Pull Request'te çalıştırılmalıdır. Bir test başarısız olursa, CI diff görüntüsünü bir derleme yapıtı olarak gösterir. Geliştirici diff'i inceler ve bir karar verir. Önemli: CI'da oluşturulan golden dosyaları asla otomatik olarak iletilmez. Yalnızca kasıtlı bir değişiklikten sonra geliştirici tarafından yerel olarak oluşturulur. GitHub Actions ve GitLab CI, tarayıcıda diff'leri görüntülemek için yapıt (png, html) yüklemeyi destekler.

Depo boyutu — golden dosyaları hızla büyür. 500 test = 100–400 MB PNG. Çözümler: (1) Git LFS — her golden LFS'de saklanır, yalnızca checkout sırasında kopyalanır. (2) Golden'ı ayrı bir depoda saklayın ve alt modül olarak ekleyin. (3) S3 + önbellekleme — golden S3'te, CI sağlama toplamına göre yalnızca değiştirilen dosyaları indirir. IT Sectr'de, track *.png filter=lfs diff=lfs merge=lfs text=false ile Git LFS kullanıyoruz. Yerel olarak, golden dosyaları src/test/goldens/ içindedir.

Golden kod incelemesi — normal git diff, PNG değişikliklerini göstermez. Çözümler: (1) GitHub, tıklandığında PNG görüntülerini açar. (2) Golden diff'lerin tarayıcıda görünür olduğu Review Apps'leri kullanın. (3) önce/sonra/diff sütunlarıyla bir HTML raporu oluşturun. Paparazzi, üç sütunlu (gerçek, beklenen, diff) bir HTML raporu oluşturur. Rapor, CI yapıtlarına eklenir. İnceleyiciler, dosyaları yerel olarak indirmeden raporu görüntüler.

Golden ne zaman güncellenmeli — yalnızca bilinçli bir UI değişikliğinden sonra. Yazı tipi, renk, dolgu, simge değişikliği — golden güncellenmelidir. Yeni bir düğme ekleme, öğeleri yeniden düzenleme — golden güncellenmelidir. Görsel görünümü değiştiren bir hata düzeltmesi — golden güncellenmelidir. UI değişikliği olmayan yeniden düzenleme — golden değişmemelidir. UI kodu değişikliği olmadan golden değişirse — bu ortamdan kaynaklanan dengesiz bir testtir, nedeni CI aracılarında veya bağımlılık sürümlerinde arayın.