Adnotacje testów

Adnotacje określają, jak z testami będzie postępować narzędzie do uruchamiania testów z wiersza poleceń. Zapisuje się je na początku pliku z testem.

W adnotacjach nie bierze się pod uwagę wielkości liter. Również nie mają żadnego wpływu, jeśli test jest uruchamiany ręcznie jako zwykły skrypt PHP.

Przykład:

/**
 * TEST: Podstawowy test zapytania do bazy danych.
 *
 * @dataProvider files/databases.ini
 * @exitCode 56
 * @phpVersion < 5.5
 */

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

TEST

To właściwie nawet nie jest adnotacja, jedynie określa tytuł testu, który jest wypisywany przy niepowodzeniu lub do logu.

@skip

Test zostanie pominięty. Przydaje się do tymczasowego wyłączenia testów.

@phpVersion

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

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

@phpExtension

Test zostanie pominięty, jeśli nie są wczytane wszystkie podane rozszerzenia PHP. Więcej rozszerzeń możemy podać w jednej adnotacji lub użyć jej wielokrotnie.

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

@dataProvider

Jeśli chcemy plik testowy uruchomić wielokrotnie, ale z innymi danymi wejściowymi, przyda się właśnie ta adnotacja. (Nie mylić z adnotacją o tej samej nazwie dla TestCase.)

Zapisujemy jako @dataProvider file.ini, ścieżka do pliku jest brana relatywnie do pliku z testem. Test zostanie uruchomiony tyle razy, ile jest sekcji w pliku 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:"

a w tym samym katalogu test database.phpt :

/**
 * @dataProvider databases.ini
 */

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

Test zostanie uruchomiony trzykrotnie, a $args będzie zawierać zawsze wartości z sekcji mysql, postgresql lub sqlite.

Istnieje jeszcze wariant, gdy adnotację zapiszemy ze znakiem zapytania jako @dataProvider? file.ini. W tym przypadku test zostanie pominięty, jeśli plik INI nie istnieje.

Tym możliwości adnotacji nie kończą się. Za nazwę pliku INI możemy specyfikować warunki, przy których test dla danej sekcji zostanie uruchomiony. Rozszerzymy 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żyjemy adnotacji z warunkiem:

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

Test zostanie uruchomiony tylko raz i to dla sekcji postgresql 9.1. Pozostałe sekcje filtrem warunku nie przejdą.

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

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

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

@multiple

Zapisujemy jako @multiple N, gdzie N jest liczbą całkowitą. Test zostanie uruchomiony dokładnie N razy.

@testCase

Adnotacja nie ma parametrów. Użyjemy jej, jeśli testy piszemy jako klasy TestCase. W tym przypadku narzędzie do uruchamiania testów z wiersza poleceń będzie uruchamiać poszczególne metody w oddzielnych procesach i równolegle w wielu wątkach. Może to znacznie przyspieszyć cały proces testowania.

@exitCode

Zapisujemy jako @exitCode N, gdzie N jest kodem powrotu uruchomionego testu. Jeśli w teście jest na przykład wywołane exit(10), adnotację zapiszemy jako @exitCode 10, a jeśli test zakończy się z innym kodem, jest to uważane za niepowodzenie. Jeśli adnotacji nie podamy, jest weryfikowany kod powrotu 0 (zero).

@httpCode

Adnotacja ma zastosowanie tylko jeśli binarka PHP jest CGI. W przeciwnym razie jest ignorowana. Zapisujemy jako @httpCode NNN, gdzie NNN jest oczekiwanym kodem HTTP. Jeśli adnotacji nie podamy, weryfikuje się kod HTTP 200. Jeśli NNN zapiszemy jako ciąg znaków ewaluowany do zera, na przykład any, kod HTTP nie jest weryfikowany.

@outputMatch i @outputMatchFile

Funkcja adnotacji jest zgodna z asercjami Assert::match() i Assert::matchFile(). Wzór (pattern) jest jednak szukany w tekście, który test wysłał na swoje standardowe wyjście. Zastosowanie znajdzie, jeśli zakładamy, że test zakończy się błędem fatalnym i potrzebujemy zweryfikować jego wyjście.

@phpIni

Dla testu ustawia wartości konfiguracyjne INI. Zapisujemy na przykład jako @phpIni precision=20 i działa tak samo, jakbyśmy podali wartość z wiersza poleceń przez parametr -d precision=20.