Анотації до тестів
******************

.[perex]
Анотації визначають, як тести будуть оброблятися [програмою запуску тестів командного рядка |running-tests]. Вони записуються на початку файлу тесту.

Анотації не чутливі до регістру. Вони також не мають жодного ефекту, якщо тест запускається вручну як звичайний PHP-скрипт.

Приклад:

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

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


Test .[filter]
--------------
Насправді це не анотація. Він тільки задає заголовок тесту, який виводиться при відмові або в логах.


@skip .[filter]
---------------
Тест пропускається. Це зручно для тимчасової деактивації тесту.


@phpVersion .[filter]
---------------------
Тест буде пропущено, якщо він не запущений відповідною версією PHP. Ми пишемо анотацію як `@phpVersion [operator] version`. Ми можемо не вказувати оператор, за замовчуванням це `>=`. Приклади:

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


@phpExtension .[filter]
-----------------------
Тест буде пропущено, якщо всі зазначені розширення PHP не завантажені. Кілька розширень можуть бути записані в одній анотації, або ми можемо використовувати анотацію кілька разів.

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


@dataProvider .[filter]
-----------------------
Ця анотація підходить, коли ми хочемо запустити тест кілька разів, але з різними даними. (Не плутати з однойменною анотацією для [TestCase |TestCase#dataProvider]).

Ми пишемо анотацію як `@dataProvider file.ini`. Шлях до файлу INI є відносним до файлу тесту. Тест запускається стільки разів, скільки секцій міститься в INI-файлі. Припустимо, що 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:"
```

і файл `database.phpt` в одному каталозі:

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

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

Тест виконується тричі, і `$args` міститиме значення із секцій `mysql`, `postgresql` або `sqlite`.

Є ще один варіант, коли ми пишемо анотації зі знаком питання, як `@dataProvider? file.ini`. У цьому випадку тест буде пропущено, якщо INI-файл не існує.

Можливості анотацій ще не всі згадані. Ми можемо написати умови після INI-файлу. Тест запускається для заданої секції тільки в тому випадку, якщо всі умови збігаються. Давайте розширимо 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:"
```

і будемо використовувати анотацію з умовою:

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

Тест виконується тільки один раз для секції `postgresql 9.1`. Інші розділи не відповідають умовам.

Аналогічно, ми можемо передати шлях до PHP-скрипту замість INI. Він повинен повертати масив або Traversable. Файл `databases.php`:

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

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


@multiple .[filter]
-------------------
Запишемо це як `@multiple N`, де `N` - ціле число. Тест виконується рівно N разів.


@testCase .[filter]
-------------------
Анотація не має параметрів. Ми використовуємо її, коли пишемо тест у вигляді класів [TestCase |TestCase]. У цьому випадку програма запуску тестів командного рядка запускатиме окремі методи в окремих процесах і паралельно в декількох потоках. Це може значно прискорити весь процес тестування.


@exitCode .[filter]
-------------------
Ми пишемо його як `@exitCode N`, де `N` is the exit code of the test. For example if `exit(10)` викликається в тесті, ми пишемо анотацію як `@exitCode 10`. Вважається невдачею, якщо тест завершується з іншим кодом. Код виходу 0 (нуль) перевіряється, якщо ми опустимо анотацію


@httpCode .[filter]
-------------------
Анотація оцінюється тільки в тому випадку, якщо бінарний PHP є CGI. В іншому випадку вона ігнорується. Ми записуємо її як `@httpCode NNN`, де `NNN` - очікуваний HTTP-код. HTTP-код 200 буде перевірено, якщо ми опустимо анотацію. Якщо ми запишемо `NNN` як рядок, що оцінюється як нуль, наприклад, `any`, HTTP-код не перевірятиметься взагалі.


@outputMatch a @outputMatchFile .[filter]
-----------------------------------------
Поведінка анотацій відповідає твердженням `Assert::match()` і `Assert::matchFile()`. Але в стандартному виведенні тесту зустрічається патерн. Відповідний випадок використання - коли ми припускаємо, що тест завершиться фатальною помилкою, і нам потрібно перевірити його виведення.


@phpIni .[filter]
-----------------
Встановлює значення конфігурації INI для тесту. Наприклад, ми записуємо його як `@phpIni precision=20` і він працює так само, як якщо б ми передали значення з командного рядка параметром `-d precision=20`.