Аннотации к тестам
******************

.[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]. В этом случае программа запуска тестов командной строки будет запускать отдельные методы в отдельных процессах и параллельно в нескольких потоках. Это может значительно ускорить весь процесс тестирования.


@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`.