Adnotări de testare
*******************

.[perex]
Adnotările determină modul în care testele vor fi gestionate de către [programul de execuție a testelor din linia de comandă |running-tests]. Ele sunt scrise la începutul fișierului de test.

Adnotările nu țin cont de majuscule și minuscule. De asemenea, acestea nu au niciun efect dacă testul este rulat manual ca un script PHP obișnuit.

Exemplu:

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

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


TEST .[filter]
--------------
De fapt, nu este o adnotare. Setează doar titlul testului care este tipărit la eșec sau în jurnale.


@skip .[filter]
---------------
Testul este omis. Este utilă pentru dezactivarea temporară a testului.


@phpVersion .[filter]
---------------------
Testul este omis dacă nu este executat de versiunea PHP corespunzătoare. Scriem adnotarea ca `@phpVersion [operator] version`. Putem omite operatorul, implicit este `>=`. Exemple:

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


@phpExtensiune .[filter]
------------------------
Testul este omis dacă toate extensiile PHP menționate nu sunt încărcate. Într-o singură adnotare pot fi scrise mai multe extensii sau putem folosi adnotarea de mai multe ori.

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


@dataProvider .[filter]
-----------------------
Această adnotare se potrivește atunci când dorim să executăm testul de mai multe ori, dar cu date diferite. (A nu se confunda cu adnotarea cu același nume pentru [TestCase |TestCase#dataProvider]).

Scriem adnotarea ca `@dataProvider file.ini`. Calea fișierului INI este relativă la fișierul de test. Testul se execută de atâtea ori cât numărul de secțiuni conținute în fișierul INI. Să presupunem că fișierul 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:"
```

și fișierul `database.phpt` în același director:

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

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

Testul se execută de trei ori, iar `$args` va conține valori din secțiunile `mysql`, `postgresql` sau `sqlite`.

Mai există o variantă atunci când scriem adnotările cu semnul întrebării ca `@dataProvider? file.ini`. În acest caz, testul este sărit dacă fișierul INI nu există.

Posibilitățile de adnotare nu au fost menționate încă toate. Putem scrie condiții după fișierul INI. Testul se execută pentru secțiunea dată numai dacă toate condițiile corespund. Să extindem fișierul 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:"
```

și vom folosi adnotarea cu condiția:

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

Testul se execută o singură dată pentru secțiunea `postgresql 9.1`. Celelalte secțiuni nu corespund condițiilor.

În mod similar, putem trece calea către un script PHP în loc de INI. Acesta trebuie să returneze array sau Traversable. Fișierul `databases.php`:

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

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


@multiple .[filter]
-------------------
O scriem ca `@multiple N` unde `N` este un număr întreg. Testul se execută exact de N ori.


@testCase .[filter]
-------------------
Adnotarea nu are parametri. O folosim atunci când scriem un test sub formă de clase [TestCase |TestCase]. În acest caz, executorul 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 .[filter]
-------------------
Îl scriem ca `@exitCode N` în cazul în care `N` is the exit code of the test. For example if `exit(10)` este apelat în test, scriem adnotarea ca `@exitCode 10`. Se consideră că testul eșuează dacă se încheie cu un cod diferit. Codul de ieșire 0 (zero) este verificat dacă omitem adnotarea


@httpCode .[filter]
-------------------
Adnotarea este evaluată numai dacă binarul PHP este CGI. În caz contrar, este ignorată. O scriem ca `@httpCode NNN` unde `NNN` este codul HTTP așteptat. Codul HTTP 200 este verificat dacă nu includem adnotarea. Dacă scriem `NNN` ca un șir de caractere evaluat ca zero, de exemplu `any`, codul HTTP nu este verificat deloc.


@outputMatch a @outputMatchFile .[filter]
-----------------------------------------
Comportamentul adnotărilor este în concordanță cu aserțiunile `Assert::match()` și `Assert::matchFile()`. Dar modelul se găsește în ieșirea standard a testului. Un caz de utilizare adecvat este atunci când presupunem că testul se încheie cu o eroare fatală și trebuie să verificăm ieșirea acestuia.


@phpIni .[filter]
-----------------
Setează valorile de configurare INI pentru test. De exemplu, îl scriem ca `@phpIni precision=20` și funcționează în același mod ca și cum am trece valoarea din linia de comandă prin parametrul `-d precision=20`.