« Class ‘WP_UnitTestCase’ not found » : la cause la plus fréquente

Error: Class 'WP_UnitTestCase' not found. Ce message apparaît en général dès la première exécution de la suite, avant même qu’un seul test ne tourne réellement, et il déroute autant les débutants que les développeurs expérimentés qui changent de machine.

La bonne nouvelle : dans l’immense majorité des cas, la cause est unique et se corrige en quelques minutes. Ce billet ne revient pas sur la configuration initiale de wp scaffold plugin-tests, déjà traitée ailleurs, mais sur le diagnostic de cette erreur précise une fois l’environnement censé être en place.

Comprendre d’où vient réellement la classe

WP_UnitTestCase n’est pas une classe du cœur de WordPress : elle appartient à la bibliothèque de test wordpress-tests-lib, un dépôt séparé cloné à côté de l’installation WordPress. Elle n’est chargée que si le fichier bootstrap.php de votre suite l’inclut explicitement, généralement via tests/phpunit/includes/bootstrap.php.

Si PHPUnit ne trouve pas cette classe, ce n’est donc jamais un problème de syntaxe dans votre test : c’est que le fichier qui la déclare n’a tout simplement jamais été chargé.

Vérifier que phpunit.xml pointe vers le bon bootstrap

La première chose à contrôler est l’attribut bootstrap de la balise racine du fichier de configuration.

<phpunit bootstrap="tests/bootstrap.php">
    <testsuites>
        <testsuite name="unit">
            <directory>./tests/</directory>
        </testsuite>
    </testsuites>
</phpunit>

Un chemin relatif incorrect, ou un fichier bootstrap.php renommé lors d’un refactoring, suffit à rendre cette ligne inopérante sans que PHPUnit ne signale d’erreur explicite au démarrage.

Contrôler la variable WP_TESTS_DIR

Le fichier bootstrap.php lui-même dépend d’une variable d’environnement, WP_TESTS_DIR, qui indique où se trouve wordpress-tests-lib. Si cette variable est absente ou pointe vers un dossier vide, l’inclusion de functions.php échoue silencieusement, et avec elle le chargement de WP_UnitTestCase.

• Vérifier avec echo $WP_TESTS_DIR dans le terminal utilisé pour lancer les tests
• Confirmer que le dossier contient bien un fichier includes/functions.php
• Sur CI, s’assurer que cette variable est définie dans le même job que celui qui exécute PHPUnit, pas seulement dans une étape précédente

Le piège classique du changement de machine

Ce scénario revient souvent après une réinstallation d’environnement local ou un changement de conteneur Docker : le script d’installation de wordpress-tests-lib a tourné une fois, sur l’ancienne machine, et n’a jamais été rejoué sur la nouvelle.

Reproduire l’installation en une commande

Le script officiel install-wp-tests.sh, fourni par le cœur de WordPress, télécharge et configure tout l’environnement en une seule commande.

bash bin/install-wp-tests.sh wordpress_test root '' localhost latest

Si cette commande échoue elle-même, le message d’erreur qu’elle affiche est bien plus précis que « class not found » : il indique généralement un problème de connexion à la base de données ou un dossier de destination sans droits d’écriture.

Distinguer ce cas d’une vraie erreur d’autoloader Composer

Un second cas, plus rare, concerne les projets qui chargent leurs propres classes via Composer mais oublient d’inclure l’autoloader dans le bootstrap. Le symptôme est identique en apparence, mais la cause est différente : ici, ce sont vos propres classes qui manquent, pas WP_UnitTestCase.

1. Vérifier que require_once __DIR__ . '/../vendor/autoload.php'; figure bien dans le bootstrap
2. Confirmer que composer install a été exécuté avant le lancement des tests
3. Ne pas confondre cette erreur avec celle liée à wordpress-tests-lib, le correctif est différent

Avant de creuser plus loin, un réflexe simple : afficher la valeur de WP_TESTS_DIR en tout premier dans le bootstrap, avant même l’inclusion de functions.php. Cette seule ligne de débogage résout neuf cas sur dix.

En résumé

« Class WP_UnitTestCase not found » n’est presque jamais un problème de code de test : c’est un problème d’environnement, le plus souvent un chemin de bootstrap incorrect ou une variable WP_TESTS_DIR mal définie. Vérifier ces deux points avant toute autre piste fait gagner un temps précieux sur ce diagnostic classique.