Annotazioni dei test

Le annotazioni determinano come i test verranno gestiti dall'esecutore di test dalla riga di comando. Vengono scritte all'inizio del file con il test.

Nelle annotazioni non si tiene conto delle maiuscole/minuscole. Inoltre non hanno alcun effetto se il test viene eseguito manualmente come uno script PHP comune.

Esempio:

/**
 * TEST: Test di query di base sul database.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 5.5
 */

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

TEST

Questa in realtà non è nemmeno un'annotazione, specifica solo il titolo del test, che viene visualizzato in caso di fallimento o nel log.

@skip

Il test viene saltato. Utile per disabilitare temporaneamente i test.

@phpVersion

Il test viene saltato se non viene eseguito con la versione PHP corrispondente. L'annotazione la scriviamo come @phpVersion [operatore] versione. L'operatore può essere omesso, il predefinito è >=. Esempi:

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

@phpExtension

Il test viene saltato se non sono caricate tutte le estensioni PHP specificate. Più estensioni possono essere specificate in una singola annotazione, oppure può essere utilizzata più volte.

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

@dataProvider

Se vogliamo eseguire il file di test più volte, ma con dati di input diversi, questa annotazione è utile. (Non confondere con l'annotazione omonima per TestCase.)

La scriviamo come @dataProvider file.ini, il percorso del file viene considerato relativo al file con il test. Il test verrà eseguito tante volte quante sono le sezioni nel file INI. Supponiamo il file 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:"

e nella stessa directory il test database.phpt:

/**
 * @dataProvider databases.ini
 */

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

Il test verrà eseguito tre volte e $args conterrà sempre i valori dalla sezione mysql, postgresql o sqlite.

Esiste ancora una variante in cui scriviamo l'annotazione con un punto interrogativo come @dataProvider? file.ini. In questo caso, il test viene saltato se il file INI non esiste.

Le possibilità dell'annotazione non finiscono qui. Dopo il nome del file INI possiamo specificare le condizioni in base alle quali il test verrà eseguito per la sezione specificata. Estendiamo il file 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 usiamo l'annotazione con la condizione:

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

Il test verrà eseguito solo una volta e per la sezione postgresql 9.1. Le altre sezioni non superano il filtro della condizione.

Analogamente, invece di un file INI possiamo fare riferimento a uno script PHP. Questo deve restituire un array o Traversable. File databases.php:

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

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

@multiple

Scriviamo come @multiple N, dove N è un numero intero. Il test verrà eseguito esattamente N volte.

@testCase

L'annotazione non ha parametri. La usiamo se scriviamo i test come classi TestCase. In tal caso, l'esecutore di test dalla riga di comando eseguirà i singoli metodi in processi separati e in parallelo su più thread. Questo può accelerare notevolmente l'intero processo di test.

@exitCode

Scriviamo come @exitCode N, dove N è il codice di ritorno del test eseguito. Se nel test viene ad esempio chiamato exit(10), scriviamo l'annotazione come @exitCode 10 e se il test termina con un codice diverso, viene considerato un fallimento. Se l'annotazione non viene specificata, viene verificato il codice di ritorno 0 (zero).

@httpCode

L'annotazione si applica solo se il binario PHP è CGI. Altrimenti viene ignorata. Scriviamo come @httpCode NNN dove NNN è il codice HTTP atteso. Se l'annotazione non viene specificata, viene verificato il codice HTTP 200. Se NNN viene scritto come una stringa valutata a zero, ad esempio any, il codice HTTP non viene verificato.

@outputMatch e @outputMatchFile

La funzione delle annotazioni è identica alle asserzioni Assert::match() e Assert::matchFile(). Il pattern viene però cercato nel testo che il test ha inviato al suo output standard. Trova applicazione se prevediamo che il test termini con un errore fatale e abbiamo bisogno di verificare il suo output.

@phpIni

Per il test imposta i valori INI di configurazione. Scriviamo ad esempio come @phpIni precision=20 e funziona come se avessimo specificato il valore dalla riga di comando tramite il parametro -d precision=20.