Anotacije testov
****************

.[perex]
Anotacije določajo, kako bo teste obravnaval [program za izvajanje testov v ukazni vrstici |running-tests]. Zapisane so na začetku testne datoteke.

Anotacije ne upoštevajo velikih in malih črk. Prav tako nimajo učinka, če se test zažene ročno kot običajna skripta PHP.

Primer:

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

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


TEST .[filter]
--------------
To pravzaprav ni anotacija. Določa le naslov testa, ki se izpiše pri neuspehu ali v dnevnike.


@skip .[filter]
---------------
Test se preskoči. To je priročno za začasno deaktivacijo testa.


@phpVersion .[filter]
---------------------
Test se preskoči, če ga ustrezna različica PHP ne zažene. Anotacijo zapišemo kot `@phpVersion [operator] version`. Operator lahko izpustimo, privzeto je `>=`. Primeri:

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


@phpExtension .[filter]
-----------------------
Test se preskoči, če niso naložene vse navedene razširitve PHP. Več razširitev lahko zapišemo v eno samo opombo ali pa opombo uporabimo večkrat.

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


@dataProvider .[filter]
-----------------------
Ta opomba je primerna, kadar želimo test zagnati večkrat, vendar z različnimi podatki. (Ne smemo ga zamenjati z istoimensko opombo za [TestCase |TestCase#dataProvider].)

Anotacijo zapišemo kot `@dataProvider file.ini`. Pot do datoteke INI je relativna glede na datoteko testa. Test se izvede tolikokrat, kolikor odsekov vsebuje datoteka INI. Predpostavimo, da je datoteka 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:"
```

in datoteko `database.phpt` v istem imeniku:

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

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

Test se izvede trikrat, datoteka `$args` pa bo vsebovala vrednosti iz razdelkov `mysql`, `postgresql` ali `sqlite`.

Obstaja še ena različica, ko anotacije zapišemo z vprašalnim znakom kot `@dataProvider? file.ini`. V tem primeru se test preskoči, če datoteka INI ne obstaja.

Vse možnosti anotacij še niso bile omenjene. Za datoteko INI lahko zapišemo pogoje. Test se za dani razdelek izvede le, če se vsi pogoji ujemajo. Razširimo datoteko 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:"
```

in uporabimo opombo s pogojem:

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

Test se izvede samo enkrat za odsek `postgresql 9.1`. Druga poglavja ne ustrezajo pogojem.

Podobno lahko namesto INI posredujemo pot do skripte PHP. Ta mora vrniti polje ali Traversable. Datoteka `databases.php`:

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

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


@multiple .[filter]
-------------------
Zapišemo ga kot `@multiple N`, kjer je `N` celo število. Test se izvede natanko N-krat.


@testCase .[filter]
-------------------
Anotacija nima parametrov. Uporabimo jo, ko test zapišemo kot razred [TestCase |TestCase]. V tem primeru bo izvajalec testov v ukazni vrstici izvajal posamezne metode v ločenih procesih in vzporedno v več niti. S tem lahko bistveno pospešimo celoten postopek testiranja.


@exitCode .[filter]
-------------------
Zapišemo jo kot `@exitCode N`, kjer se v testu kliče `N` is the exit code of the test. For example if `exit(10)`, anotacijo zapišemo kot `@exitCode 10`. Šteje se, da je test neuspešen, če se konča z drugačno kodo. Koda izhoda 0 (nič) se preveri, če izpustimo opombo


@httpCode .[filter]
-------------------
Opomba se oceni samo, če je binarni program PHP CGI. V nasprotnem primeru se ne upošteva. Zapišemo jo kot `@httpCode NNN`, kjer je `NNN` pričakovana koda HTTP. Koda HTTP 200 se preveri, če opusti anotacijo. Če zapišemo `NNN` kot niz, ovrednoten kot nič, na primer `any`, se koda HTTP sploh ne preveri.


@outputMatch a @outputMatchFile .[filter]
-----------------------------------------
Obnašanje pripisov je skladno s trditvami `Assert::match()` in `Assert::matchFile()`. Vzorec pa najdemo v standardnem izpisu testa. Primeren primer uporabe je, ko predvidevamo, da se test konča s usodno napako, in moramo preveriti njegov izhod.


@phpIni .[filter]
-----------------
Nastavi konfiguracijske vrednosti INI za test. Zapišemo ga na primer kot `@phpIni precision=20` in deluje enako, kot če bi vrednost iz ukazne vrstice posredovali s parametrom `-d precision=20`.