Аннотации тестов
****************

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

Аннотации нечувствительны к регистру. Кроме того, они не действуют, если тест запущен вручную как обычный PHP-скрипт.

Пример:

```php
/**
 * TEST: Базовая проверка запроса к базе данных.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 8.4
 */

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


TEST .[filter]
--------------
На самом деле это не аннотация. Она просто задаёт название теста, которое отображается при провале или в логах.


@skip .[filter]
---------------
Тест пропускается. Удобно для временного отключения тестов.


@phpVersion .[filter]
---------------------
Тест пропускается, если запущен не с соответствующей версией PHP. Записывайте аннотацию как `@phpVersion [оператор] версия`. Оператор можно опустить, по умолчанию это `>=`. Примеры:

```php
/**
 * @phpVersion 8.1
 * @phpVersion < 8.4
 * @phpVersion != 8.2.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]
-----------------------------------------
Действие этих аннотаций идентично утверждениям `Assert::match()` и `Assert::matchFile()`. Однако образец ищется в тексте, который тест отправил в свой стандартный вывод. Это удобно, когда вы ожидаете, что тест завершится фатальной ошибкой, и вам нужно проверить его вывод.


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