La pyramide des tests de NextPDF

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

En un coup d’œil

NextPDF ne repose pas sur un seul type de test. Sa stratégie comporte cinq niveaux, et chacun répond à une question différente sur le moteur. La raison est simple : un PDF peut réussir un test unitaire tout en restant un fichier structurellement cassé sur le disque. Cette page nomme les cinq niveaux et ce que chacun doit prouver.

Pourquoi c’est important

Un moteur PDF présente une surface d’erreurs exceptionnellement large. Un même chemin de code peut être correct comme fonction et comme flux d’octets, et produire malgré tout un fichier qu’un lecteur conforme rejette. Il peut aussi produire un fichier dont le rendu est subtilement erroné, mais uniquement à un saut de page. Teste le moteur à une seule granularité et tu n’obtiens de la confiance qu’à cette granularité, et à aucune autre.

Les textes normatifs sont clairs à ce sujet. Les techniques de conception de tests fondées sur la spécification et celles fondées sur la structure ne sont pas liées entre elles, et il est recommandé qu’une stratégie de test utilise plus d’un critère, avec au moins un critère fonctionnel et un critère structurel (ISO/IEC/IEEE 29119-4, Annex A). Un seul niveau n’est pas une version réduite d’une bonne stratégie. C’est une stratégie différente, et incomplète.

La version courte

Les tests de NextPDF sont organisés en cinq niveaux, de la base au sommet :

Unitaire — une classe ou une fonction, isolée. La grande base.
Intégration — des unités qui collaborent au-delà d’une frontière de module.
Structurel — le graphe d’objets PDF émis, la table de références croisées et le trailer sont bien formés et conformes.
Visuel — la page rendue correspond à une référence approuvée selon une tolérance déclarée.
Golden — des fixtures de bout en bout figées qui détectent toute dérive involontaire de la sortie finale. Le sommet.

Chaque niveau prouve quelque chose que le niveau en dessous ne peut pas prouver. Aucun d’eux n’est décoratif. La forme pyramidale exprime une quantité — beaucoup de tests unitaires peu coûteux, moins de tests de bout en bout, plus coûteux — et non une importance.

Comment NextPDF l’aborde

Les niveaux sont physiques, pas théoriques. La configuration PHPUnit du dépôt les déclare comme des suites de tests nommées, chacune associée à son propre répertoire. Un niveau est donc une cible vers laquelle tu peux diriger un exécuteur, pas une étiquette sur une diapositive. Les suites qu’un ingénieur expérimenté reconnaîtra incluent Unit, Integration, Golden, Snapshot, Reproducibility, Conformance, Standards et Performance, chacune avec son propre profil d’exécution (isolation, budget de temps et exécution ou non par défaut en intégration continue).

Cette séparation est délibérée. Le niveau de base, rapide (Unit), s’exécute à chaque modification avec un budget d’une seconde par test. Les niveaux plus lents et sensibles à l’environnement — rendu visuel, conformité complète, performance — sont optionnels ou nocturnes. Cela maintient le chemin courant rapide et déterministe sans renoncer aux vérifications plus poussées. Le typage strict sous-tend toute la pile. Le moteur est analysé avec Spec: PHPStan, Level 10 , le budget d’erreurs verrouillé à zéro, si bien qu’une grande catégorie de défauts n’atteint jamais le moindre test.

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

Les cinq niveaux de tests de NextPDF, de la base au sommet. Le niveau unitaire est la base large et rapide ; chaque niveau au-dessus prouve une propriété que le niveau en dessous ne peut pas prouver, jusqu'aux fixtures golden de bout en bout au sommet. La largeur n'est qu'une indication de quantité — elle ne classe pas l'importance.

La couverture n’est pas la confiance. Un pourcentage de couverture de lignes t’indique qu’une ligne a été exécutée pendant l’exécution ; il ne te dit pas que le test aurait remarqué si cette ligne était fautive. La pyramide existe parce que chaque niveau observe un type d’erreur différent — une fonction qui renvoie la mauvaise valeur, deux unités en désaccord à une frontière, un fichier structurellement invalide, une régression visuelle, une dérive au niveau de l’octet. C’est l’empilement des niveaux, et non la maximisation d’un chiffre unique, qui produit une sortie digne de confiance. Les tests de mutation, traités séparément, sont la façon dont NextPDF mesure si les tests de ces niveaux détectent réellement les défauts.

Ce que disent les preuves

Evidence: Test-backed Les cinq suites existent en tant que suites de tests PHPUnit déclarées dans la configuration du moteur, chacune liée à son propre répertoire et à son propre profil d’exécution. Le vocabulaire des niveaux utilisé sur cette page est le même que celui qu’emploie l’infrastructure de test.

Evidence: Standard-backed La raison d’avoir plus d’un niveau est ancrée dans Spec: ISO/IEC/IEEE 29119-4, Annex A  : les critères de couverture ne sont pas tous liés entre eux, et il est recommandé qu’une stratégie combine des techniques fonctionnelles et structurelles. Point crucial, la même annexe note que l’ordre de subsomption entre les critères de couverture ne donne aucune indication sur leur capacité à exposer les défauts — l’efficacité des tests (ISO/IEC/IEEE 29119-4, §C.2.4). « Plus de couverture » n’est pas la même chose que « de meilleurs tests ».

Evidence: Standard-backed Le choix des propriétés à prouver correspond aux caractéristiques de qualité produit de Spec: ISO/IEC 25010  : la correction fonctionnelle (unitaire, intégration), et les propriétés au niveau du fichier qui rendent un PDF réellement exploitable en aval (structurel, visuel, golden). Le modèle de qualité indique explicitement que différentes caractéristiques importent dans différents contextes d’utilisation.

Exemple pratique

Les niveaux sont adressables depuis les scripts du moteur lui-même. Une modification d’un seul formateur est vérifiée à la base. Une modification de la façade de document est vérifiée sur plusieurs niveaux :

<?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.

L’intérêt de l’exemple tient à la logique de routage, pas aux commandes. Le niveau que tu sollicites est choisi en fonction de ce que la modification peut casser. L’infrastructure fait de chaque niveau une cible à part entière, exécutable séparément.

Idée fausse répandue

La pyramide est souvent interprétée comme un classement — les tests unitaires en bas parce qu’ils comptent le moins, les tests de bout en bout en haut parce qu’ils comptent le plus (ou l’inverse). Ce n’est ni l’un ni l’autre. L’axe vertical représente grosso modo le coût et la quantité : beaucoup de tests unitaires rapides et peu coûteux formant une large base ; au-dessus, des tests progressivement moins nombreux, plus lents et de plus haute fidélité. Un test golden n’est pas « meilleur » qu’un test unitaire. Il détecte une défaillance différente, plus tard, à un coût plus élevé, et ferait un piètre substitut aux milliers de vérifications rapides situées en dessous de lui.

La seconde idée fausse est qu’un taux de couverture élevé signifie que la pyramide est solide. Ce n’est pas le cas. La couverture mesure l’exécution, pas la détection. Les normes refusent explicitement d’assimiler l’ordre de couverture à la capacité de détection des défauts. C’est précisément pour exposer cet écart que les tests de mutation existent.

Limites et frontières

Cette page décrit la forme et l’intention de la stratégie, pas ses résultats actuels. Les nombres de tests, les pourcentages de couverture et les scores de mutation sont délibérément absents ici. Ce sont des indicateurs de qualité vivants, générés à partir d’artefacts d’intégration continue. Les chiffres actuels sont publiés avec le build. Figés dans la prose, ils deviendraient discrètement obsolètes. Le seul chiffre indiqué — PHPStan niveau 10 — est un fait de configuration stable, vérifiable dans la configuration d’analyse statique du moteur, et non une mesure.

Les noms des niveaux forment un vocabulaire d’architecture stable. L’ensemble précis des suites et leurs profils d’exécution évolue avec le moteur et relève de la configuration de test, qui fait autorité si jamais elle est en désaccord avec cette explication. Cette page n’affirme aucun taux de réussite précis et n’établit aucune comparaison avec la stratégie de test d’une autre bibliothèque.

Documentation associée

Tests sur fichiers golden — comment le niveau au sommet fige la sortie de référence et reste honnête.
Les tests de mutation, expliqués — pourquoi un taux de couverture ne prouve pas que les tests de ces niveaux fonctionnent réellement.
Le typage strict, partout — comment PHPStan niveau 10 élimine une catégorie de défauts avant même l’exécution du moindre niveau.

Glossaire

Niveau de test — un palier de la stratégie qui prouve un type de propriété (par exemple, le comportement unitaire ou la validité structurelle). NextPDF en utilise cinq.
Test structurel — une vérification que le graphe d’objets du PDF émis, la table de références croisées et le trailer sont bien formés et conformes, par opposition à la simple vérification d’une valeur de retour.
Test visuel — une vérification qu’une page rendue correspond à une image de référence approuvée dans une tolérance déclarée.
Test golden — une vérification de bout en bout par rapport à une sortie de référence figée qui n’est jamais mise à jour automatiquement ; le contrat de « la sortie n’a pas changé ».
Efficacité des tests — la capacité d’un ensemble de tests à exposer les défauts, que la norme ISO/IEC/IEEE 29119-4 distingue de la couverture. Note sur l’acronyme : le MSI (Mutation Score Indicator) est défini sur la page tests de mutation.
PHPStan niveau 10 — le niveau d’analyse statique le plus strict ; NextPDF l’exécute avec le budget d’erreurs verrouillé à zéro.