Onboarding sur une suite de tests WordPress : l’essentiel en une journée

Un développeur qui rejoint l’équipe n’a pas besoin de connaître toute l’histoire de la suite de tests pour être productif : il a besoin d’un chemin balisé qui le rend autonome en une journée, quitte à approfondir les subtilités plus tard. Voici la checklist que nous transmettons à chaque nouvel arrivant, condensée pour tenir dans une matinée de prise en main suivie d’un après-midi de pratique encadrée.

1. Les cinq commandes qui couvrent 90 % des besoins quotidiens

# lancer toute la suite
vendor/bin/phpunit

# lancer un seul fichier
vendor/bin/phpunit tests/test-reservations.php

# lancer un seul test par son nom
vendor/bin/phpunit --filter test_reservation_refuse_date_passee

# lancer uniquement le groupe rapide, pour un retour en quelques secondes
vendor/bin/phpunit --group rapide

# régénérer la base de test si elle semble corrompue après une manipulation malheureuse
wp scaffold plugin-tests --dir=. # uniquement en cas de besoin de réinitialisation complète

Le premier après-midi consiste à faire écrire, encadré, un test simple sur une fonction déjà existante non couverte, en utilisant uniquement ces cinq commandes, sans jamais avoir besoin d’ouvrir la documentation complète de PHPUnit dès le premier jour.

2. Les conventions de nommage de l’équipe, pas celles de PHPUnit par défaut

• Un nom de méthode de test décrit un comportement en français, jamais en anglais générique : test_reservation_refuse_date_passee(), pas testCase1() ni test_it_works().
• Chaque classe de test hérite de WP_UnitTestCase sauf mention explicite justifiant l’usage de PHPUnit\Framework\TestCase pur (généralement une fonction sans aucune dépendance WordPress).
• Les fixtures partagées entre plusieurs tests vivent dans tests/fixtures/, jamais dupliquées dans chaque fichier de test.

3. Les trois pièges qu’on préfère montrer plutôt que laisser découvrir seul

Piège n° 1 : la fuite d’état entre tests. Un test qui modifie une option globale sans la restaurer dans tear_down() contamine les tests suivants, avec des échecs qui varient selon l’ordre d’exécution. On montre en direct l’exécution avec --order-by=random pour révéler ce genre de dépendance cachée avant qu’elle ne devienne un mystère à déboguer seul plus tard.

Piège n° 2 : tester l’implémentation plutôt que le comportement. Un test qui vérifie qu’une méthode privée précise a été appelée, plutôt que de vérifier le résultat observable, casse à chaque refactoring même quand le comportement reste correct. On montre un contre-exemple corrigé côte à côte pour rendre la différence tangible.

Piège n° 3 : confondre assertion faible et test qui protège vraiment. Un test qui se contente de $this->assertNotNull( $resultat ) passe même si le contenu du résultat est complètement faux. On insiste sur des assertions précises, assertSame plutôt que assertEquals quand le type compte, dès la première revue de code du nouvel arrivant.

4. Où trouver de l’aide sans déranger toute l’équipe

La règle qu’on transmet systématiquement : si un test échoue pour une raison qui semble n’avoir aucun rapport avec ton changement, regarde d’abord s’il passe seul avant de chercher le bug dans ton propre code. Neuf fois sur dix, c’est un test précédent qui a laissé une trace.

• Le fichier tests/README.md du projet recense les conventions spécifiques à ce dépôt précis, à lire avant toute question à l’équipe.
• Le canal de discussion dédié aux tests garde l’historique des pièges déjà rencontrés par d’autres, souvent la réponse existe déjà.
• Un binôme désigné pour la première semaine reste la ressource par défaut pour toute question bloquante de plus de quinze minutes.

5. L’objectif du premier jour, rien de plus

Ce billet ne traite pas de l’organisation du dossier de tests lui-même, une convention déjà établie et documentée séparément dans le projet. L’objectif du premier jour reste volontairement modeste : qu’un nouvel arrivant écrive un test correct, nommé selon les conventions de l’équipe, sans fuite d’état ni assertion faible, avant la fin de sa première journée. Le reste — factories avancées, mocks, tests d’intégration complexes — vient naturellement dans les semaines suivantes, porté par la pratique plutôt que par une documentation exhaustive lue d’un bloc.

En résumé

Un onboarding réussi sur une suite de tests ne se mesure pas à l’exhaustivité de ce qui est transmis le premier jour, mais à la vitesse à laquelle le nouvel arrivant devient autonome sur les cas courants. Concentrer la première journée sur cinq commandes, trois conventions et trois pièges connus donne de bien meilleurs résultats qu’une documentation complète que personne ne lit en entier avant d’en avoir vraiment besoin.