Anotaciones de pruebas

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

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

Ejemplo:

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

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

TEST

En realidad no es una anotación. Simplemente indica el título de la prueba, que se muestra en caso de fallo o en los registros.

@skip

La prueba se omite. Útil para desactivar pruebas temporalmente.

@phpVersion

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

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

@phpExtension

La prueba se omite si no están cargadas todas las extensiones de PHP indicadas. Se pueden enumerar varias extensiones en una sola anotación, o usar la anotación varias veces.

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

@dataProvider

Esta anotación es útil cuando quiere ejecutar el archivo de prueba varias veces con distintos datos de entrada. (No la confunda con la anotación del mismo nombre para TestCase.)

Escríbala como @dataProvider file.ini. La ruta del archivo es relativa al archivo de prueba. La prueba se ejecutará tantas veces como secciones tenga 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 el archivo database.phpt en el mismo directorio:

/**
 * @dataProvider databases.ini
 */

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

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

Existe otra variante en la que se escribe la anotación con un signo de interrogación: @dataProvider? file.ini. En ese caso, la prueba se omite si el archivo INI no existe.

Las posibilidades de esta anotación no acaban aquí. Tras el nombre del archivo INI puede indicar condiciones que determinan si la prueba se ejecuta para una sección concreta. 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 una condición:

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

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

De forma parecida, en lugar de un archivo INI puede referirse a un script PHP. Debe devolver un array o un objeto Traversable. Archivo databases.php:

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

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

@multiple

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

@testCase

Esta anotación no tiene parámetros. Úsela cuando escriba las pruebas como clases TestCase. En ese caso, el ejecutor de pruebas de la línea de comandos ejecutará los distintos métodos en procesos separados y en paralelo en varios hilos. Eso puede acelerar notablemente todo el proceso de pruebas.

@exitCode

Escríbala como @exitCode N, donde N es el código de salida esperado de la prueba. Por ejemplo, si en la prueba se llama a exit(10), escriba la anotación como @exitCode 10. Si la prueba termina con otro código, se considera un fallo. Si se omite la anotación, se verifica el código de salida 0 (cero).

@httpCode

Esta anotación se aplica solo si el binario de PHP es CGI; en caso contrario se ignora. Escríbala como @httpCode NNN, donde NNN es el código HTTP esperado. Si se omite la anotación, se verifica el código HTTP 200. Si NNN se escribe como una cadena que se evalúa a cero (p. ej. any), el código HTTP no se comprueba.

@outputMatch y @outputMatchFile

La función de estas anotaciones es idéntica a la de 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. Es útil cuando espera que una prueba termine con un error fatal y necesita verificar su salida.

@phpIni

Establece valores de configuración INI para la prueba. Escríbala, por ejemplo, como @phpIni precision=20. Funciona igual que si indicara el valor desde la línea de comandos con el parámetro -d precision=20.