Annotations de test

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

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

Exemple :

/**
 * TEST: Basic database query test.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 5.5
 */

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

TEST

Il ne s'agit pas d'une annotation en fait. Elle définit seulement le titre du test qui est imprimé sur les échecs ou dans les journaux.

@skip

Le test est ignoré. C'est pratique pour désactiver temporairement un test.

@phpVersion

Le test est ignoré s'il n'est pas exécuté par la version PHP correspondante. Nous écrivons l'annotation comme @phpVersion [operator] version. Nous pouvons ne pas utiliser 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 ignoré si toutes les extensions PHP mentionnées ne sont pas chargées. Plusieurs extensions peuvent être écrites dans une seule annotation, ou nous pouvons utiliser l'annotation plusieurs fois.

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

@dataProvider

Cette annotation convient lorsque l'on veut exécuter le test plusieurs fois mais avec des données différentes. (A ne pas confondre avec l'annotation du même nom pour TestCase).

Nous écrivons l'annotation comme @dataProvider file.ini. Le chemin du fichier INI est relatif au fichier de test. Le test s'exécute autant de fois que le nombre de sections contenues dans le fichier INI. Supposons que 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écute trois fois et $args contiendra les valeurs des sections mysql, postgresql ou sqlite.

Il existe une autre variante lorsque nous écrivons des annotations avec un point d'interrogation comme @dataProvider? file.ini. Dans ce cas, le test est ignoré si le fichier INI n'existe pas.

Les possibilités d'annotation n'ont pas encore été toutes mentionnées. Nous pouvons écrire des conditions après le fichier INI. Le test s'exécute pour la section donnée seulement si toutes les conditions correspondent. Étendons 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 nous utiliserons l'annotation avec la condition :

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

Le test s'exécute une seule fois pour la section postgresql 9.1. Les autres sections ne correspondent pas aux conditions.

De même, nous pouvons passer le chemin d'un script PHP au lieu de l'INI. Il doit retourner un tableau ou un Traversable. Fichier databases.php:

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

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

@multiple

Nous l'écrivons comme @multiple N où N est un nombre entier. Le test s'exécute exactement N fois.

@testCase

L'annotation n'a pas de paramètres. Nous l'utilisons lorsque nous écrivons un test en tant que classes TestCase. Dans ce cas, l'exécuteur de test en 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 l'écrivons comme @exitCode N où N is the exit code of the test. For example if exit(10) est appelé dans le test, nous écrivons l'annotation comme @exitCode 10. Il est considéré comme un échec si le test se termine par un code différent. Le code de sortie 0 (zéro) est vérifié si nous omettons l'annotation

@httpCode

L'annotation est évaluée seulement si le binaire PHP est CGI. Sinon, elle est ignorée. Nous l'écrivons sous la forme @httpCode NNN où NNN est le code HTTP attendu. Le code HTTP 200 est vérifié si nous ne tenons pas compte de l'annotation. Si nous écrivons NNN comme une chaîne évaluée à zéro, par exemple any, le code HTTP n'est pas vérifié du tout.

@outputMatch a @outputMatchFile

Le comportement des annotations est cohérent avec les assertions Assert::match() et Assert::matchFile(). Mais le modèle est trouvé dans la sortie standard du test. Un cas d'utilisation approprié est lorsque nous supposons que le test se termine par une erreur fatale et que nous devons vérifier sa sortie.

@phpIni

Il définit les valeurs de configuration INI pour le test. Par exemple, nous l'écrivons comme @phpIni precision=20 et il fonctionne de la même manière que si nous passions la valeur de la ligne de commande par le paramètre -d precision=20.