À combien de versions de retard une suite de tests peut-elle rester avant de devenir un vrai problème ? La question s’est posée concrètement sur un projet resté bloqué sur PHPUnit 9 depuis près de deux ans, par prudence plus que par nécessité réelle, pendant que l’écosystème avait déjà basculé vers la version 10 puis 11. Le rattrapage, une fois entamé, s’est révélé moins pénible que redouté, mais il a fallu défaire quelques habitudes bien ancrées.
PHPUnit 11 poursuit une tendance amorcée dès la version 10 : le remplacement progressif des annotations de docblock, ce commentaire spécial placé au-dessus d’une méthode de test, par des attributs PHP natifs, cette syntaxe entre crochets introduite en PHP 8. Pour un projet WordPress, cette évolution touche directement les tests écrits avec WP_UnitTestCase.
Des annotations aux attributs : ce qui change concrètement
Une annotation comme @dataProvider, placée en commentaire au-dessus d’une méthode de test, fonctionnait par simple convention de nommage, sans aucune vérification par l’interpréteur PHP lui-même. À partir de PHPUnit 10, et de façon plus marquée en version 11, l’équivalent recommandé devient un attribut natif, vérifié structurellement par le langage :
// Ancienne syntaxe par annotation, encore supportée mais dépréciée
/**
* @dataProvider fournisseur_de_tarifs
*/
public function test_calcul_remise( $tarif, $attendu ) { /* ... */ }
// Nouvelle syntaxe par attribut PHP natif
#[DataProvider('fournisseur_de_tarifs')]
public function test_calcul_remise( $tarif, $attendu ) { /* ... */ }Les anciennes annotations continuent de fonctionner en PHPUnit 11 pour la plupart des cas courants, mais génèrent des avertissements de dépréciation de plus en plus visibles, un signal clair que leur suppression complète est désormais planifiée dans une future version majeure.
WP_UnitTestCase reste utilisable, grâce aux polyfills
La bonne nouvelle pour un projet WordPress : la classe WP_UnitTestCase, fournie par la suite de tests officielle, continue de fonctionner normalement avec PHPUnit 11, à condition d’utiliser une version à jour des Yoast PHPUnit Polyfills, qui absorbent les différences d’API entre les versions majeures successives de PHPUnit. Sur les trois projets migrés pour vérifier ce point, aucun n’a nécessité de modification du bootstrap de tests lui-même au-delà de la mise à jour de cette dépendance.
Ce qui bloque encore certaines migrations
Le vrai frein, sur les projets où la migration a traîné, ne vient presque jamais du cœur WordPress ou de sa suite de tests officielle, mais des extensions tierces de tests elles-mêmes, en particulier certaines bibliothèques de mocks anciennes qui étendent directement des classes internes de PHPUnit désormais supprimées ou marquées final. Sur un projet, une bibliothèque de mock HTTP maintenue de façon irrégulière a bloqué la montée de version pendant plusieurs semaines, le temps qu’une version compatible soit publiée par son mainteneur.
# Vérifier les dépendances de tests qui pourraient bloquer la migration
composer why-not phpunit/phpunit ^11.0Attributs utiles à connaître au-delà du DataProvider
PHPUnit 11 généralise l’usage des attributs à d’autres cas fréquents en tests WordPress, avec un gain de lisibilité réel une fois l’habitude prise :
#[Test], qui permet de nommer une méthode de test sans imposer le préfixetest_, utile pour des noms de méthode plus proches d’une phrase lisible#[Group('rest-api')], remplaçant l’ancienne annotation@group, pour filtrer l’exécution d’un sous-ensemble de tests en ligne de commande#[Depends('test_creation_produit')], qui exprime explicitement qu’un test dépend du résultat d’un autre, remplaçant@depends
Une migration progressive, méthode recommandée
Plutôt que de réécrire toutes les annotations d’un coup, ce qui produit une pull request massive et difficile à relire, on a procédé fichier par fichier de test, en migrant les annotations vers les attributs uniquement lors des modifications déjà prévues sur ces fichiers pour d’autres raisons. Cette approche progressive a permis de convertir plus de 80 % de la suite en environ deux mois, sans jamais bloquer le développement courant sur un chantier de migration dédié.
Une syntaxe dépréciée qui fonctionne encore n’est pas une urgence, mais elle devient un coût caché à chaque nouvelle version majeure repoussée : mieux vaut migrer au fil de l’eau que de réserver un futur grand chantier qu’on ne trouvera jamais le temps de faire.
Vérifier la matrice complète avant de généraliser
Comme pour toute montée de version de l’outillage de tests, on rejoue systématiquement la matrice complète de versions PHP et WordPress ciblées par le projet avant de considérer la migration terminée, l’expérience ayant montré à plusieurs reprises qu’une combinaison précise de versions révèle des comportements que l’exécution locale unique ne détecte jamais.
En résumé
La migration vers PHPUnit 11 sur un projet WordPress reste globalement fluide grâce aux polyfills communautaires qui maintiennent la compatibilité de WP_UnitTestCase. Le principal effort porte sur le remplacement progressif des annotations par des attributs natifs, un chantier qui peut s’étaler naturellement au fil des modifications courantes plutôt que de nécessiter une opération dédiée. Les vrais blocages viennent presque toujours des dépendances tierces de tests, à vérifier en priorité avant de lancer la migration sur un projet qui en dépend fortement.
