Mettre en place PHPUnit pour un plugin WordPress avec wp scaffold plugin-tests

Écrire un plugin WordPress sans un seul test, cela fonctionne un moment. Puis vient le jour où une mise à jour de WordPress casse silencieusement une fonction que personne ne surveille, ou où un client signale un bug que vous auriez pu détecter en trente secondes avec la bonne suite de tests. PHPUnit reste, en 2020, l’outil de référence pour tester du code PHP, et WordPress fournit tout ce qu’il faut pour le brancher rapidement sur un plugin, à condition de connaître les bonnes commandes.

Cet article couvre la mise en place complète : générer le squelette avec WP-CLI, comprendre chaque fichier créé, installer l’environnement de test WordPress en local, et écrire un premier test qui a du sens. L’objectif n’est pas de vous vendre les tests automatisés en général, mais de vous donner un point de départ fonctionnel en moins d’une heure, sur un plugin réel.

Générer le squelette avec WP-CLI

Si vous avez WP-CLI installé, la commande wp scaffold plugin-tests fait le plus gros du travail. Placez-vous à la racine de votre installation WordPress et lancez :

wp scaffold plugin-tests mon-plugin

WP-CLI cherche le dossier wp-content/plugins/mon-plugin et y ajoute une arborescence standard :

• phpunit.xml.dist : la configuration de PHPUnit (bootstrap, suites, couleurs de sortie).
• tests/bootstrap.php : le fichier qui charge l’environnement de test WordPress avant chaque suite.
• tests/test-sample.php : un exemple de test basé sur WP_UnitTestCase.
• bin/install-wp-tests.sh : un script bash qui télécharge une copie de WordPress et crée une base de données de test.
• .travis.yml ou un fichier CI équivalent selon la version de WP-CLI utilisée.

Installer l’environnement de test avec install-wp-tests.sh

Le script bin/install-wp-tests.sh fait deux choses : il télécharge une copie propre du cœur de WordPress dans un répertoire temporaire, et il crée une base de données MySQL dédiée aux tests. Rendez-le exécutable puis lancez-le avec vos identifiants MySQL locaux :

chmod +x bin/install-wp-tests.sh
bash bin/install-wp-tests.sh wordpress_test root motdepasse localhost latest

Les paramètres, dans l’ordre, sont le nom de la base de test, l’utilisateur MySQL, le mot de passe, l’hôte, puis la version de WordPress à installer (latest convient dans la grande majorité des cas). Ce script crée réellement une base de données : utilisez un utilisateur MySQL qui a les droits nécessaires, et surtout jamais les identifiants de votre base de production. Une fois l’installation terminée, WordPress est copié dans /tmp/wordpress-tests-lib par défaut, avec un fichier wp-tests-config.php qui pointe vers votre base de test.

Comprendre le fichier bootstrap.php

Le fichier tests/bootstrap.php est le point d’entrée de toute la suite. Il définit la variable d’environnement pointant vers WordPress, puis charge votre plugin via le filtre muplugins_loaded avant d’appeler WP_PHPUNIT__DIR . '/includes/bootstrap.php' (ou l’équivalent selon votre version de scaffold) :

tests_add_filter( 'muplugins_loaded', function() {
    require dirname( __DIR__ ) . '/mon-plugin.php';
} );

require $_tests_dir . '/includes/bootstrap.php';

C’est cette mécanique qui garantit que votre plugin est chargé exactement comme il le serait sur un site réel, avec les hooks WordPress déjà en place, avant que le premier test ne s’exécute.

Écrire un premier test utile

Le fichier tests/test-sample.php généré par défaut est volontairement trivial. Remplacez-le par quelque chose qui teste réellement une fonction de votre plugin. Supposons que votre plugin expose une fonction mon_plugin_get_prix_ttc( $prix_ht, $taux_tva = 20 ) :

class Test_Calcul_Prix extends WP_UnitTestCase {

    public function test_calcule_le_prix_ttc_avec_taux_par_defaut() {
        $this->assertEquals( 120.0, mon_plugin_get_prix_ttc( 100 ) );
    }

    public function test_calcule_le_prix_ttc_avec_taux_personnalise() {
        $this->assertEquals( 105.5, mon_plugin_get_prix_ttc( 100, 5.5 ) );
    }
}

La classe WP_UnitTestCase hérite elle-même de PHPUnit\Framework\TestCase et ajoute des méthodes propres à WordPress, comme factory() pour générer des posts, des utilisateurs ou des termes de taxonomie à la volée. Nous y reviendrons dans un prochain article, mais gardez en tête que le test ci-dessus n’a besoin d’aucune fixture : il teste une pure fonction métier, ce qui en fait un bon premier test.

Lancer la suite

Une fois PHPUnit installé (via Composer, avec composer require --dev phpunit/phpunit, en veillant à choisir une version compatible avec votre PHP 7.x local), lancez simplement :

vendor/bin/phpunit

PHPUnit lit automatiquement phpunit.xml.dist à la racine du plugin, trouve le dossier tests, exécute le bootstrap puis chaque classe de test. Une sortie verte avec le nombre de tests et d’assertions passées confirme que tout fonctionne.

Les pièges classiques au démarrage

Quelques erreurs reviennent systématiquement chez les développeurs qui installent cette chaîne pour la première fois :

• Utiliser la base de données de production dans install-wp-tests.sh : chaque exécution de la suite vide et recrée les tables, ce qui serait catastrophique en prod.
• Oublier que svn doit être installé sur la machine : le script s’appuie dessus pour récupérer les fichiers de test du cœur WordPress.
• Lancer les tests avec un PHP différent de celui utilisé par votre hébergement, ce qui masque des incompatibilités qui n’apparaîtront qu’en production.
• Confondre wp-tests-config.php, propre à l’environnement de test, avec le wp-config.php du site réel.

Sur nos projets, la première chose que nous vérifions après un wp scaffold plugin-tests, c’est que la base de test porte un nom qui ne peut jamais être confondu avec une base de production, du type wordpress_test plutôt qu’un simple wordpress.

En résumé

En quelques minutes, wp scaffold plugin-tests pose les fondations d’une suite PHPUnit fonctionnelle pour un plugin WordPress : structure de fichiers, environnement de test isolé, et un premier test exécutable. La suite logique consiste à explorer les factories de WP_UnitTestCase pour tester des scénarios impliquant posts, utilisateurs et taxonomies, ce que nous détaillerons dans un prochain article. Pour l’instant, le plus important est de prendre l’habitude : un plugin sans tests aujourd’hui est un plugin qui coûtera plus cher à maintenir demain.