Test-Annotationen

Annotationen bestimmen, wie der Test-Runner auf der Kommandozeile mit den Tests umgeht. Sie werden an den Anfang der Testdatei geschrieben.

Bei Annotationen wird die Groß- und Kleinschreibung nicht unterschieden. Sie haben außerdem keine Wirkung, wenn der Test manuell als gewöhnliches PHP-Skript ausgeführt wird.

Beispiel:

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

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

TEST

Das ist eigentlich keine Annotation. Sie gibt nur den Titel des Tests an, der bei einem Fehlschlag oder in den Logs angezeigt wird.

@skip

Der Test wird übersprungen. Nützlich, um Tests vorübergehend abzuschalten.

@phpVersion

Der Test wird übersprungen, wenn er nicht mit der entsprechenden PHP-Version ausgeführt wird. Schreiben Sie die Annotation als @phpVersion [Operator] Version. Der Operator kann weggelassen werden; der Standard ist >=. Beispiele:

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

@phpExtension

Der Test wird übersprungen, wenn nicht alle angegebenen PHP-Extensions geladen sind. Mehrere Extensions können in einer Annotation aufgezählt werden, oder die Annotation lässt sich mehrfach verwenden.

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

@dataProvider

Diese Annotation ist nützlich, wenn Sie die Testdatei mehrfach mit unterschiedlichen Eingabedaten ausführen wollen. (Verwechseln Sie sie nicht mit der gleichnamigen Annotation für TestCase.)

Schreiben Sie sie als @dataProvider file.ini. Der Pfad zur Datei ist relativ zur Testdatei. Der Test wird so oft ausgeführt, wie die INI-Datei Sektionen hat. Nehmen wir die INI-Datei databases.ini an:

[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:"

und die Datei database.phpt im selben Verzeichnis:

/**
 * @dataProvider databases.ini
 */

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

Der Test läuft dreimal, und $args enthält jeweils die Werte aus der Sektion mysql, postgresql bzw. sqlite.

Es gibt noch eine Variante, bei der Sie die Annotation mit einem Fragezeichen schreiben: @dataProvider? file.ini. In diesem Fall wird der Test übersprungen, wenn die INI-Datei nicht existiert.

Die Möglichkeiten dieser Annotation enden hier nicht. Hinter dem Namen der INI-Datei können Sie Bedingungen angeben, die bestimmen, ob der Test für eine bestimmte Sektion läuft. Erweitern wir die INI-Datei:

[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:"

und verwenden die Annotation mit einer Bedingung:

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

Der Test läuft nur einmal, nämlich für die Sektion postgresql 9.1. Die übrigen Sektionen erfüllen den Bedingungsfilter nicht.

Ebenso können Sie statt einer INI-Datei auf ein PHP-Skript verweisen. Es muss ein Array oder ein Traversable-Objekt zurückgeben. Datei databases.php:

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

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

@multiple

Schreiben Sie sie als @multiple N, wobei N eine ganze Zahl ist. Der Test läuft genau N-mal.

@testCase

Diese Annotation hat keine Parameter. Verwenden Sie sie, wenn Sie Tests als TestCase-Klassen schreiben. Der Test-Runner auf der Kommandozeile führt die einzelnen Methoden dann in eigenen Prozessen und parallel in mehreren Threads aus. Das kann den gesamten Testvorgang deutlich beschleunigen.

@exitCode

Schreiben Sie sie als @exitCode N, wobei N der erwartete Exit-Code des Tests ist. Wird im Test zum Beispiel exit(10) aufgerufen, schreiben Sie die Annotation als @exitCode 10. Endet der Test mit einem anderen Code, gilt er als fehlgeschlagen. Fehlt die Annotation, wird der Exit-Code 0 (null) geprüft.

@httpCode

Diese Annotation gilt nur, wenn die PHP-Binary CGI ist; sonst wird sie ignoriert. Schreiben Sie sie als @httpCode NNN, wobei NNN der erwartete HTTP-Code ist. Fehlt die Annotation, wird der HTTP-Code 200 geprüft. Wird NNN als String geschrieben, der zu null ausgewertet wird (z. B. any), wird der HTTP-Code nicht geprüft.

@outputMatch und @outputMatchFile

Die Funktion dieser Annotationen ist identisch mit den Assertions Assert::match() und Assert::matchFile(). Das Muster wird jedoch in dem Text gesucht, den der Test an seine Standardausgabe gesendet hat. Das ist nützlich, wenn Sie erwarten, dass ein Test mit einem fatalen Fehler endet, und dessen Ausgabe prüfen müssen.

@phpIni

Setzt INI-Konfigurationswerte für den Test. Schreiben Sie sie zum Beispiel als @phpIni precision=20. Sie funktioniert genauso, als würden Sie den Wert auf der Kommandozeile mit dem Parameter -d precision=20 angeben.