Golden Test — mi ez, hogyan működik a snapshot-tesztelés és alkalmazása

Mi a Golden Test és hogyan működik?

Golden Test — a komponens megjelenésének automatizált ellenőrzése pixelről-pixelre történő összehasonlítással a referenciával. Folyamat: (1) a fejlesztő vagy tesztelő elkészíti a komponens első felvételét — ez a “golden” (referencia). (2) A golden-fájl a teszt mellett a repository-ban kerül elmentésre. (3) A későbbi futtatások során a teszt újra rendereli a komponenst és összehasonlítja az elmentett golden-nel. (4) Ha a képek egyeznek — a teszt zöld. Ha eltérnek — a teszt piros diff-fel. Döntés: vagy a változtatások várhatóak (frissítjük a golden-t), vagy ez egy hiba.

Hogyan generálódik a golden — a könyvtár a komponenst egy off-screen pufferben rendereli (Android: Canvas, iOS: UIGraphicsImageRenderer) valódi kijelző nélkül. Ez azt jelenti, hogy a golden-tesztek CI-n működnek képernyő-emulátor (virtual display) nélkül, ami felgyorsítja a végrehajtást. A Paparazzi Androidon az Android Studio Layoutlib-jét használja — ugyanazt a motort, mint a Layout Editor. Az iOSSnapshotTestCase UIKit-renderelést használ CGImage-be. Eredmény — egy rögzített méretű PNG fájl.

A golden-fájlok mérete és tároláskezelés

Golden-fájlok — egy képernyő PNG felvétele (1080x1920) 200-800 KB-ot foglal a komplexitástól függően. Egy 500 golden-teszttel rendelkező projekt esetén ez ~100-400 MB a repository-ban. Megoldások: (1) golden tárolása Git LFS-ben. (2) PNG tömörítés használata (pngcrush, oxipng). (3) Golden tárolása külön tárhelyen (S3) és letöltés build-kor. Az IT Sectr-nél golden-t Git LFS-ben tárolunk 1 MB fájlonkénti küszöbértékkel — ez a tesztek 90%-ához elegendő.

Flaky golden tesztek és megoldásuk

Flaky golden tesztek — a golden-tesztek fő problémája. Különböző GPU-k, betűtípus-verziók és anti-aliasing mikro-eltéréseket okoznak a pixelekben. Megoldások: threshold (eltérő pixelek megengedett százaléka), fuzzy comparison (elmosódott összehasonlítás) és azonos CI-ügynökökön történő futtatás (azonos GPU, OS, emulátorverzió). A Paparazzi pixel-perfect összehasonlítást használ, ezért a CI-ügynököknek azonosnak kell lenniük.

Golden Test vs Screenshot Test: mi a különbség?

Golden Test — a screenshot-tesztelés egy fajtája rögzített referenciával. A “golden” kifejezés azt jelenti, hogy a referenciát a csapat jóváhagyta (elfogadta) és a repository-ban tárolja. A kép bármilyen változása a fejlesztő tudatos döntését igényli: a golden frissítése vagy a kód javítása. A Golden Test egyes komponensek szintjén működik (Composable, UIView) és nem igényel valódi eszközt.

Screenshot Test — tágabb fogalom. A Screenshot-test a teljes képernyőt rögzítheti valódi adatokkal, navigációval, rendszer állapotsorral és animációkkal. A Screenshot-tesztek gyakran valódi eszközökön vagy emulátorokon futnak UI Automator (Android) vagy XCUITest (iOS) segítségével. A Golden-tesztek unit-test környezetben (JVM, XCTest) működnek emulátor nélkül és csak egy komponenst rögzítenek.

Lefedettségi stratégia: golden vs screenshot

Golden vs Screenshot — golden-tesztek az egyes UI-komponensek (gomb, kártya, párbeszédablak) ellenőrzésére minden commit-nál. Screenshot-tesztek — a teljes képernyők E2E ellenőrzésére kiadás előtt. A golden-tesztek gyors visszajelzést adnak a fejlesztőnek, a screenshot-tesztek — bizalmat a teljes alkalmazás integritásában. Az IT Sectr-nél golden-teszteket használunk Pull Request-hez (3-5 perc), screenshot-teszteket — nightly futtatásokhoz (30-60 perc).

Paparazzi és Roborazzi: snapshot-tesztelés Androidon

Paparazzi — a Cash App (Square) könyvtára, amely Android View és Jetpack Compose komponenseket renderel PNG-be emulátor nélkül. A Layoutlib-et használja (ugyanaz a motor, mint az Android Studio Preview). Beállítás: Gradle plugin csatlakoztatása, teszt írása @Test és @RunWith(PaparazziRule::class) paranccsal, paparazzi.snapshot(view) meghívása. A Paparazzi nem támogatja az animációkat, videót és Real Device-t — csak statikus komponens-renderelést.

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

// Golden test a Compose-komponenshez
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 — a Paparazzi alternatívája Compose, View és képek összehasonlításának támogatásával. Különbség: a Roborazzi Robolectric-en keresztül működik és támogatja a threshold-t (megengedett pixelkülönbség százaléka). Ez csökkenti a flakiness-t különböző GPU-k esetén CI-n. A Roborazzi képes GIF-animációkat is készíteni a változásokról (előtte/utána/diff), ami kényelmes a kód áttekintéséhez. A golden-fájlok formátuma: PNG + JSON metaadatok.

Golden frissítése — a UI szándékos megváltoztatása után a fejlesztő törli a régi golden-fájlokat és record flag-gel futtatja a teszteket. A Paparazzi újra létrehozza az összes golden-fájlt. Ezután a fejlesztő commit-eli az új golden-t a kódváltoztatással együtt. A kód áttekintése során a bíráló látja a régi és új golden-ek diff-jét. Ha a változtatások jóvá vannak hagyva — a PR egyesítésre kerül. Ha nem — a fejlesztő kijavítja a kódot és újra futtatja a teszteket. Soha ne frissítse a golden-t automatikusan CI-n — csak lokálisan.

SwiftSnapshotTesting és iOSSnapshotTestCase iOS-en

SwiftSnapshotTesting — a pointfree.co könyvtára, a Composable Architecture alkotói. Támogatja a UIView, UIViewController, CALayer és SwiftUI View típusokat. Elv: assertSnapshot(matching: view, as: .image). Az első futtatáskor a golden automatikusan létrejön. A következőknél — összehasonlításra kerül. Ha a különbség meghaladja a megengedettet — a teszt sikertelen. A SwiftSnapshotTesting a UIGraphicsImageRenderer-en keresztül működik, amely kompatibilis a CI-vel (Xcode Cloud, GitHub Actions).

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 (korábban FBSnapshotTestCase) — az Uber könyvtára UIKit számára. A SwiftSnapshotTesting-től eltérően az iOSSnapshotTestCase megköveteli a képernyő méretének és tájolásának megadását. Golden-fájlok — PNG a ReferenceImages mappában. Előny: UIKit-kel működik SwiftUI nélkül és támogatja az iOS 12+-t. Hátrány: nem frissíti automatikusan a golden-t — record flag-gel kell futtatni. A SwiftSnapshotTesting modernebb és új projektekhez ajánlott.

Eszközspecifikus golden — a golden-fájlok eltérőek a különböző képernyőméretek és tájolások esetén. Szabványos megközelítés: a golden elnevezése TestName@3x~iPhone14.png formátumban. A SwiftSnapshotTesting automatikusan hozzáadja az eszköz utótagot, ha az .image(on: .iPhoneSe) paraméter meg van adva. Androidon a Paparazzi a DeviceConfig-ot használja a méret beállításához. Tárolja a golden-t minden támogatott eszköz form faktorhoz külön. Ne használjon egy golden-t különböző méretekhez — ez flaky tesztekhez vezet.

Golden-fájlok használata CI-ben és frissítések kezelése

CI pipeline — a golden-teszteket minden Pull Request-nél futtatni kell. Ha a teszt sikertelen, a CI megjeleníti a diff-képet build műtermékként. A fejlesztő megtekinti a diff-et és döntést hoz. Fontos: a CI-n generált golden-fájlok soha nem kerülnek automatikus commit-ra. Csak a fejlesztő általi lokális generálás szándékos változtatás után. A GitHub Actions és a GitLab CI támogatja a műtermékek (png, html) feltöltését a diff böngészőben történő megtekintéséhez.

Repository mérete — a golden-fájlok gyorsan nőnek. 500 teszt = 100-400 MB PNG. Megoldások: (1) Git LFS — minden golden LFS-ben tárolva, csak checkout-kor klónozva. (2) Golden tárolása külön repository-ban és almodulként csatlakoztatva. (3) S3 + gyorsítótárazás — golden az S3-on, a CI csak a checksum alapján módosított fájlokat tölti le. Az IT Sectr-nél Git LFS-t használunk track *.png filter=lfs diff=lfs merge=lfs text=false beállítással. Lokálisan a golden-ek a src/test/goldens/ mappában találhatók.

Golden kód áttekintése — a szokásos git diff nem mutatja a PNG-változásokat. Megoldások: (1) A GitHub megnyitja a PNG-képeket kattintásra. (2) Review Apps használata, ahol a golden-diff látható a böngészőben. (3) HTML-jelentés generálása előtte/utána/diff oszlopokkal. A Paparazzi három oszlopos HTML-jelentést készít: actual, expected, diff. A jelentés a CI-műtermékekhez csatolódik. A bírálók a jelentést a fájlok lokális letöltése nélkül tekintik meg.

Mikor frissítsük a golden-t — csak a UI tudatos megváltoztatása után. Betűtípus, szín, térköz, ikon változása — a golden-t frissíteni kell. Új gomb hozzáadása, elemek átrendezése — a golden-t frissíteni kell. Hibajavítás, amely megváltoztatja a megjelenést — a golden-t frissíteni kell. Refaktorálás UI-változtatás nélkül — a golden-t nem kell frissíteni. Ha a golden UI-kód változtatása nélkül változik — ez egy flaky teszt, amelyet a környezet okoz, keresse az okot a CI-ügynökökben vagy a függőségi verziókban.