assertFileEquals pour comparer un export CSV généré à un fichier de référence

Une boucle de comparaison ligne par ligne qui masque l’assertion réelle

Tester un export CSV en comparant chaque ligne à la main, dans une boucle qui ouvre le fichier généré et le fichier de référence en parallèle, fonctionne mais dilue la véritable assertion dans une logique de parcours qui n’a rien à voir avec le comportement testé. Cette boucle doit aussi gérer les cas limites : un fichier plus court ou plus long que l’autre, une ligne vide en fin de fichier, un encodage de fin de ligne différent selon la plateforme d’exécution du test.

assertFileEquals() remplace toute cette logique par une seule ligne, qui compare directement le contenu de deux fichiers :

public function test_export_correspond_au_fichier_de_reference() {
    $chemin_genere = $this->generer_export_csv( $commandes_de_test );

    $this->assertFileEquals(
        __DIR__ . '/fixtures/export-attendu.csv',
        $chemin_genere
    );
}

Le premier argument désigne le fichier de référence, le second le fichier produit par le code testé. En cas de différence, PHPUnit affiche un diff du contenu des deux fichiers, ce qui permet de localiser immédiatement la ligne ou la portion de contenu à l’origine de l’échec, sans avoir à ouvrir manuellement les deux fichiers côte à côte.

Le fichier golden : une référence versionnée, pas générée à la volée

Le fichier de référence, souvent appelé « golden file » dans le vocabulaire des tests, doit être versionné avec le code du projet, dans un dossier de fixtures dédié, et jamais régénéré automatiquement par le test lui-même. Un fichier golden généré à la volée par le même code que celui testé ne prouverait rien : il validerait uniquement que le code produit toujours la même sortie que lui-même, sans jamais vérifier que cette sortie correspond au format réellement attendu par le système qui consomme cet export ensuite.

tests/
  fixtures/
    export-attendu.csv
  ExportCsvTest.php

Modifier volontairement le format d’export impose donc de mettre à jour ce fichier golden manuellement, en vérifiant que le nouveau contenu correspond bien à ce qui est attendu, avant de le committer avec le reste du changement de code.

Un cas concret : détecter un changement d’encodage des accents

Un export CSV destiné à un logiciel de comptabilité tiers peut exiger un encodage précis, par exemple ISO-8859-1 plutôt qu’UTF-8, pour que les caractères accentués s’affichent correctement à la réouverture du fichier. Un changement accidentel d’encodage dans le code de génération, invisible à l’œil nu dans un éditeur qui convertit tout automatiquement à l’affichage, se traduit par une différence d’octets détectée immédiatement par assertFileEquals(), puisque l’assertion compare le contenu binaire des deux fichiers, pas seulement leur rendu textuel apparent :

public function test_export_conserve_lencodage_iso_8859_1() {
    $chemin_genere = $this->generer_export_comptable( $commandes_de_test );

    $this->assertFileEquals(
        __DIR__ . '/fixtures/export-comptable-attendu.csv',
        $chemin_genere
    );
}

Un fichier golden versionné transforme un format d’export implicite, connu seulement de la personne qui l’a écrit, en un contrat explicite que tout changement de code doit respecter ou mettre à jour consciemment.

Ce que l’assertion ne fait pas : un diagnostic ligne par ligne détaillé

assertFileEquals() signale qu’une différence existe et l’affiche sous forme de diff standard, mais elle ne fournit pas nativement un décompte du nombre de lignes divergentes ni une tolérance configurable sur certains champs, comme une date d’export qui varierait légitimement à chaque exécution. Pour un export qui contient une donnée volontairement variable, il faut soit neutraliser cette donnée avant la comparaison, par exemple en remplaçant la date par une valeur fixe dans les deux fichiers, soit se tourner vers une comparaison plus fine que le fichier entier, ligne concernée par ligne concernée.

• assertFileEquals compare le contenu binaire de deux fichiers en une seule assertion.
• Le fichier golden de référence doit être versionné et jamais régénéré par le test lui-même.
• Une donnée volontairement variable dans l’export doit être neutralisée avant la comparaison.

Conclusion : un test d’export centré sur le résultat, pas sur son parcours

Remplacer une boucle de comparaison manuelle par assertFileEquals() recentre le test sur ce qui compte réellement : le contenu final produit par l’export, comparé à une référence stable et versionnée. Cette approche gagne en clarté sur un format d’export riche, où une boucle manuelle aurait fini par reproduire, dans le test lui-même, une bonne partie de la logique du code qu’elle est censée vérifier.