Annotazioni del test
********************

.[perex]
Le annotazioni determinano il modo in cui i test saranno gestiti dal [test runner a riga di comando |running-tests]. Vengono scritte all'inizio del file di test.

Le annotazioni sono insensibili alle maiuscole e alle minuscole. Inoltre, non hanno alcun effetto se il test viene eseguito manualmente come un normale script PHP.

Esempio:

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

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


TEST .[filter]
--------------
In realtà non è un'annotazione. Imposta solo il titolo del test che viene stampato in caso di fallimento o nei log.


@skip .[filter]
---------------
Il test viene saltato. È utile per disattivare temporaneamente il test.


@phpVersion .[filter]
---------------------
Il test viene saltato se non viene eseguito dalla versione PHP corrispondente. Scriviamo l'annotazione come `@phpVersion [operator] version`. Si può omettere l'operatore, l'impostazione predefinita è `>=`. Esempi:

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


@phpExtension .[filter]
-----------------------
Il test viene saltato se tutte le estensioni PHP menzionate non sono caricate. È possibile scrivere più estensioni in una singola annotazione, oppure utilizzare l'annotazione più volte.

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


@dataProvider .[filter]
-----------------------
Questa annotazione è adatta quando si vuole eseguire il test più volte, ma con dati diversi. (Da non confondere con l'annotazione omonima per [TestCase |TestCase#dataProvider]).

Scriviamo l'annotazione come `@dataProvider file.ini`. Il percorso del file INI è relativo al file di test. Il test viene eseguito tante volte quante sono le sezioni contenute nel file INI. Supponiamo che il file 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:"
```

e il file `database.phpt` nella stessa directory:

```php
/**
 * @dataProvider databases.ini
 */

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

Il test viene eseguito tre volte e `$args` conterrà i valori delle sezioni `mysql`, `postgresql` o `sqlite`.

Esiste un'ulteriore variante quando si scrivono annotazioni con un punto interrogativo come `@dataProvider? file.ini`. In questo caso, il test viene saltato se il file INI non esiste.

Le possibilità di annotazione non sono state ancora menzionate tutte. È possibile scrivere condizioni dopo il file INI. Il test viene eseguito per la sezione indicata solo se tutte le condizioni corrispondono. Estendiamo il file 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:"
```

e utilizzeremo l'annotazione con la condizione:

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

Il test viene eseguito solo una volta per la sezione `postgresql 9.1`. Le altre sezioni non corrispondono alle condizioni.

Allo stesso modo, si può passare il percorso a uno script PHP invece di INI. Deve restituire un array o un Traversable. File `databases.php`:

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

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


@multiplo .[filter]
-------------------
Si scrive come `@multiple N` dove `N` è un numero intero. Il test viene eseguito esattamente N volte.


@testCase .[filter]
-------------------
L'annotazione non ha parametri. Si usa quando si scrive un test come classi [TestCase |TestCase]. In questo caso, il test runner a riga di comando eseguirà i singoli metodi in processi separati e in parallelo in più thread. Questo può accelerare notevolmente l'intero processo di test.


@exitCode .[filter]
-------------------
Lo scriviamo come `@exitCode N` dove `N` is the exit code of the test. For example if `exit(10)` viene chiamato nel test, scriviamo l'annotazione come `@exitCode 10`. Il test viene considerato fallito se termina con un codice diverso. Il codice di uscita 0 (zero) è verificato se si tralascia l'annotazione


@httpCode .[filter]
-------------------
L'annotazione viene valutata solo se il binario PHP è CGI. Altrimenti viene ignorata. Si scrive come `@httpCode NNN`, dove `NNN` è il codice HTTP atteso. Il codice HTTP 200 viene verificato se si omette l'annotazione. Se si scrive `NNN` come una stringa valutata come zero, per esempio `any`, il codice HTTP non viene verificato affatto.


@outputMatch a @outputMatchFile .[filter]
-----------------------------------------
Il comportamento delle annotazioni è coerente con le asserzioni `Assert::match()` e `Assert::matchFile()`. Ma lo schema si trova nell'output standard del test. Un caso d'uso appropriato è quello in cui si suppone che il test termini con un errore fatale e che sia necessario verificare il suo output.


@phpIni .[filter]
-----------------
Imposta i valori di configurazione INI per il test. Ad esempio, lo scriviamo come `@phpIni precision=20` e funziona come se avessimo passato il valore dalla riga di comando con il parametro `-d precision=20`.