Annotations de test
*******************

.[perex]
Les annotations déterminent comment les tests seront traités par le [gestionnaire de tests en ligne de commande |running-tests]. 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 :

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

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


TEST .[filter]
--------------
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 .[filter]
---------------
Le test est ignoré. C'est pratique pour désactiver temporairement un test.


@phpVersion .[filter]
---------------------
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 :

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


@phpExtension .[filter]
-----------------------
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.

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


@dataProvider .[filter]
-----------------------
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 |TestCase#dataProvider]).

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`:

```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 :

```php
/**
 * @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 :

```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 :

```php
/**
 * @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`:

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

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


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


@testCase .[filter]
-------------------
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 .[filter]
-------------------
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 .[filter]
-------------------
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 .[filter]
-----------------------------------------
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 .[filter]
-----------------
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`.