Die Testpyramide von NextPDF

Spec Spec: ISO/IEC/IEEE 29119-4 ISO/IEC/IEEE 29119-4 Spec Spec: ISO/IEC 25010 ISO/IEC 25010 Evidence ✓ Test-backed Evidence: Test-backed PHPStan Level 10 PHPStan: Level 10

Auf einen Blick

NextPDF setzt nicht auf nur eine Art von Test. Es gibt fünf Stufen, und jede beantwortet eine andere Frage zur Engine. Das ist nötig, weil ein PDF einen Unit-Test bestehen und auf der Festplatte trotzdem eine strukturell defekte Datei sein kann. Diese Seite beschreibt die fünf Stufen und was jede einzelne belegen muss.

Warum das wichtig ist

Eine PDF-Engine kann auf ungewöhnlich vielen Ebenen scheitern. Derselbe Codepfad kann funktional korrekt und als Bytefolge korrekt sein und dennoch eine Datei erzeugen, die ein konformer Reader ablehnt. Außerdem kann er eine Datei erzeugen, die erst an einem Seitenumbruch unauffällig falsch gerendert wird. Testen Sie die Engine nur auf einer einzigen Granularitätsebene, gewinnen Sie Vertrauen genau in diese Granularität und in nichts anderes.

Die einschlägige Normenliteratur ist in diesem Punkt eindeutig. Spezifikationsbasierte und strukturbasierte Testentwurfstechniken stehen nicht zwingend in Beziehung zueinander, und eine Teststrategie sollte mehr als ein Kriterium verwenden, darunter mindestens ein funktionales und ein strukturelles (ISO/IEC/IEEE 29119-4, Annex A). Eine einzelne Stufe ist keine verkleinerte Version einer guten Strategie. Sie ist eine andere Strategie, und zwar eine unvollständige.

Die Kurzfassung

Die Tests von NextPDF sind in fünf Stufen organisiert, von der Basis bis zur Spitze:

1. Unit — eine Klasse oder Funktion, isoliert. Die breite Basis.
2. Integration — zusammenarbeitende Einheiten über eine Modulgrenze hinweg.
3. Strukturell — der ausgegebene PDF-Objektgraph, die Querverweistabelle und der Trailer sind wohlgeformt und konform.
4. Visuell — die gerenderte Seite stimmt innerhalb einer angegebenen Toleranz mit einer freigegebenen Referenz überein.
5. Golden — fixierte End-to-End-Fixtures, die unbeabsichtigte Abweichungen in der finalen Ausgabe erkennen. Die Spitze.

Jede Stufe belegt etwas, das die darunterliegende Stufe nicht belegen kann. Keine von ihnen ist Beiwerk. Die Pyramidenform betrifft die Menge — viele günstige Unit-Tests, weniger teure End-to-End-Tests — nicht die Wichtigkeit.

Wie NextPDF es angeht

Die Stufen existieren physisch; sie sind nicht nur ein Zielbild. Die PHPUnit-Konfiguration des Repositorys deklariert jede als benannte Testsuite, die eins zu eins einem Verzeichnis zugeordnet ist. Eine Stufe ist daher ein konkreter Ort, auf den Sie einen Runner ansetzen können, und kein Etikett auf einer Folie. Zu den Suiten, die erfahrene Entwickler wiedererkennen, gehören Unit, Integration, Golden, Snapshot, Reproducibility, Conformance, Standards und Performance, jede mit ihrem eigenen Ausführungsprofil (Isolation, Zeitfenster und ob sie standardmäßig in der Continuous Integration läuft).

Diese Trennung ist bewusst gewählt. Die schnelle Basisstufe (Unit) läuft bei jeder Änderung mit einem Zeitbudget von einer Sekunde pro Test. Die langsameren, umgebungsempfindlichen Stufen — visuelles Rendering, vollständige Konformität, Performance — sind optional oder laufen nachts. So bleibt der übliche Entwicklungspfad schnell und deterministisch, ohne auf die tieferen Prüfungen zu verzichten. Strikte Typisierung trägt den gesamten Stack. Die Engine wird mit Spec Spec: PHPStan, Level 10 PHPStan Level 10 analysiert, wobei das Fehlerbudget auf null fixiert ist, sodass eine große Klasse von Defekten gar nicht erst bis zu einem Test gelangt.

1. Tier 1 of 5 Unit Isolated behaviour of a single class or function; the broad base.
2. Tier 2 of 5 Integration Collaborating units across a module boundary.
3. Tier 3 of 5 Structural The emitted PDF object/xref structure is well-formed and conformant.
4. Tier 4 of 5 Visual Rendered output matches an approved reference within tolerance.
5. Tier 5 of 5 Golden End-to-end byte/lossless fixtures pinned as the contract; the apex.

Die fünf Teststufen von NextPDF, von der Basis bis zur Spitze. Unit ist die breite, schnelle Basis; jede Stufe darüber belegt eine Eigenschaft, die die darunterliegende Stufe nicht kann, bis hinauf zu den Golden-End-to-End-Fixtures an der Spitze. Die Breite ist nur ein Mengenhinweis — sie wertet die Wichtigkeit nicht.

Human-factors note: Human-factors note

Abdeckung ist nicht Vertrauen. Ein Zeilenabdeckungswert sagt Ihnen, dass eine Zeile während des Laufs ausgeführt wurde; er sagt Ihnen nicht, ob der Test bemerkt hätte, wenn diese Zeile falsch gewesen wäre. Die Pyramide existiert, weil jede Stufe eine andere Fehlerart sichtbar macht — eine Funktion, die den falschen Wert zurückgibt, zwei Einheiten, die an einer Grenze nicht übereinstimmen, eine strukturell ungültige Datei, eine visuelle Regression, eine Abweichung auf Byte-Ebene. Das Stapeln der Stufen, nicht das Maximieren einer einzelnen Zahl, bringt vertrauenswürdige Ausgabe hervor. Mutation-Testing, separat behandelt, ist die Methode, mit der NextPDF misst, ob die Tests in diesen Stufen tatsächlich Fehler erkennen.

Was die Belege sagen

Evidence ✓ Test-backed Evidence: Test-backed Die fünf Suiten existieren als deklarierte PHPUnit-Testsuites in der Konfiguration der Engine, jede an ihr eigenes Verzeichnis und Ausführungsprofil gebunden. Das Stufenvokabular auf dieser Seite ist dasselbe Vokabular, das die Testinfrastruktur verwendet.

Evidence § Standard-backed Evidence: Standard-backed Der Grund für mehr als eine Stufe ist in Spec Spec: ISO/IEC/IEEE 29119-4, Annex A ISO/IEC/IEEE 29119-4 Annex A verankert: Abdeckungskriterien stehen nicht alle in einer Subsumtionsbeziehung zueinander, und Strategien sollten funktionale und strukturelle Techniken kombinieren. Entscheidend ist, dass derselbe Anhang anmerkt, dass die Subsumtionsordnung zwischen Abdeckungskriterien keinen Hinweis auf ihre Fähigkeit gibt, Fehler aufzudecken — also auf Testwirksamkeit (ISO/IEC/IEEE 29119-4, §C.2.4). „Mehr Abdeckung“ ist nicht dieselbe Aussage wie „bessere Tests“.

Evidence § Standard-backed Evidence: Standard-backed Die Wahl, welche Eigenschaften belegt werden, lässt sich auf die Produktqualitätsmerkmale von Spec Spec: ISO/IEC 25010 ISO/IEC 25010 abbilden: funktionale Korrektheit (Unit, Integration) und die Eigenschaften auf Dateiebene, die ein PDF in nachgelagerten Systemen tatsächlich nutzbar machen (strukturell, visuell, Golden). Das Qualitätsmodell stellt ausdrücklich klar, dass unterschiedliche Merkmale in unterschiedlichen Nutzungskontexten von Bedeutung sind.

Praktisches Beispiel

Die Stufen sind über die Skripte der Engine selbst aufrufbar. Eine Änderung an einem einzelnen Formatter wird an der Basis verifiziert. Eine Änderung an der Dokument-Fassade wird über mehrere Stufen hinweg verifiziert:

<?php

declare(strict_types=1);

// Tier 1 — Unit: one unit, isolated, fast.
// composer test:unit         → phpunit --testsuite Unit

// Tier 2 — Integration: collaborating units across a boundary.
// composer test:integration  → phpunit --testsuite Integration

// Tier 3 — Structural: the emitted PDF object graph is well-formed.
// vendor/bin/phpunit --testsuite Conformance

// Tier 4/5 — Visual + Golden: rendered/serialized output vs a pinned
// reference (golden is byte/structure-pinned, never auto-updated).
// vendor/bin/phpunit --testsuite Golden

// A change to the document facade touches every API, so the routing
// guidance escalates it from "unit only" to the full unit + integration
// surface — the tier you run is a function of blast radius, not habit.

Der Sinn des Beispiels ist die Routing-Logik, nicht die Befehle. Welche Stufe Sie ausführen, hängt davon ab, was die Änderung beschädigen kann. Die Infrastruktur macht jede Stufe zu einem eigenständigen, separat ausführbaren Ziel.

Häufiges Missverständnis

Die Pyramide wird häufig als Rangordnung gelesen — Unit-Tests unten, weil sie am wenigsten wichtig seien, End-to-End oben, weil sie am wichtigsten seien (oder umgekehrt). Sie ist weder das eine noch das andere. Die vertikale Achse steht grob für Kosten und Menge: viele schnelle, günstige Unit-Tests bilden eine breite Basis; nach oben hin gibt es zunehmend weniger, langsamere, realitätsnähere Tests. Ein Golden-Test ist nicht „besser“ als ein Unit-Test. Er erkennt einen anderen Fehler, später und teurer, und wäre ein schlechter Ersatz für die Tausenden schnellen Prüfungen darunter.

Das zweite Missverständnis ist, dass eine hohe Abdeckungszahl bedeutet, die Pyramide sei solide. Das tut sie nicht. Abdeckung misst Ausführung, nicht Erkennung. Die Normen lehnen es ausdrücklich ab, die Abdeckungsordnung mit der Fähigkeit zur Fehlerfindung gleichzusetzen. Genau diese Lücke aufzudecken ist der Zweck des Mutation-Testings.

Grenzen und Abgrenzungen

Diese Seite beschreibt die Gestalt und Absicht der Strategie, nicht ihre aktuellen Ergebnisse. Testanzahlen, Abdeckungsprozentsätze und Mutation-Scores fehlen hier bewusst. Sie sind laufende Qualitätssignale, erzeugt aus Continuous-Integration-Artefakten. Die aktuellen Werte werden mit dem Build veröffentlicht. In Prosa eingefroren, würden sie stillschweigend veralten. Die einzige genannte Zahl — PHPStan Level 10 — ist eine stabile Tatsache der Konfiguration, überprüfbar in der Konfiguration der statischen Analyse der Engine, keine Messung.

Die Stufen-namen sind stabiles Architekturvokabular. Die genaue Menge der Suiten und ihre Ausführungsprofile entwickeln sich mit der Engine weiter und gehören in die Testkonfiguration, die maßgeblich ist, falls sie jemals dieser Erklärung widerspricht. Diese Seite behauptet keine bestimmte Erfolgsquote und stellt keinen Vergleich mit der Teststrategie einer anderen Bibliothek an.

Verwandte Dokumente

• Golden-File-Testing — wie die Spitzenstufe die Referenzausgabe fixiert und verlässlich bleibt.
• Mutation-Testing, erklärt — warum eine Abdeckungszahl nicht belegt, dass die Tests in diesen Stufen tatsächlich funktionieren.
• Strikte Typen, überall — wie PHPStan Level 10 eine Klasse von Defekten beseitigt, bevor irgendeine Stufe läuft.

Glossar

• Teststufe — eine Ebene der Strategie, die eine bestimmte Art von Eigenschaft belegt (zum Beispiel Unit-Verhalten oder strukturelle Gültigkeit). NextPDF verwendet fünf.
• Struktureller Test — eine Prüfung, dass der Objektgraph des ausgegebenen PDFs, die Querverweistabelle und der Trailer wohlgeformt und konform sind, anstatt lediglich einen Rückgabewert zu prüfen.
• Visueller Test — eine Prüfung, dass eine gerenderte Seite innerhalb einer angegebenen Toleranz mit einem freigegebenen Referenzbild übereinstimmt.
• Golden-Test — eine End-to-End-Prüfung gegen eine fixierte Referenzausgabe, die niemals automatisch aktualisiert wird; die verbindliche Absicherung dafür, dass „sich die Ausgabe nicht geändert hat“.
• Testwirksamkeit — die Fähigkeit eines Testsatzes, Fehler aufzudecken, die ISO/IEC/IEEE 29119-4 von Abdeckung unterscheidet. Akronymhinweis: MSI (Mutation Score Indicator) wird auf der Seite Mutation-Testing definiert.
• PHPStan Level 10 — die strikteste Ebene der statischen Analyse; NextPDF führt sie mit auf null fixiertem Fehlerbudget aus.