Test-Anmerkungen
****************

.[perex]
Anmerkungen legen fest, wie die Tests von der [Befehlszeile des Testläufers |running-tests] behandelt werden sollen. Sie werden an den Anfang der Testdatei geschrieben.

Bei den Anmerkungen wird die Groß- und Kleinschreibung nicht berücksichtigt. Sie haben auch keine Auswirkungen, wenn der Test manuell als normales PHP-Skript ausgeführt wird.

Beispiel:

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

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


TEST .[filter]
--------------
Es handelt sich nicht um eine eigentliche Anmerkung. Er legt nur den Testtitel fest, der bei Fehlschlägen oder in Protokollen ausgegeben wird.


@skip .[filter]
---------------
Der Test wird übersprungen. Dies ist praktisch für die vorübergehende Deaktivierung von Tests.


@phpVersion .[filter]
---------------------
Der Test wird übersprungen, wenn er nicht mit der entsprechenden PHP-Version ausgeführt wird. Wir schreiben die Annotation als `@phpVersion [operator] version`. Wir können den Operator weglassen, Standard ist `>=`. Beispiele:

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


@phpExtension .[filter]
-----------------------
Der Test wird übersprungen, wenn nicht alle genannten PHP-Erweiterungen geladen sind. Mehrere Erweiterungen können in eine einzige Anmerkung geschrieben werden, oder wir können die Anmerkung mehrfach verwenden.

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


@dataProvider .[filter]
-----------------------
Diese Annotation eignet sich, wenn der Test mehrfach, aber mit unterschiedlichen Daten ausgeführt werden soll. (Nicht zu verwechseln mit der gleichnamigen Annotation für [TestCase |TestCase#dataProvider]).

Wir schreiben die Anmerkung als `@dataProvider file.ini`. Der Pfad der INI-Datei ist relativ zur Testdatei. Der Test wird so oft ausgeführt, wie die Anzahl der in der INI-Datei enthaltenen Abschnitte. Nehmen wir an, die INI-Datei `databases.ini`:

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

und die Datei `database.phpt` befinden sich im selben Verzeichnis:

```php
/**
 * @dataProvider databases.ini
 */

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

Der Test läuft dreimal und `$args` enthält Werte aus den Abschnitten `mysql`, `postgresql` oder `sqlite`.

Es gibt noch eine weitere Variante, wenn wir Anmerkungen mit einem Fragezeichen als `@dataProvider? file.ini` schreiben. In diesem Fall wird der Test übersprungen, wenn die INI-Datei nicht vorhanden ist.

Es wurden noch nicht alle Möglichkeiten für Anmerkungen erwähnt. Wir können Bedingungen hinter die INI-Datei schreiben. Der Test wird nur dann für den angegebenen Abschnitt ausgeführt, wenn alle Bedingungen erfüllt sind. Erweitern wir die INI-Datei:

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

und wir werden eine Anmerkung mit Bedingung verwenden:

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

Der Test läuft nur einmal für den Abschnitt `postgresql 9.1`. Andere Abschnitte erfüllen die Bedingungen nicht.

Auf ähnliche Weise können wir den Pfad zu einem PHP-Skript anstelle von INI übergeben. Es muss Array oder Traversable zurückgeben. Datei `databases.php`:

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

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


@multiple .[filter]
-------------------
Wir schreiben es als `@multiple N`, wobei `N` eine ganze Zahl ist. Der Test läuft genau N-mal.


@testCase .[filter]
-------------------
Die Annotation hat keine Parameter. Wir verwenden sie, wenn wir einen Test als [TestCase-Klassen |TestCase] schreiben. In diesem Fall führt der Befehlszeilen-Testrunner die einzelnen Methoden in separaten Prozessen und parallel in mehreren Threads aus. Dadurch kann der gesamte Testprozess erheblich beschleunigt werden.


@exitCode .[filter]
-------------------
Wir schreiben es als `@exitCode N`, wenn `N` is the exit code of the test. For example if `exit(10)` im Test aufgerufen wird, schreiben wir die Annotation als `@exitCode 10`. Wenn der Test mit einem anderen Code endet, gilt er als fehlgeschlagen. Der Exit-Code 0 (Null) wird verifiziert, wenn wir die Annotation weglassen


@httpCode .[filter]
-------------------
Der Vermerk wird nur ausgewertet, wenn das PHP-Binary CGI ist. Ansonsten wird sie ignoriert. Wir schreiben sie als `@httpCode NNN`, wobei `NNN` der erwartete HTTP-Code ist. Der HTTP-Code 200 wird überprüft, wenn wir die Anmerkung weglassen. Wenn wir `NNN` als String schreiben, der als Null ausgewertet wird, z. B. `any`, wird der HTTP-Code überhaupt nicht überprüft.


@outputMatch a @outputMatchFile .[filter]
-----------------------------------------
Das Verhalten der Annotationen ist konsistent mit den Assertionen `Assert::match()` und `Assert::matchFile()`. Das Muster wird jedoch in der Standardausgabe des Tests gefunden. Ein geeigneter Anwendungsfall ist, wenn wir davon ausgehen, dass der Test mit einem schwerwiegenden Fehler endet und wir seine Ausgabe überprüfen müssen.


@phpIni .[filter]
-----------------
Es setzt INI-Konfigurationswerte für den Test. Wir schreiben es zum Beispiel als `@phpIni precision=20` und es funktioniert genauso, wie wenn wir den Wert von der Kommandozeile mit dem Parameter `-d precision=20` übergeben.