Adnotări de test

Adnotările determină cum vor fi tratate testele de către rulatorul de teste din linia de comandă. Se scriu la începutul fișierului cu testul.

La adnotări nu se ține cont de majuscule. De asemenea, nu au niciun efect dacă testul este rulat manual ca un script PHP obișnuit.

Exemplu:

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

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

TEST

Aceasta nu este de fapt o adnotare, ci doar specifică titlul testului, care se afișează la eșec sau în log.

@skip

Testul va fi omis. Este util pentru dezactivarea temporară a testelor.

@phpVersion

Testul va fi omis dacă nu este rulat cu versiunea PHP corespunzătoare. Adnotarea o scriem ca @phpVersion [operator] versiune. Operatorul poate fi omis, implicit este >=. Exemple:

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

@phpExtension

Testul va fi omis dacă nu sunt încărcate toate extensiile PHP specificate. Mai multe extensii pot fi specificate într-o singură adnotare sau o putem folosi de mai multe ori.

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

@dataProvider

Dacă dorim să rulăm fișierul de test de mai multe ori, dar cu date de intrare diferite, această adnotare este potrivită. (Nu confundați cu adnotarea omonimă pentru TestCase.)

O scriem ca @dataProvider file.ini, calea către fișier se consideră relativă la fișierul cu testul. Testul va fi rulat de atâtea ori câte secțiuni sunt în fișierul INI. Presupunem fișierul 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:"

și în același director testul database.phpt:

/**
 * @dataProvider databases.ini
 */

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

Testul va fi rulat de trei ori și $args va conține de fiecare dată valorile din secțiunea mysql, postgresql sau sqlite.

Există și o variantă în care scriem adnotarea cu un semn de întrebare ca @dataProvider? file.ini. În acest caz, testul va fi omis dacă fișierul INI nu există.

Posibilitățile adnotării nu se termină aici. După numele fișierului INI putem specifica condiții sub care testul va fi rulat pentru secțiunea respectivă. Extindem fișierul 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:"

și folosim adnotarea cu condiție:

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

Testul va fi rulat doar o singură dată și anume pentru secțiunea postgresql 9.1. Celelalte secțiuni nu trec filtrul condiției.

În mod similar, în loc de fișierul INI putem face referire la un script PHP. Acesta trebuie să returneze un array sau Traversable. Fișierul databases.php:

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

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

@multiple

O scriem ca @multiple N, unde N este un număr întreg. Testul va fi rulat exact de N ori.

@testCase

Adnotarea nu are parametri. O folosim dacă scriem testele ca clase TestCase. În acest caz, rulatorul de teste din linia de comandă va rula metodele individuale în procese separate și în paralel în mai multe fire de execuție. Acest lucru poate accelera semnificativ întregul proces de testare.

@exitCode

O scriem ca @exitCode N, unde N este codul de retur al testului rulat. Dacă în test se apelează, de exemplu, exit(10), scriem adnotarea ca @exitCode 10 și dacă testul se termină cu un alt cod, este considerat eșec. Dacă nu specificăm adnotarea, se verifică codul de retur 0 (zero).

@httpCode

Adnotarea se aplică doar dacă binarul PHP este CGI. Altfel se ignoră. O scriem ca @httpCode NNN unde NNN este codul HTTP așteptat. Dacă nu specificăm adnotarea, se verifică codul HTTP 200. Dacă NNN îl scriem ca un șir evaluat la zero, de exemplu any, codul HTTP nu se verifică.

@outputMatch și @outputMatchFile

Funcția adnotărilor este identică cu aserțiunile Assert::match() și Assert::matchFile(). Modelul (pattern) se caută însă în textul pe care testul l-a trimis la ieșirea sa standard. Găsește aplicare dacă presupunem că testul se va termina cu o eroare fatală și avem nevoie să verificăm ieșirea sa.

@phpIni

Pentru test setează valorile de configurare INI. O scriem, de exemplu, ca @phpIni precision=20 și funcționează la fel ca și cum am fi specificat valoarea din linia de comandă prin parametrul -d precision=20.