Анотації тестів

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

При анотаціях не враховується регістр літер. Також вони не мають жодного впливу, якщо тест запущений вручну як звичайний 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

Функція анотацій збігається з assertion Assert::match() та Assert::matchFile(). Патерн (шаблон) шукається в тексті, який тест надіслав на свій стандартний вивід. Застосування знайде, якщо ми припускаємо, що тест завершиться фатальною помилкою, і нам потрібно перевірити його вивід.

@phpIni

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