Golden Test — co to je, jak funguje snapshot-testování a použití

Co je Golden Test a jak funguje?

Golden Test — je automatizovaná kontrola vzhledu komponenty porovnáním pixel po pixelu s referencí. Proces: (1) vývojář nebo tester pořídí první snímek komponenty — to je “golden” (reference). (2) Golden-soubor je uložen v repozitáři vedle testu. (3) Při následných spuštěních test znovu vyrenderuje komponentu a porovná ji s uloženým golden. (4) Pokud se obrázky shodují — test je zelený. Pokud se liší — test je červený s diffem. Rozhodnutí: buď jsou změny očekávané (aktualizujeme golden), nebo je to chyba.

Jak se golden generuje — knihovna vykreslí komponentu do off-screen bufferu (Android: Canvas, iOS: UIGraphicsImageRenderer) bez reálného displeje. To znamená, že golden-testy fungují na CI bez emulátoru obrazovky (virtual display), což zrychluje provádění. Paparazzi na Androidu používá Layoutlib z Android Studio — stejný engine jako Layout Editor. iOSSnapshotTestCase používá UIKit rendering do CGImage. Výsledek — PNG soubor s pevnou velikostí.

Velikost golden-souborů a správa úložiště

Golden-soubory — PNG snímek jedné obrazovky (1080x1920) zabírá 200-800 KB v závislosti na složitosti. Pro projekt s 500 golden-testy je to ~100-400 MB v repozitáři. Řešení: (1) ukládat golden do Git LFS. (2) Používat kompresi PNG (pngcrush, oxipng). (3) Ukládat golden do samostatného úložiště (S3) a stahovat při sestavení. V IT Sectr ukládáme golden v Git LFS s prahem 1 MB na soubor — to stačí pro 90% testů.

Flaky golden testy a jejich řešení

Flaky golden testy — hlavní problém golden-testů. Různé GPU, verze písem a anti-aliasing vytvářejí mikro-rozdíly v pixelech. Řešení: threshold (povolené procento odlišných pixelů), fuzzy comparison (rozmazané porovnání) a spouštění na identických CI agentech (stejné GPU, OS, verze emulátoru). V Paparazzi se používá pixel-perfect porovnání, proto musí být CI agenti identičtí.

Golden Test vs Screenshot Test: jaký je rozdíl?

Golden Test — je typ screenshot-testování s pevnou referencí. Termín “golden” znamená, že reference byla schválena (přijata) týmem a uložena v repozitáři. Každá změna obrázku vyžaduje vědomé rozhodnutí vývojáře: aktualizovat golden nebo opravit kód. Golden Test pracuje na úrovni jednotlivých komponent (Composable, UIView) a nevyžaduje reálné zařízení.

Screenshot Test — širší pojem. Screenshot-test může zachytit celou obrazovku s reálnými daty, navigací, systémovým stavovým řádkem a animacemi. Screenshot-testy se často spouštějí na reálných zařízeních nebo emulátorech přes UI Automator (Android) nebo XCUITest (iOS). Golden-testy pracují v unit-test prostředí (JVM, XCTest) bez emulátoru a zachycují pouze jednu komponentu.

Strategie pokrytí: golden vs screenshot

Golden vs Screenshot — golden-testy pro kontrolu jednotlivých UI komponent (tlačítko, karta, dialog) při každém commitu. Screenshot-testy — pro E2E kontrolu celých obrazovek před vydáním. Golden-testy poskytují vývojáři rychlou zpětnou vazbu, screenshot-testy — důvěru v integritu celé aplikace. V IT Sectr používáme golden-testy pro Pull Request (3-5 minut) a screenshot-testy pro nightly (30-60 minut).

Paparazzi a Roborazzi: snapshot-testování na Androidu

Paparazzi — knihovna od Cash App (Square), která vykresluje Android View a Jetpack Compose komponenty do PNG bez emulátoru. Používá Layoutlib (stejný engine jako Android Studio Preview). Nastavení: připojit Gradle plugin, napsat test s @Test a @RunWith(PaparazziRule::class), zavolat paparazzi.snapshot(view). Paparazzi nepodporuje animace, video a Real Device — pouze statické vykreslování komponent.

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

// Golden test pro Compose komponentu
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 — alternativa k Paparazzi s podporou Compose, View a porovnávání obrázků. Rozdíl: Roborazzi pracuje přes Robolectric a podporuje threshold (procento povolené odchylky pixelů). To snižuje flakiness při různých GPU na CI. Roborazzi také umí vytvářet GIF animace změn (před/po/diff), což je vhodné pro code review. Formát golden-souborů: PNG + JSON metadata.

Aktualizace golden — po záměrné změně UI vývojář smaže staré golden-soubory a spustí testy s flagem record. Paparazzi znovu vytvoří všechny golden-soubory. Poté vývojář commitne nový golden spolu se změnou kódu. Při code review recenzent vidí diff starých a nových golden. Pokud jsou změny schváleny — PR je sloučen. Pokud ne — vývojář opraví kód a znovu spustí testy. Nikdy neaktualizujte golden automaticky na CI — pouze lokálně.

SwiftSnapshotTesting a iOSSnapshotTestCase na iOS

SwiftSnapshotTesting — knihovna od pointfree.co, tvůrců Composable Architecture. Podporuje UIView, UIViewController, CALayer a SwiftUI View. Princip: assertSnapshot(matching: view, as: .image). Při prvním spuštění se golden vytvoří automaticky. Při dalších — porovnává se. Pokud rozdíl překročí povolenou mez — test selže. SwiftSnapshotTesting funguje přes UIGraphicsImageRenderer, který je kompatibilní s CI (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 (dříve FBSnapshotTestCase) — knihovna od Uber pro UIKit. Na rozdíl od SwiftSnapshotTesting vyžaduje iOSSnapshotTestCase určení velikosti obrazovky a orientace. Golden-soubory — PNG ve složce ReferenceImages. Výhoda: funguje s UIKit bez SwiftUI a podporuje iOS 12+. Nevýhoda: neaktualizuje golden automaticky — je třeba spustit s flagem record. SwiftSnapshotTesting je modernější a doporučuje se pro nové projekty.

Golden specifický pro zařízení — golden-soubory se liší pro různé velikosti obrazovek a orientace. Standardní přístup: pojmenovat golden jako TestName@3x~iPhone14.png. SwiftSnapshotTesting automaticky přidá suffix zařízení, pokud je uveden parametr .image(on: .iPhoneSe). Na Androidu Paparazzi používá DeviceConfig pro nastavení velikosti. Uchovávejte golden pro každý podporovaný formát zařízení zvlášť. Nepoužívejte jeden golden pro různé velikosti — to povede k flaky testům.

Práce se golden-soubory v CI a správa aktualizací

CI pipeline — golden-testy by měly být spouštěny při každém Pull Request. Pokud test selže, CI zobrazí diff-obrázek jako artefakt sestavení. Vývojář prohlédne diff a rozhodne se. Důležité: golden-soubory vygenerované na CI nejsou nikdy automaticky commitovány. Pouze lokální generování vývojářem po záměrné změně. GitHub Actions a GitLab CI podporují nahrávání artefaktů (png, html) pro prohlížení diff v prohlížeči.

Velikost repozitáře — golden-soubory rychle rostou. 500 testů = 100-400 MB PNG. Řešení: (1) Git LFS — každý golden je uložen v LFS, klonován pouze při checkout. (2) Ukládání golden v samostatném repozitáři a připojení jako submodul. (3) S3 + cache — golden na S3, CI stahuje pouze změněné soubory podle checksumu. V IT Sectr používáme Git LFS s track *.png filter=lfs diff=lfs merge=lfs text=false. Lokálně golden leží v src/test/goldens/.

Code review golden — běžný git diff nezobrazuje změny PNG. Řešení: (1) GitHub otevírá PNG obrázky po kliknutí. (2) Použití Review Apps, kde je golden-diff viditelný v prohlížeči. (3) Generování HTML zprávy se sloupci před/po/diff. Paparazzi vytváří HTML zprávu se třemi sloupci: actual, expected, diff. Zpráva je připojena k CI artefaktům. Recenzenti prohlížejí zprávu bez stahování souborů lokálně.

Kdy aktualizovat golden — pouze po vědomé změně UI. Změna písma, barvy, mezery, ikony — golden by měl být aktualizován. Přidání nového tlačítka, přeskupení prvků — golden by měl být aktualizován. Oprava chyby měnící vzhled — golden by měl být aktualizován. Refaktorování bez změny UI — golden by neměl být aktualizován. Pokud se golden mění bez změny UI kódu — je to flaky test způsobený prostředím, hledejte příčinu v CI agentech nebo verzích závislostí.