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

Аннотации определяют, как будут обрабатываться тесты средством запуска тестов из командной строки. Они записываются в начале файла с тестом.

В аннотациях не учитывается регистр букв. Также они не имеют никакого влияния, если тест запущен вручную как обычный PHP-скрипт.

Пример:

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

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

TEST

Это, собственно, даже не аннотация, она просто определяет заголовок теста, который выводится при сбое или в лог.

@skip

Тест будет пропущен. Полезно для временного отключения тестов.

@phpVersion

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

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

@phpExtension

Тест будет пропущен, если не загружены все указанные PHP-расширения. Несколько расширений можно указать в одной аннотации или использовать ее несколько раз.

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

@dataProvider

Если мы хотим запустить тестовый файл несколько раз, но с разными входными данными, полезна именно эта аннотация. (Не путайте с одноименной аннотацией для TestCase.)

Записываем как @dataProvider file.ini, путь к файлу берется относительно файла с тестом. Тест будет запущен столько раз, сколько секций в INI-файле. Предположим, INI-файл databases.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:

/**
 * @dataProvider databases.ini
 */

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

Тест будет запущен трижды, и $args будет содержать всегда значения из секции mysql, postgresql или sqlite.

Существует еще вариант, когда аннотацию записываем с вопросительным знаком как @dataProvider? file.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:"

и используем аннотацию с условием:

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

Тест будет запущен только один раз, и то для секции postgresql 9.1. Остальные секции фильтром условия не пройдут.

Аналогично, вместо INI-файла мы можем сослаться на PHP-скрипт. Он должен вернуть массив или Traversable. Файл databases.php:

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

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

@multiple

Записываем как @multiple N, где N — целое число. Тест будет запущен ровно N раз.

@testCase

Аннотация не имеет параметров. Используем ее, если тесты пишем как классы TestCase. В этом случае средство запуска тестов из командной строки будет запускать отдельные методы в самостоятельных процессах и параллельно в нескольких потоках. Это может значительно ускорить весь процесс тестирования.

@exitCode

Записываем как @exitCode N, где N — код возврата запущенного теста. Если в тесте, например, вызывается exit(10), аннотацию запишем как @exitCode 10, и если тест завершится с другим кодом, это считается сбоем. Если аннотацию не указать, проверяется код возврата 0 (ноль).

@httpCode

Аннотация применяется только если бинарный файл PHP — CGI. В противном случае игнорируется. Записываем как @httpCode NNN, где NNN — ожидаемый HTTP-код. Если аннотацию не указать, проверяется HTTP-код 200. Если NNN записать как строку, вычисляемую в ноль, например, any, HTTP-код не проверяется.

@outputMatch и @outputMatchFile

Функции аннотаций совпадают с утверждениями Assert::match() и Assert::matchFile(). Шаблон (pattern) ищется в тексте, который тест отправил на свой стандартный вывод. Применение находит, если мы предполагаем, что тест завершится фатальной ошибкой, и нам нужно проверить его вывод.

@phpIni

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