Anotaciones de pruebas

Las anotaciones determinan cómo tratará las pruebas el ejecutor de pruebas desde la línea de comandos. Se escriben al principio del archivo con la prueba.

En las anotaciones no se distingue entre mayúsculas y minúsculas. Tampoco tienen ningún efecto si la prueba se ejecuta manualmente como un script PHP normal.

Ejemplo:

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

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

TEST

Esto en realidad ni siquiera es una anotación, solo determina el título de la prueba, que se imprime en caso de fallo o en el log.

@skip

La prueba se omite. Es útil para deshabilitar temporalmente las pruebas.

@phpVersion

La prueba se omite si no se ejecuta con la versión de PHP correspondiente. La anotación la escribimos como @phpVersion [operador] versión. Podemos omitir el operador, el predeterminado es >=. Ejemplos:

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

@phpExtension

La prueba se omite si no están cargadas todas las extensiones PHP indicadas. Podemos indicar múltiples extensiones en una anotación, o usarla varias veces.

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

@dataProvider

Si queremos ejecutar el archivo de prueba varias veces, pero con diferentes datos de entrada, esta anotación es útil. (No confundir con la anotación del mismo nombre para TestCase.)

La escribimos como @dataProvider file.ini, la ruta al archivo se toma relativa al archivo con la prueba. La prueba se ejecutará tantas veces como secciones haya en el archivo INI. Supongamos el archivo 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:"

y en el mismo directorio la prueba database.phpt:

/**
 * @dataProvider databases.ini
 */

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

La prueba se ejecutará tres veces y $args contendrá siempre los valores de la sección mysql, postgresql o sqlite.

Existe aún una variante donde escribimos la anotación con un signo de interrogación como @dataProvider? file.ini. En este caso, la prueba se omitirá si el archivo INI no existe.

Con esto no terminan las posibilidades de la anotación. Después del nombre del archivo INI podemos especificar las condiciones bajo las cuales se ejecutará la prueba para la sección dada. Ampliemos el archivo 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 usemos la anotación con condición:

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

La prueba se ejecutará solo una vez y para la sección postgresql 9.1. Las demás secciones no pasarán el filtro de la condición.

De manera similar, en lugar de un archivo INI podemos referenciar un script PHP. Este debe devolver un array o Traversable. Archivo databases.php:

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

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

@multiple

Lo escribimos como @multiple N, donde N es un número entero. La prueba se ejecutará exactamente N veces.

@testCase

La anotación no tiene parámetros. La usamos si escribimos las pruebas como clases TestCase. En ese caso, el ejecutor de pruebas desde la 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

Lo escribimos como @exitCode N, donde N es el código de retorno de la prueba ejecutada. Si en la prueba se llama, por ejemplo, a exit(10), escribimos la anotación como @exitCode 10 y si la prueba termina con otro código, se considera un fallo. Si no indicamos la anotación, se verifica el código de retorno 0 (cero).

@httpCode

La anotación solo se aplica si el binario PHP es CGI. De lo contrario, se ignora. La escribimos como @httpCode NNN donde NNN es el código HTTP esperado. Si no indicamos la anotación, se verifica el código HTTP 200. Si NNN lo escribimos como una cadena evaluada a cero, por ejemplo any, el código HTTP no se verifica.

@outputMatch y @outputMatchFile

La función de las anotaciones es idéntica a las aserciones Assert::match() y Assert::matchFile(). Pero el patrón se busca en el texto que la prueba envió a su salida estándar. Encuentra aplicación si suponemos que la prueba terminará con un error fatal y necesitamos verificar su salida.

@phpIni

Para la prueba establece valores de configuración INI. Lo escribimos, por ejemplo, como @phpIni precision=20 y funciona igual que si hubiéramos especificado el valor desde la línea de comandos a través del parámetro -d precision=20.