Un export comptable qui change d’un espace ou d’une virgule décimale ne provoque presque jamais d’erreur visible côté WordPress. Il provoque en revanche un rejet silencieux côté Xero ou QuickBooks, découvert seulement quand le comptable signale que les écritures du mois ne s’importent plus. C’est ce décalage de responsabilité qui a motivé la mise en place de tests golden files sur ce module d’export.
Un golden file est un fichier de référence, versionné avec le code, qui représente la sortie attendue exacte d’une fonction. Le test ne vérifie pas une propriété abstraite du résultat, il compare caractère pour caractère la sortie produite avec ce fichier de référence.
Choisir ce qui mérite un golden file
Tous les exports ne s’y prêtent pas : un export contenant une date de génération ou un identifiant aléatoire ne peut pas être comparé littéralement sans neutraliser ces champs au préalable. Le module d’export comptable, lui, produit un CSV entièrement déterministe à partir d’un jeu de commandes fixé — un candidat idéal.
tests/fixtures/export-xero/
├── commandes-source.json
└── attendu.csv
Le fichier commandes-source.json contient trois commandes WooCommerce avec des cas volontairement variés : une commande avec remise, une avec taxe à taux réduit, une remboursée partiellement.
Comparer littéralement plutôt qu’assertion par assertion
Le test charge le fichier source, exécute le générateur d’export, puis compare le résultat au fichier golden avec assertStringEqualsFile(), plutôt que de vérifier colonne par colonne à coups d’assertions séparées.
public function test_export_xero_correspond_au_golden_file() {
$commandes = $this->charger_commandes( __DIR__ . '/fixtures/export-xero/commandes-source.json' );
$csv = ( new ExportXero() )->generer( $commandes );
$this->assertStringEqualsFile(
__DIR__ . '/fixtures/export-xero/attendu.csv',
$csv
);
}
Cette approche a un avantage direct : le diff affiché en cas d’échec montre exactement la ligne et la colonne qui divergent, sans qu’il soit nécessaire d’écrire une assertion dédiée pour chaque champ du format Xero.
Valider explicitement chaque changement volontaire
Quand le format d’export évolue réellement — un nouveau champ exigé par une mise à jour de l’API Xero, par exemple — le golden file doit être régénéré et relu à la main avant d’être commité. Ce point de friction est volontaire : il oblige à une revue humaine de chaque changement de format, plutôt qu’une mise à jour automatique aveugle.
- Script dédié pour régénérer les golden files sur demande explicite
- Revue obligatoire du diff Git avant tout commit du fichier de référence
- Aucune régénération automatique déclenchée par la CI
Étendre la même approche à QuickBooks
Le format QuickBooks, structurellement différent — un fichier IIF plutôt qu’un CSV standard — a suivi le même principe avec son propre dossier de fixtures et son propre golden file. Les deux formats partagent la même source de commandes, ce qui garantit une cohérence des cas de test entre les deux exports.
Un golden file ne remplace pas la compréhension du format cible, mais il garantit qu’une modification involontaire du générateur ne passe jamais inaperçue.
Ce que ces tests ne couvrent pas
La synchronisation en temps réel avec l’API Xero, l’authentification OAuth et la gestion des jetons d’accès font l’objet d’une suite distincte, avec des mocks HTTP dédiés. Les golden files ne concernent que la génération du format de fichier, indépendamment de son transport vers le logiciel comptable.
En résumé
Depuis la mise en place de ces golden files, deux régressions de format ont été détectées avant mise en production : un changement d’encodage accidentel introduit par une bibliothèque tierce, et un arrondi de taxe qui différait d’un centime sur certaines commandes. Toutes deux auraient été invisibles avec des assertions classiques, et bien réelles pour le comptable qui reçoit le fichier.
