Golden-file-testing

Spec: ISO/IEC/IEEE 29119-4 Spec: ISO/IEC 25010 Evidence: Test-backed

In een oogopslag

Een golden file is een vastgelegde weergave van hoe correcte uitvoer eruit hoort te zien, waarmee een test bij elke uitvoering de nieuwe uitvoer vergelijkt. NextPDF gebruikt goldens om onbedoelde wijzigingen op te sporen: een stream die anders is gecomprimeerd, een alinea die is verschoven of een coördinaat die afwijkt. Deze pagina legt uit hoe dat werkt en hoe een golden betrouwbaar blijft, in plaats van een verouderde referentie te worden die niemand leest.

Waarom dit belangrijk is

PDF-generatie is een lange pijplijn waarin op veel plekken geruisloos afwijkingen kunnen ontstaan. Een refactor die „niets verandert” kan ongemerkt operatoren herordenen, een transformatiematrix wijzigen of een tabelcel een minieme afstand verschuiven. Unittests sporen dit zelden op: ze controleren de waarde waar je aan dacht, niet de duizenden bytes waar je niet aan dacht. Structuur- en specificatiegebaseerde technieken detecteren verschillende fouten, en geen van beide vervangt de ander (ISO/IEC/IEEE 29119-4, Annex A). Een golden file is de specificatie-aan-de-hand-van-een-voorbeeld die de volledige uitvoer vastzet, niet één assertie.

Het risico werkt twee kanten op. Een golden die te streng is, faalt bij elke onschuldige wijziging en wordt blindelings opnieuw goedgekeurd totdat hij niets meer aantoont. Een golden die te ruim is, laat echte regressies door. Die balans goed krijgen is waar het vakmanschap zit.

De korte versie

Een golden file is een vastgezette referentie-uitvoer, gegenereerd op basis van bekend-correct engine-gedrag en vastgelegd in de repository.
Een golden-test genereert de uitvoer opnieuw en vergelijkt die met de vastgezette referentie; elk verschil laat de test mislukken en vereist een menselijke beslissing.
NextPDF vergelijkt op het niveau dat betekenisvol maar stabiel is: geëxtraheerde tekst en genormaliseerde structurele operatoren, geen ruwe bytes, omdat ruwe bytes ruis bevatten (tijdstempels, subset-ordening, compressie) die geen regressie is.
Het bijwerken van een golden is een doelbewuste, beoordeelde handeling achter een expliciete GOLDEN_UPDATE-schakelaar — nooit een automatisch „accepteer wat er ook veranderd is”.
Een golden verschilt op één doorslaggevend punt van snapshot- en karakterisatietesten: een golden wordt nooit automatisch bijgewerkt.

Hoe NextPDF het aanpakt

De golden-infrastructuur van de engine gebruikt een expliciete tweelaagse diff in plaats van een bytevergelijking:

Generate Render the fixture input through the current engine.
Layer 1 — text Extract human-readable text from the content stream; diff against the text golden. Catches dropped or reordered content and encoding regressions.
Layer 2 — structure Extract ordered PDF operators, normalise coordinates to a fixed precision, diff against the operator golden. Catches layout shifts and broken structure.
Decide Any diff fails the test; a human judges whether it is a regression or an intended change.

Hoe een golden-vergelijking van NextPDF verloopt: genereer de PDF, extraheer de betekenisvolle lagen (tekst, daarna genormaliseerde structurele operatoren), vergelijk elke laag met de vastgezette referentie en laat de test mislukken met een leesbaar rapport bij elk verschil.

Wat NextPDF bewust niet vergelijkt, is even belangrijk als wat het wel vergelijkt. Ruwe byte-uitvoer blijft buiten beeld, omdat tijdstempels, lettertype-subset-ordening en stream-compressie die broos maken zonder de vergelijking correcter te maken. Het vergelijken van afbeeldingen op pixelniveau blijft op dit niveau buiten beschouwing, omdat daarvoor een externe renderer nodig is en dat omgevingsvariatie introduceert. Drijvendekommacoördinaten worden genormaliseerd naar een vaste precisie, zodat betekenisloze afrondingsruis zich niet voordoet als een regressie. Dit is het verschil tussen een golden die gedrag test en een die vluchtige omgevingsruis test.

Deze keuze legt ook het reproduceerbaarheidsprofiel van de pagina vast: structureel. NextPDF documenteert drie profielen — bitwise (de exacte bytes worden gereproduceerd), structural (de objectgraaf en operatorvolgorde worden gereproduceerd, waarbij onschuldige variatie op byteniveau is toegestaan) en semantic (de betekenis wordt gereproduceerd). Golden-tests op dit niveau bevestigen het structurele profiel door hun opzet. Daarom blijven hun referenties bruikbaar na een upgrade van de compressiebibliotheek, maar falen ze nog steeds bij een verschoven tabel.

Wat het bewijs zegt

Evidence: Test-backed De tweelaagse vergelijking (tekstextractie, gevolgd door vergelijking van genormaliseerde structurele operatoren) is de gedocumenteerde golden-methodiek van de engine, waarbij vergelijking van ruwe bytes, afbeeldingsdiffs en exacte floats om bovenstaande redenen expliciet buiten beschouwing blijft. De golden-suite is een gedeclareerde, afzonderlijk uitvoerbare testsuite, los van de snapshot- en karakterisatiesuites.

Evidence: Test-backed Het eerlijkheidsmechanisme is concreet: golden-referenties zijn gegenereerde artefacten, niet met de hand geschreven. Het overschrijven ervan wordt afgeschermd door een expliciete GOLDEN_UPDATE-omgevingsschakelaar, gedocumenteerd als een zeldzame, altijd beoordeelde handeling. Snapshottests in de engine worden daarentegen bij de eerste uitvoering opnieuw gegenereerd en erkennen afwijkingen via een bijwerk-vlag. Karakterisatietesten leggen bestaand gedrag vast zonder te beweren dat het correct is. De drie zijn bewust verschillende hulpmiddelen.

Evidence: Standard-backed Een golden is een specificatie-aan-de-hand-van-een-voorbeeld. Spec: ISO/IEC/IEEE 29119-4, Annex A merkt op dat specificatiegebaseerde en structuurgebaseerde technieken verschillende foutklassen opvangen en dat een strategie ze moet combineren. Daarom staan goldens náást, en niet in plaats van, unit- en structurele tests in de testpiramide.

Praktijkvoorbeeld

Een golden-test is mechanisch eenvoudig; de discipline zit in de workflow eromheen:

<?php

declare(strict_types=1);

// 1. The fixture: a fixed HTML input committed next to the test.
//    tests/Golden/fixtures/html-inputs/002-basic-table.html

// 2. The pinned references, generated once from known-good behaviour:
//    002-basic-table.text.golden       (Layer 1 — extracted text)
//    002-basic-table.operators.golden  (Layer 2 — normalised operators)

// 3. The run compares; ANY difference fails:
//    vendor/bin/phpunit --testsuite Golden

// 4. An intended behaviour change is the ONLY time references move,
//    and it is explicit and reviewed — never automatic:
//    GOLDEN_UPDATE=1 vendor/bin/phpunit --testsuite Golden
//
//    The regenerated *.golden files land in the diff of the same change
//    that altered behaviour, so a reviewer sees the output delta next to
//    the code delta and signs off on both together.

Het voorbeeld ís het proces. De testcode vergelijkt alleen. Wat de golden betrouwbaar maakt, is dat een gewijzigde referentie als uitvoer wordt beoordeeld in dezelfde wijziging die de engine heeft aangepast.

Veelvoorkomend misverstand

De meest gemaakte fout is golden-testing zien als byte-voor-byte-testing. De goldens van NextPDF zijn niet de bytes van het bestand — ze zijn de geëxtraheerde tekst en de genormaliseerde structurele operatoren ervan. Het controleren van ruwe bytes zou falen bij een nieuwe zlib-versie, een andere subset-tag of een opnieuw gegenereerd tijdstempel, wat geen van alle een regressie is. De test zou binnen een week door herhaaldelijke goedkeuring nutteloos worden. (Waar exacte bytes daadwerkelijk gereproduceerd moeten worden, is dat het afzonderlijke, strengere bitwise-reproduceerbaarheidsprofiel, geen golden.)

De tweede fout is aannemen dat een groene golden-suite correctheid bewijst. Die bewijst het ontbreken van verandering. Een golden die uit foutieve uitvoer is gegenereerd, beschermt die fout getrouw. Goldens waken tegen regressie ten opzichte van een bekend-correcte basislijn; ze stellen niet vast dat de basislijn goed was. Daarvoor dienen de unit-, structurele en conformiteitsniveaus.

Grenzen en beperkingen

Een golden-test beantwoordt precies één vraag: is de uitvoer veranderd ten opzichte van de vastgezette referentie. De test zegt niet of de referentie ooit correct was. Hij meet ook geen prestaties, conformiteit of beveiliging. Dat zijn andere niveaus. De omvang van het fixture-corpus, het slagingspercentage van de suite en elk dekkingscijfer zijn levende kwaliteitssignalen die uit continuous-integration-artefacten worden gegenereerd en met de build worden gepubliceerd. Ze worden hier bewust niet vermeld, omdat ze hier zouden kunnen verouderen.

De exacte mapindeling, de interne werking van de vergelijker en de bijwerk-schakelaar vallen onder de testinfrastructuur van de engine en kunnen evolueren. De testconfiguratie is doorslaggevend als die ooit van deze uitleg afwijkt. Deze pagina doet geen uitspraak over de snapshot- of golden-tooling van enige andere bibliotheek.

Gerelateerde documentatie

De NextPDF-testpiramide — waar het golden-niveau zich binnen de vijf niveaus bevindt en wat het uniek aantoont.
Mutatietesten, uitgelegd — hoe NextPDF controleert of zijn tests, goldens inbegrepen, fouten daadwerkelijk detecteren.
Strikte typen, overal — de statische analyse die een klasse van defecten wegneemt voordat ook maar één golden wordt uitgevoerd.

Verklarende woordenlijst

Golden file — een vastgezette referentie-uitvoer, gegenereerd op basis van bekend-correct engine-gedrag en vastgelegd, waarmee een test bij elke uitvoering vergelijkt. Nooit automatisch bijgewerkt.
Tweelaagse diff — de golden-vergelijking van NextPDF: geëxtraheerde tekst (laag 1) plus genormaliseerde structurele operatoren (laag 2), in plaats van ruwe bytes.
Snapshottest — een verwante maar onderscheiden techniek waarbij de referentie bij de eerste uitvoering opnieuw wordt gegenereerd en afwijking wordt erkend via een bijwerk-vlag.
Karakterisatietest — een test die bestaand gedrag vastlegt zonder te beweren dat het correct is, doorgaans om een refactor veilig te maken.
Reproduceerbaarheidsprofiel — het niveau waarop uitvoer gereproduceerd moet worden: bitwise (exacte bytes), structural (objectgraaf en operatorvolgorde, onschuldige bytevariatie toegestaan) of semantic (betekenis). Golden-tests bevestigen hier het structurele profiel.
GOLDEN_UPDATE — de expliciete omgevingsschakelaar die het overschrijven van golden-referenties autoriseert; een zeldzame, beoordeelde handeling.