Quelle convention de nommage de méthode de test survit quand deux équipes qui travaillaient jusque-là sur des dépôts séparés se retrouvent à contribuer au même projet WordPress ? La première équipe nommait ses méthodes selon le schéma classique testSommeCalculeCorrectement(), hérité directement des conventions PHPUnit historiques. La seconde préférait une forme descriptive proche du comportement attendu, du type ilRetourneZeroQuandLePanierEstVide().
Aucune des deux conventions n’est en soi défaillante : PHPUnit exécute l’une comme l’autre sans distinction. Le problème apparaît au moment de la fusion des deux bases de code, quand 340 méthodes de test cohabitent soudain dans le même dépôt, rendant la navigation incohérente pour quiconque n’appartient pas à l’équipe d’origine du fichier consulté.
Ce que chaque convention apporte réellement
Le style testXxx a l’avantage de la reconnaissance immédiate : n’importe quel développeur ayant déjà touché à PHPUnit identifie en un coup d’œil qu’il s’agit d’une méthode de test, même en dehors d’un contexte de classe héritant de PHPUnit\Framework\TestCase. Son inconvénient : le nom décrit souvent l’action testée, rarement le résultat attendu, ce qui oblige à ouvrir le corps de la méthode pour comprendre ce qu’elle vérifie exactement.
Le style descriptif, à l’inverse, rend le comportement lisible dès la liste des méthodes, particulièrement utile dans un rapport de test qui échoue : un message d’échec du type ilRetourneZeroQuandLePanierEstVide renseigne immédiatement sur l’intention, sans consulter le code source.
Le critère qui a permis de trancher
Plutôt que d’imposer une préférence, l’équipe a organisé une revue courte autour d’un critère unique : quelle convention est la plus utile au moment précis où un test échoue en CI, généralement lu par une personne pressée qui n’a pas écrit le test ? La réponse a penché vers la forme descriptive, à condition de l’encadrer par une règle stricte : commencer systématiquement par un verbe à la troisième personne du singulier, et jamais nommer une méthode d’après l’implémentation interne testée.
// Retenu
public function ilLeveUneExceptionSiLeCodePromoEstExpire(): void { /* ... */ }
// Écarté (nomme l'implémentation, pas le comportement)
public function testAppelleValidateCodePromoMethod(): void { /* ... */ }
Ce que la règle ne tranchait pas encore
Restait la question des tests couvrant plusieurs comportements dans une même méthode, fréquents dans l’ancien dépôt de la première équipe. La règle adoptée impose désormais une méthode par comportement observable, quitte à multiplier les méthodes courtes plutôt que d’entasser plusieurs assertions indépendantes dans une seule.
Migrer sans tout renommer d’un coup
Renommer 340 méthodes en une seule journée aurait produit une revue de code illisible et un risque élevé d’erreur de copier-coller. La migration retenue suit une règle simple : tout fichier de test modifié pour une autre raison (correction de bug, ajout de scénario) voit ses méthodes renommées à cette occasion, jamais en dehors d’un changement déjà justifié.
- Aucun renommage isolé, sans changement fonctionnel associé, pour limiter le bruit dans l’historique Git.
- Un court guide de nommage, versionné dans le dépôt, sert de référence lors des revues de contribution.
- La convention historique reste tolérée dans les fichiers non encore migrés, sans obligation de rattrapage forcé.
Un nom de méthode de test qui se lit comme une phrase économise systématiquement une lecture du corps de la méthode.
En résumé
Il n’existe pas de convention de nommage de test universellement supérieure, seulement des critères de choix qui doivent rester explicites plutôt qu’hérités d’une habitude. Ici, la lisibilité au moment de l’échec en CI a fait pencher la balance vers le style descriptif, appliqué progressivement au fil des modifications plutôt qu’imposé par un renommage massif des 340 méthodes existantes.
