# Nommer vos tests PHPUnit pour qu’ils documentent un comportement précis

> Un nom de test qui recopie le nom de la fonction testée ne dit rien du comportement vérifié. Une convention centrée sur le résultat attendu change tout à la lecture.

- Auteur : WordPress Développement
- Publié le : 2021-10-14
- Mis à jour le : 2021-10-14
- Catégorie : Tests
- URL : https://www.wpmoderne.fr/tests/nommer-tests-phpunit-comportement/

## L’essentiel

- Un nom de test doit décrire un comportement, pas une méthode
- La formule condition + résultat attendu couvre la majorité des cas
- Un nom trop générique masque en réalité plusieurs comportements distincts

Une suite de tests qui s'appelle `test_calculer()`, `test_calculer2()` et `test_calculer_encore()` ne raconte rien à quiconque l'ouvre pour la première fois. Elle oblige à lire le corps de chaque méthode pour comprendre ce qui distingue les trois cas, alors qu'un bon nom aurait pu épargner cette lecture.

Le nom d'une méthode de test est une documentation à part entière, souvent la première chose lue en cas d'échec dans un rapport de build. Ce billet propose une convention de nommage centrée sur le comportement attendu ; il ne traite ni la structure interne du test ni les fournisseurs de données (data providers), qui répondent à d'autres questions.

## Le problème du nom qui recopie la méthode testée

Nommer un test `test_calculer_remise()` semble naturel, mais ce nom ne dit rien de ce qui est vérifié précisément. Que se passe-t-il pour un client fidèle depuis un mois ? Depuis un an ? Avec un montant négatif ? Chacune de ces situations mérite son propre test, avec un nom qui l'identifie sans ambiguïté.

```
// Insuffisant : ne distingue aucun cas
public function test_calculer_remise() { /* ... */ }

// Explicite : condition + résultat attendu
public function test_remise_de_dix_pourcent_apres_six_mois_anciennete() { /* ... */ }
public function test_aucune_remise_avant_six_mois_anciennete() { /* ... */ }
public function test_remise_plafonnee_a_cinquante_euros_gros_montant() { /* ... */ }
```

## La formule condition plus résultat attendu

La plupart des noms de test peuvent suivre un gabarit simple : la condition testée, suivie du résultat attendu dans cette condition. Cette formule oblige à clarifier, avant même d'écrire le corps du test, ce qui est réellement vérifié :

- `test_[resultat_attendu]_[condition]()` ou l'inverse selon la lisibilité en français.
- Éviter les abréviations qui ne parlent qu'à l'auteur du test au moment où il l'écrit.
- Préférer une méthode longue mais explicite à une méthode courte mais opaque.

> L'essentiel à retenir : Un nom de test doit décrire un comportement, pas une méthode ; La formule condition + résultat attendu couvre la majorité des cas ; Un nom trop générique masque en réalité plusieurs comportements distincts

## Un nom générique cache souvent plusieurs comportements

Un symptôme fréquent d'un mauvais nommage : un test appelé `test_validation_formulaire()` qui, une fois ouvert, contient en réalité cinq assertions distinctes sur cinq champs différents. Ce test devrait être scindé en cinq méthodes, chacune nommée d'après le champ et la règle qu'elle vérifie :

```
public function test_email_invalide_rejete_par_validation() { /* ... */ }
public function test_telephone_manquant_rejete_par_validation() { /* ... */ }
public function test_code_postal_cinq_chiffres_accepte_par_validation() { /* ... */ }
```

Scinder ainsi n'ajoute pas de complexité réelle à la suite : chaque test reste court, et un échec pointe immédiatement vers le champ concerné, plutôt que de forcer une lecture du corps entier du test pour comprendre laquelle des cinq assertions a échoué.

## Le nom comme premier niveau de diagnostic

En intégration continue, la première information visible en cas d'échec est souvent le nom du test, avant même son message d'erreur. Un nom explicite permet de comprendre l'essentiel du problème sans ouvrir le rapport complet :

| Nom du test en échec | Ce qu'il indique immédiatement |
| --- | --- |
| test_aucune_remise_avant_six_mois_anciennete | La règle de seuil d'ancienneté est cassée |
| test_calculer_remise_2 | Rien, sans ouvrir le code du test |

## Une convention à documenter, pas à imposer sans explication

Comme toute convention d'équipe, celle-ci ne tient dans la durée que si elle est expliquée, pas seulement exigée en revue de code. Un exemple concret dans le guide de contribution du projet, montrant un nom avant et après réécriture, convainc plus efficacement qu'une règle énoncée sans illustration.

> Si le nom d'un test demande une phrase d'explication en revue de code, c'est le nom qu'il faut corriger, pas la personne qui pose la question.

## En résumé

Un nom de test centré sur le comportement attendu, plutôt que sur la méthode testée, transforme chaque échec en un message immédiatement compréhensible sans lecture du code. Cette convention, simple à adopter mais difficile à maintenir sans vigilance en revue, paie surtout dans les rapports d'intégration continue consultés rapidement par toute l'équipe.