PHPUnit 10 : passer des annotations aux attributs DataProvider sans tout casser

« PHPUnit 10 est sorti début février 2023, avec un changement structurel qui touche directement les fournisseurs de données : la documentation officielle de PHPUnit recommande désormais l’attribut #[DataProvider] plutôt que l’annotation docblock @dataProvider, même si cette dernière reste encore lue par le framework. »

Pour une équipe qui maintient plusieurs centaines de tests écrits avec l’ancienne syntaxe, la question n’est pas de savoir s’il faut migrer, mais comment le faire sans provoquer une avalanche d’échecs le jour où la version de PHPUnit est mise à jour dans la CI.

Ce que PHPUnit 10 change concrètement

PHPUnit 10 relève l’exigence minimale à PHP 8.1, ce qui rend les attributs natifs disponibles pour l’ensemble du code de test. Le framework continue d’interpréter les annotations docblock existantes pour ne pas casser les suites migrées progressivement, mais la documentation officielle présente désormais les attributs comme la forme de référence, notamment pour #[DataProvider], #[Test], #[Group] et #[Depends].

La différence n’est pas seulement esthétique : un attribut est vérifié par l’analyseur syntaxique de PHP au chargement du fichier, alors qu’une annotation docblock reste une simple chaîne de caractères analysée par PHPUnit lui-même au moment de l’exécution. Une faute de frappe dans le nom d’une méthode de fournisseur de données référencée par attribut est repérable plus tôt par l’outillage (IDE, analyse statique) qu’une faute équivalente dans un commentaire.

La conversion, méthode par méthode

Voici la même méthode de test, avant puis après migration :

// Avant : annotation docblock
/**
 * @dataProvider fournisseurDePrix
 */
public function test_calcule_la_remise(float $prix, float $attendu): void
{
    $this->assertSame($attendu, calculerRemise($prix));
}

public function fournisseurDePrix(): array
{
    return [
        [100.0, 90.0],
        [50.0, 45.0],
    ];
}

// Après : attribut natif PHP 8.1+
use PHPUnit\Framework\Attributes\DataProvider;

#[DataProvider('fournisseurDePrix')]
public function test_calcule_la_remise(float $prix, float $attendu): void
{
    $this->assertSame($attendu, calculerRemise($prix));
}

public static function fournisseurDePrix(): array
{
    return [
        [100.0, 90.0],
        [50.0, 45.0],
    ];
}

Le détail qui casse le plus de suites lors de cette migration n’est pas la syntaxe de l’attribut lui-même, mais une exigence annexe : PHPUnit 10 impose que la méthode de fournisseur de données soit statique. Une méthode d’instance oubliée en public function plutôt qu’en public static function continue de fonctionner avec l’ancienne annotation, mais échoue avec l’attribut natif.

Une migration progressive plutôt qu’un big bang

1. Passer d’abord PHPUnit en version 9.6, qui accepte déjà à la fois les annotations et les attributs, pour valider la compatibilité du reste de la suite sans changer la syntaxe des tests.
2. Convertir les fournisseurs de données classe par classe, en commençant par celles qui ont le moins de dépendances croisées, et en rendant chaque méthode de fournisseur statique au passage.
3. Ne monter vers PHPUnit 10 qu’une fois que l’ensemble des méthodes de fournisseurs de données a été rendu statique, attribut ou pas.
4. Ajouter yoast/phpunit-polyfills comme dépendance de développement si le projet doit encore exécuter la même base de tests sous plusieurs versions majeures de PHPUnit en parallèle, ce qui est fréquent dans un contexte WordPress où le cœur impose parfois une version différente de celle du projet applicatif.

Ce qui ne change pas

La configuration XML de PHPUnit (fichier phpunit.xml) n’est pas concernée par cette migration : les balises <testsuite>, les filtres par groupe ou les variables d’environnement définies dans ce fichier continuent de fonctionner à l’identique, que les tests utilisent des annotations ou des attributs. Ce sujet mérite un traitement séparé.

Vérifier la migration avant de basculer la CI

Avant de changer la version de PHPUnit dans le pipeline d’intégration continue, il est prudent d’exécuter la suite localement avec les deux versions installées côte à côte (dans deux environnements distincts), en comparant le nombre de tests exécutés et le nombre d’assertions. Un écart, même faible, signale presque toujours une méthode de fournisseur de données oubliée en instance plutôt qu’en statique, ou un attribut mal orthographié qui fait silencieusement disparaître un test de la liste.

En résumé

La migration des annotations docblock vers les attributs #[DataProvider] de PHPUnit 10 se prépare avant la montée de version elle-même, en rendant statiques les méthodes de fournisseurs de données pendant que l’ancienne syntaxe fonctionne encore. Ce détail, souvent négligé, explique la grande majorité des échecs rencontrés lors de cette transition.