Annotations de test

Les annotations déterminent comment les tests seront traités par le lanceur de tests depuis la ligne de commande. Elles sont écrites au début du fichier de test.

Les annotations ne tiennent pas compte de la casse. Elles n'ont également aucun effet si le test est exécuté manuellement comme un script PHP ordinaire.

Exemple :

/**
 * TEST: Test de requête de base de données de base.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 5.5
 */

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

TEST

Ce n'est en fait pas une annotation, elle détermine seulement le titre du test, qui est affiché en cas d'échec ou dans le journal.

@skip

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

@phpVersion

Le test est sauté s'il n'est pas exécuté avec la version PHP correspondante. Nous écrivons l'annotation comme @phpVersion [opérateur] version. Nous pouvons omettre l'opérateur, la valeur par défaut est >=. Exemples :

/**
 * @phpVersion 5.3.3
 * @phpVersion < 5.5
 * @phpVersion != 5.4.5
 */

@phpExtension

Le test est sauté si toutes les extensions PHP spécifiées ne sont pas chargées. Nous pouvons spécifier plusieurs extensions dans une seule annotation, ou l'utiliser plusieurs fois.

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

@dataProvider

Si nous voulons exécuter le fichier de test plusieurs fois, mais avec des données d'entrée différentes, cette annotation est utile. (Ne pas confondre avec l'annotation du même nom pour TestCase.)

Nous écrivons comme @dataProvider file.ini, le chemin vers le 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 dans le même répertoire, le test database.phpt :

/**
 * @dataProvider databases.ini
 */

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

Le test sera exécuté trois fois et $args contiendra toujours les valeurs de la section mysql, postgresql ou sqlite.

Il existe une autre variante où nous écrivons l'annotation avec un point d'interrogation comme @dataProvider? file.ini. Dans ce cas, le test est sauté si le fichier INI n'existe pas.

Les possibilités de l'annotation ne s'arrêtent pas là. Après le nom du fichier INI, nous pouvons spécifier des conditions sous lesquelles le test sera exécuté pour la section donnée. Élargissons 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 sera exécuté une seule fois et ce, pour la section postgresql 9.1. Les autres sections ne passeront pas le filtre de la condition.

De même, au lieu d'un fichier INI, nous pouvons faire référence à un script PHP. Celui-ci doit retourner un tableau ou un Traversable. Fichier databases.php :

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

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

@multiple

Nous écrivons comme @multiple N, où N est un entier. Le test sera exécuté exactement N fois.

@testCase

L'annotation n'a pas de paramètres. Nous l'utilisons si nous écrivons les tests comme des classes TestCase. Dans ce cas, le lanceur de tests depuis la ligne de commande exécutera les méthodes individuelles dans des processus séparés et en parallèle dans plusieurs threads. Cela peut accélérer considérablement l'ensemble du processus de test.

@exitCode

Nous écrivons comme @exitCode N, où N est le code de retour du test exécuté. Si, par exemple, exit(10) est appelé dans le test, nous écrivons l'annotation comme @exitCode 10 et si le test se termine avec un code différent, cela est considéré comme un échec. Si nous n'indiquons pas l'annotation, le code de retour 0 (zéro) est vérifié.

@httpCode

L'annotation ne s'applique que si le binaire PHP est CGI. Sinon, elle est ignorée. Nous écrivons comme @httpCode NNN où NNN est le code HTTP attendu. Si nous n'indiquons pas l'annotation, le code HTTP 200 est vérifié. Si NNN est écrit comme une chaîne évaluée à zéro, par exemple any, le code HTTP n'est pas vérifié.

@outputMatch et @outputMatchFile

La fonction des annotations est identique aux assertions Assert::match() et Assert::matchFile(). Le modèle (pattern) est cependant recherché dans le texte que le test a envoyé sur sa sortie standard. Elle trouve son utilité si nous supposons que le test se terminera par une erreur fatale et que nous devons vérifier sa sortie.

@phpIni

Définit les valeurs INI de configuration pour le test. Nous écrivons par exemple comme @phpIni precision=20 et cela fonctionne de la même manière que si nous avions entré la valeur depuis la ligne de commande via le paramètre -d precision=20.