Adnotacja o testach
*******************

.[perex]
Adnotacje określają, jak [biegacz |running-tests] testowy będzie obsługiwał testy [z linii poleceń |running-tests]. Są one zapisywane na początku pliku testowego.

Adnotacje nie uwzględniają wielkości liter. Nie mają one również wpływu, jeśli test jest uruchamiany ręcznie jako zwykły skrypt PHP.

Przykład:

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

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


TEST .[filter]
--------------
To nie jest właściwie adnotacja, po prostu określa tytuł testu, który jest drukowany na niepowodzeniach lub do dziennika.


@skip .[filter]
---------------
Test jest pomijany. Dobre do tymczasowego odrzucania testów.


@phpVersion .[filter]
---------------------
Test zostanie pominięty, jeśli nie zostanie uruchomiony z odpowiednią wersją PHP. Adnotację zapisujemy jako. `@phpVersion [operator] verze`. Operator może być pominięty, domyślnie jest to `>=`. Przykłady:

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


@phpExtension .[filter]
-----------------------
Test zostanie pominięty, jeśli nie zostaną załadowane wszystkie wymienione rozszerzenia PHP. Wiele rozszerzeń może być wymienionych w jednej adnotacji lub używanych wielokrotnie.

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


@dataProvider .[filter]
-----------------------
Jeśli chcesz uruchomić plik testowy wiele razy, ale z różnymi danymi wejściowymi, ta adnotacja jest przydatna. (Nie należy mylić z tą samą adnotacją dla [TestCase |TestCase#dataProvider]).

Zapisujemy go jako `@dataProvider file.ini`, ścieżka do pliku jest przyjmowana względem pliku testowego. Test zostanie uruchomiony tyle razy, ile jest sekcji w pliku INI. Załóżmy, że plik INI to `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 w tym samym katalogu test `database.phpt`:

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

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

Test zostanie uruchomiony trzy razy, a `$args` zawsze będzie zawierał wartości z `mysql`, `postgresql` lub `sqlite`.

Istnieje również wariant, w którym zapisujemy adnotację ze znakiem zapytania jako `@dataProvider? file.ini`. W tym przypadku test zostanie pominięty, jeśli plik INI nie istnieje.

To nie koniec opcji związanych z adnotacjami. Po nazwie pliku INI możemy określić warunki, w jakich test będzie uruchamiany dla danej sekcji. Rozwiń plik 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 użyć adnotacji o stanie:

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

Test zostanie przeprowadzony tylko raz dla odcinka `postgresql 9.1`. Pozostałe odcinki nie przejdą przez filtr warunków.

Podobnie możemy odwołać się do skryptu PHP zamiast do pliku INI. Musi to zwrócić tablicę lub Traversable. Plik `databases.php`:

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

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


@multiple .[filter]
-------------------
Zapisujemy ją jako `@multiple N`, gdzie `N` jest liczbą całkowitą. Test zostanie przeprowadzony dokładnie N razy.


@testCase .[filter]
-------------------
Adnotacja nie posiada żadnych parametrów. Używamy go, gdy piszemy testy jako klasy [TestCase |TestCase]. W takim przypadku biegacz testowy linii poleceń uruchomi każdą metodę w oddzielnych procesach i równolegle w wielu wątkach. Może to znacznie przyspieszyć cały proces testowania.


@exitCode .[filter]
-------------------
Zapisujemy go jako `@exitCode N`, gdzie `N` je návratový kód spuštěného testu. Je-li v testu například voláno `exit(10)`, adnotację zapisujemy jako `@exitCode 10` i jeśli test zakończy się innym kodem, jest to traktowane jako niepowodzenie. Jeśli nie podano adnotacji, kod zwrotny jest walidowany jako 0 (zero).


@httpCode .[filter]
-------------------
Adnotacja jest stosowana tylko wtedy, gdy PHP jest binarnym CGI. W przeciwnym razie jest ignorowany. Zapisujemy go jako `@httpCode NNN` gdzie `NNN` to oczekiwany kod HTTP. Jeśli nie podano adnotacji, zatwierdzany jest kod HTTP 200. Jeśli `NNN` jest zapisany jako ciąg o wartości zero, na przykład `any`, kod HTTP nie jest weryfikowany.


@outputMatch i @outputMatchFile .[filter]
-----------------------------------------
Funkcja adnotacji jest identyczna jak w przypadku asercji `Assert::match()` i `Assert::matchFile()`. Jednak wzorzec jest szukany w tekście, który test wysłał na swoje standardowe wyjście. Jest to przydatne, jeśli spodziewamy się, że test zakończy się fatalnym błędem i musimy zatwierdzić jego wyjście.


@phpIni .[filter]
-----------------
Ustawia wartości INI konfiguracji dla testu. Na przykład piszemy go jako `@phpIni precision=20` i działa tak samo, jakbyśmy wprowadzili wartość z linii poleceń poprzez parametr `-d precision=20`.