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

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

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

Пример:

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

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

Test

На самом деле это не аннотация. Он только задает заголовок теста, который выводится при отказе или в логах.

@skip

Тест пропускается. Это удобно для временной деактивации теста.

@phpVersion

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

/**
 * @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-файле. Предположим, что 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. Другие разделы не соответствуют условиям.

Аналогично, мы можем передать путь к PHP-скрипту вместо INI. Он должен возвращать массив или 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 is the exit code of the test. For example if exit(10) вызывается в тесте, мы пишем аннотацию как @exitCode 10. Считается неудачей, если тест завершается с другим кодом. Код выхода 0 (ноль) проверяется, если мы опустим аннотацию

@httpCode

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

@outputMatch a @outputMatchFile

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

@phpIni

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