Adnotacje testów

Adnotacje określają, jak testy będą obsługiwane przez runner testów z wiersza poleceń. Zapisuje się je na początku pliku testu.

Adnotacje nie rozróżniają wielkości liter. Nie mają też żadnego efektu, jeśli test uruchomimy ręcznie jako zwykły skrypt PHP.

Przykład:

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

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

TEST

To właściwie nie jest adnotacja. Podaje po prostu tytuł testu, który wyświetla się w razie niepowodzenia albo w logach.

@skip

Test jest pomijany. Przydaje się do tymczasowego wyłączania testów.

@phpVersion

Test jest pomijany, jeśli nie jest uruchamiany z odpowiednią wersją PHP. Adnotację zapisujemy jako @phpVersion [operator] wersja. Operator można pominąć, domyślny to >=. Przykłady:

/**
 * @phpVersion 8.1
 * @phpVersion < 8.4
 * @phpVersion != 8.2.5
 */

@phpExtension

Test jest pomijany, jeśli nie są załadowane wszystkie podane rozszerzenia PHP. Wiele rozszerzeń można wypisać w jednej adnotacji albo użyć adnotacji wielokrotnie.

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

@dataProvider

Ta adnotacja przydaje się, gdy chcesz uruchomić plik testu wielokrotnie z różnymi danymi wejściowymi. (Nie myl jej z adnotacją o tej samej nazwie dla TestCase.)

Zapisujemy ją jako @dataProvider file.ini. Ścieżka pliku jest względem pliku testu. Test uruchomi się tyle razy, ile sekcji ma plik INI. Załóżmy plik 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:"

i plik database.phpt w tym samym katalogu:

/**
 * @dataProvider databases.ini
 */

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

Test uruchomi się trzy razy, a $args będzie zawierać wartości odpowiednio z sekcji mysql, postgresql albo sqlite.

Istnieje jeszcze wariant, w którym adnotację zapisujemy ze znakiem zapytania: @dataProvider? file.ini. W tym przypadku test jest pomijany, jeśli plik INI nie istnieje.

Możliwości tej adnotacji na tym się nie kończą. Za nazwą pliku INI możesz podać warunki określające, czy test uruchomi się dla konkretnej sekcji. Rozszerzmy plik 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:"

i użyjmy adnotacji z warunkiem:

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

Test uruchomi się tylko raz, dla sekcji postgresql 9.1. Pozostałe sekcje nie spełniają filtra warunku.

Podobnie zamiast pliku INI możesz odwołać się do skryptu PHP. Musi on zwrócić tablicę albo obiekt Traversable. Plik databases.php:

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

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

@multiple

Zapisujemy ją jako @multiple N, gdzie N to liczba całkowita. Test uruchomi się dokładnie N razy.

@testCase

Ta adnotacja nie ma parametrów. Użyj jej, gdy piszesz testy jako klasy TestCase. W tym przypadku runner testów z wiersza poleceń będzie wykonywał poszczególne metody w osobnych procesach i równolegle w wielu wątkach. Może to znacząco przyspieszyć cały proces testowania.

@exitCode

Zapisujemy ją jako @exitCode N, gdzie N to oczekiwany kod wyjścia testu. Jeśli na przykład w teście wywoływane jest exit(10), adnotację zapisujemy jako @exitCode 10. Jeśli test zakończy się innym kodem, uznawane jest to za niepowodzenie. Jeśli adnotację pominiemy, weryfikowany jest kod wyjścia 0 (zero).

@httpCode

Ta adnotacja stosuje się tylko wtedy, gdy binarka PHP to CGI; w przeciwnym razie jest ignorowana. Zapisujemy ją jako @httpCode NNN, gdzie NNN to oczekiwany kod HTTP. Jeśli adnotację pominiemy, weryfikowany jest kod HTTP 200. Jeśli NNN zapiszemy jako ciąg, który ewaluuje się do zera (np. any), kod HTTP nie jest sprawdzany.

@outputMatch i @outputMatchFile

Funkcja tych adnotacji jest identyczna jak asercji Assert::match() i Assert::matchFile(). Wzorzec szukany jest jednak w tekście, który test wysłał na swoje standardowe wyjście. Przydaje się to, gdy spodziewasz się, że test zakończy się błędem krytycznym, i musisz zweryfikować jego wyjście.

@phpIni

Ustawia testowi wartości konfiguracyjne INI. Zapisujemy ją na przykład jako @phpIni precision=20. Działa tak samo, jakbyś podał wartość z wiersza poleceń parametrem -d precision=20.