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

.[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 [оператор] версія`. Оператор можна пропустити, стандартний — `>=`. Приклади:

```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-файл `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`. Інші секції фільтром умови не пройдуть.

Аналогічно, замість INI-файлу ми можемо посилатися на PHP-скрипт. Він повинен повернути масив або 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` — код повернення запущеного тесту. Якщо в тесті, наприклад, викликається `exit(10)`, анотацію запишемо як `@exitCode 10`, і якщо тест завершиться з іншим кодом, це вважається невдачею. Якщо анотацію не вказати, перевіряється код повернення 0 (нуль).


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


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


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