Annotations de test

Les annotations déterminent la façon dont les tests seront traités par le lanceur de tests en ligne de commande. Elles s'écrivent au début du fichier de test.

Les annotations sont insensibles à la casse. Elles n'ont par ailleurs aucun effet si le test est lancé manuellement comme un simple script PHP.

Exemple :

/**
 * TEST: Test de base d'une requête en base de données.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 8.4
 */

require __DIR__ . '/../bootstrap.php';

TEST

Ce n'est en fait pas une annotation. Elle indique simplement le titre du test, affiché en cas d'échec ou dans les journaux.

@skip

Le test est ignoré. Utile pour désactiver temporairement des tests.

@phpVersion

Le test est ignoré s'il n'est pas exécuté avec la version de PHP correspondante. Écrivez l'annotation sous la forme @phpVersion [opérateur] version. L'opérateur peut être omis, la valeur par défaut est >=. Exemples :

/**
 * @phpVersion 8.1
 * @phpVersion < 8.4
 * @phpVersion != 8.2.5
 */

@phpExtension

Le test est ignoré si toutes les extensions PHP indiquées ne sont pas chargées. Plusieurs extensions peuvent être énumérées dans une seule annotation, ou l'annotation peut être utilisée plusieurs fois.

/**
 * @phpExtension pdo, pdo_pgsql, pdo_mysql
 * @phpExtension json
 */

@dataProvider

Cette annotation est utile lorsque vous voulez exécuter le fichier de test plusieurs fois avec des données d'entrée différentes. (Ne la confondez pas avec l'annotation du même nom pour TestCase.)

Écrivez-la sous la forme @dataProvider fichier.ini. Le chemin du fichier est relatif au fichier de test. Le test sera exécuté autant de fois qu'il y a de sections dans le fichier INI. Supposons le fichier INI databases.ini :

[mysql]
dsn = "mysql:host=127.0.0.1"
user = root
password = ******

[postgresql]
dsn = "pgsql:host=127.0.0.1;dbname=test"
user = postgres
password = ******

[sqlite]
dsn = "sqlite::memory:"

et le fichier database.phpt dans le même répertoire :

/**
 * @dataProvider databases.ini
 */

$args = Tester\Environment::loadData();

Le test s'exécutera trois fois et $args contiendra respectivement les valeurs des sections mysql, postgresql ou sqlite.

Il existe une autre variante, où vous écrivez l'annotation avec un point d'interrogation : @dataProvider? fichier.ini. Dans ce cas, le test est ignoré si le fichier INI n'existe pas.

Les possibilités de cette annotation ne s'arrêtent pas là. Vous pouvez indiquer, après le nom du fichier INI, des conditions déterminant si le test s'exécute pour une section donnée. Étoffons le fichier INI :

[mysql]
dsn = "mysql:host=127.0.0.1"
user = root
password = ******

[postgresql 8.4]
dsn = "pgsql:host=127.0.0.1;dbname=test"
user = postgres
password = ******

[postgresql 9.1]
dsn = "pgsql:host=127.0.0.1;dbname=test;port=5433"
user = postgres
password = ******

[sqlite]
dsn = "sqlite::memory:"

et utilisons l'annotation avec une condition :

/**
 * @dataProvider  databases.ini  postgresql, >=9.0
 */

Le test ne s'exécutera qu'une seule fois, pour la section postgresql 9.1. Les autres sections ne satisfont pas le filtre de la condition.

De la même façon, au lieu d'un fichier INI, vous pouvez référencer un script PHP. Il doit renvoyer un tableau ou un objet Traversable. Fichier databases.php :

return [
	'postgresql 8.4' => [
		'dsn' => '...',
		'user' => '...',
	],

	'postgresql 9.1' => [
		'dsn' => '...',
		'user' => '...',
	],
];

@multiple

Écrivez-la sous la forme @multiple N, où N est un entier. Le test s'exécutera exactement N fois.

@testCase

Cette annotation n'a pas de paramètres. Utilisez-la lorsque vous écrivez les tests sous forme de classes TestCase. Dans ce cas, le lanceur de tests en ligne de commande exécutera les différentes méthodes dans des processus distincts et en parallèle, sur plusieurs threads. Cela peut accélérer nettement l'ensemble du processus de test.

@exitCode

Écrivez-la sous la forme @exitCode N, où N est le code de sortie attendu du test. Par exemple, si exit(10) est appelé dans le test, écrivez l'annotation @exitCode 10. Si le test se termine avec un autre code, il est considéré comme échoué. Si l'annotation est omise, c'est un code de sortie 0 (zéro) qui est vérifié.

@httpCode

Cette annotation ne s'applique que si le binaire PHP est en CGI ; sinon elle est ignorée. Écrivez-la sous la forme @httpCode NNN, où NNN est le code HTTP attendu. Si l'annotation est omise, c'est un code HTTP 200 qui est vérifié. Si NNN est écrit sous forme de chaîne s'évaluant à zéro (par exemple any), le code HTTP n'est pas contrôlé.

@outputMatch et @outputMatchFile

La fonction de ces annotations est identique à celle des assertions Assert::match() et Assert::matchFile(). Le motif est cependant recherché dans le texte que le test a envoyé sur sa sortie standard. C'est utile lorsque vous attendez qu'un test se termine par une erreur fatale et que vous devez en vérifier la sortie.

@phpIni

Définit des valeurs de configuration INI pour le test. Écrivez-la par exemple @phpIni precision=20. Cela fonctionne de la même façon que si vous indiquiez la valeur en ligne de commande avec le paramètre -d precision=20.