Anotaciones de prueba
*********************

.[perex]
Las anotaciones determinan cómo serán manejadas las pruebas por [el ejecutor de pruebas de línea de comandos |running-tests]. Se escriben al principio del archivo de prueba.

Las anotaciones no distinguen entre mayúsculas y minúsculas. Tampoco tienen efecto si la prueba se ejecuta manualmente como un script PHP normal.

Ejemplo:

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

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


TEST .[filter]
--------------
En realidad no es una anotación. Sólo establece el título de la prueba que se imprime al fallar o en los registros.


@skip .[filter]
---------------
Se omite la prueba. Es útil para la desactivación temporal de la prueba.


@phpVersion .[filter]
---------------------
La prueba es omitida si no es ejecutada por la versión PHP correspondiente. Escribimos la anotación como `@phpVersion [operator] version`. Podemos omitir el operador, por defecto es `>=`. Ejemplos:

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


@phpExtension .[filter]
-----------------------
La prueba se salta si todas las extensiones PHP mencionadas no están cargadas. Múltiples extensiones pueden ser escritas en una sola anotación, o podemos usar la anotación múltiples veces.

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


@dataProvider .[filter]
-----------------------
Esta anotación es adecuada cuando queremos ejecutar la prueba varias veces pero con datos diferentes. (No confundir con la anotación del mismo nombre para [TestCase |TestCase#dataProvider]).

Escribimos la anotación como `@dataProvider file.ini`. La ruta del archivo INI es relativa al archivo de prueba. La prueba se ejecuta tantas veces como secciones contenga el archivo INI. Supongamos que el archivo INI `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:"
```

y el fichero `database.phpt` en el mismo directorio:

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

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

La prueba se ejecuta tres veces y `$args` contendrá valores de las secciones `mysql`, `postgresql` o `sqlite`.

Hay una variación más cuando escribimos anotaciones con un signo de interrogación como `@dataProvider? file.ini`. En este caso, la prueba se salta si el archivo INI no existe.

Aún no se han mencionado todas las posibilidades de anotación. Podemos escribir condiciones después del archivo INI. La prueba se ejecuta para la sección dada sólo si todas las condiciones coinciden. Vamos a ampliar el archivo 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:"
```

y utilizaremos la anotación con la condición:

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

La prueba se ejecuta sólo una vez para la sección `postgresql 9.1`. Las demás secciones no cumplen las condiciones.

Del mismo modo, podemos pasar la ruta a un script PHP en lugar de INI. Debe devolver array o Traversable. Archivo `databases.php`:

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

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


@multiple .[filter]
-------------------
Lo escribimos como `@multiple N` donde `N` es un número entero. La prueba se ejecuta exactamente N veces.


@testCase .[filter]
-------------------
La anotación no tiene parámetros. La utilizamos cuando escribimos una prueba como clases [TestCase]. En este caso, el ejecutor de pruebas de línea de comandos ejecutará los métodos individuales en procesos separados y en paralelo en múltiples hilos. Esto puede acelerar significativamente todo el proceso de prueba.


@exitCode .[filter]
-------------------
Lo escribimos como `@exitCode N` donde `N` is the exit code of the test. For example if `exit(10)` es llamado en la prueba, escribimos la anotación como `@exitCode 10`. Se considera que falla si la prueba termina con un código diferente. El código de salida 0 (cero) se verifica si omitimos la anotación


@httpCode .[filter]
-------------------
La anotación es evaluada sólo si el binario PHP es CGI. En caso contrario, se ignora. Lo escribimos como `@httpCode NNN` donde `NNN` es el código HTTP esperado. El código HTTP 200 se verifica si omitimos la anotación. Si escribimos `NNN` como una cadena evaluada como cero, por ejemplo `any`, el código HTTP no es verificado en absoluto.


@outputMatch a @outputMatchFile .[filter]
-----------------------------------------
El comportamiento de las anotaciones es coherente con las aserciones `Assert::match()` y `Assert::matchFile()`. Pero el patrón se encuentra en la salida estándar de la prueba. Un caso de uso adecuado es cuando suponemos que la prueba finaliza por error fatal y necesitamos verificar su salida.


@phpIni .[filter]
-----------------
Establece valores de configuración INI para el test. Por ejemplo lo escribimos como `@phpIni precision=20` y funciona de la misma manera que si pasáramos el valor desde la línea de comandos por el parámetro `-d precision=20`.