Annotazioni dei test

Le annotazioni determinano come i test verranno trattati dal runner dei test da riga di comando. Si scrivono all'inizio del file del test.

Le annotazioni non fanno distinzione tra maiuscole e minuscole. Non hanno inoltre alcun effetto se il test viene eseguito a mano come un normale script PHP.

Esempio:

/**
 * TEST: Test di base di una query al database.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 8.4
 */

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

TEST

In realtà non è un'annotazione. Indica semplicemente il titolo del test, che viene mostrato in caso di fallimento o nei log.

@skip

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

@phpVersion

Il test viene saltato se non è eseguito con la versione di PHP corrispondente. L'annotazione si scrive come @phpVersion [operatore] versione. L'operatore si può omettere, quello predefinito è >=. Esempi:

/**
 * @phpVersion 8.1
 * @phpVersion < 8.4
 * @phpVersion != 8.2.5
 */

@phpExtension

Il test viene saltato se non sono caricate tutte le estensioni PHP indicate. In una sola annotazione si possono elencare più estensioni, oppure si può usare l'annotazione più volte.

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

@dataProvider

Questa annotazione torna utile quando volete eseguire il file del test più volte con dati in ingresso diversi. (Non confondetela con l'annotazione omonima per TestCase.)

Si scrive come @dataProvider file.ini. Il percorso del file è relativo al file del 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 il file database.phpt nella stessa directory:

/**
 * @dataProvider databases.ini
 */

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

Il test verrà eseguito tre volte e $args conterrà rispettivamente i valori della sezione mysql, postgresql oppure sqlite.

Esiste un'altra variante in cui scrivete l'annotazione con un punto interrogativo: @dataProvider? file.ini. In questo caso il test viene saltato se il file INI non esiste.

Le possibilità di questa annotazione non finiscono qui. Dopo il nome del file INI potete indicare delle condizioni che determinano se il test viene eseguito per una data sezione. 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 una condizione:

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

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

Allo stesso modo, invece di un file INI potete indicare uno script PHP. Deve restituire un array o un oggetto Traversable. File databases.php:

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

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

@multiple

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

@testCase

Questa annotazione non ha parametri. Usatela quando scrivete i test come classi TestCase. In tal caso il runner da 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

Si scrive come @exitCode N, dove N è il codice di uscita atteso del test. Se per esempio nel test viene chiamato exit(10), scrivete l'annotazione come @exitCode 10. Se il test termina con un codice diverso, è considerato fallito. Se l'annotazione viene omessa, si verifica il codice di uscita 0 (zero).

@httpCode

Questa annotazione si applica solo se il binario PHP è CGI, altrimenti viene ignorata. Si scrive come @httpCode NNN, dove NNN è il codice HTTP atteso. Se l'annotazione viene omessa, si verifica il codice HTTP 200. Se NNN è scritto come una stringa che vale zero (per esempio any), il codice HTTP non viene controllato.

@outputMatch e @outputMatchFile

La funzione di queste annotazioni è identica alle asserzioni Assert::match() e Assert::matchFile(). Il pattern viene però cercato nel testo che il test ha inviato al proprio output standard. Torna utile quando vi aspettate che un test termini con un errore fatale e dovete verificarne l'output.

@phpIni

Imposta i valori di configurazione INI per il test. Si scrive per esempio come @phpIni precision=20. Funziona come se indicaste il valore dalla riga di comando con il parametro -d precision=20.