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

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

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

Пример:

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

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

TEST

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

@skip

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

@phpVersion

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

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

@phpIni

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