Anotações de Teste

As anotações determinam como os testes serão tratados pelo executor de testes da linha de comando. Elas são escritas no início do arquivo de teste.

As anotações não diferenciam maiúsculas de minúsculas. Elas também não têm efeito se o teste for executado manualmente como um script PHP comum.

Exemplo:

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

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

TEST

Na verdade, isso nem é uma anotação, apenas define o título do teste, que é exibido em caso de falha ou no log.

@skip

O teste é pulado. É útil para desativar temporariamente os testes.

@phpVersion

O teste é pulado se não for executado com a versão correspondente do PHP. Escrevemos a anotação como @phpVersion [operador] versão. Podemos omitir o operador, o padrão é >=. Exemplos:

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

@phpExtension

O teste é pulado se todas as extensões PHP especificadas não estiverem carregadas. Podemos especificar várias extensões em uma anotação ou usá-la várias vezes.

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

@dataProvider

Se quisermos executar o arquivo de teste várias vezes, mas com dados de entrada diferentes, esta anotação é útil. (Não confunda com a anotação de mesmo nome para TestCase.)

Escrevemos como @dataProvider file.ini, o caminho para o arquivo é relativo ao arquivo de teste. O teste será executado tantas vezes quantas seções houver no arquivo INI. Suponha o arquivo 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:"

e no mesmo diretório, o teste database.phpt:

/**
 * @dataProvider databases.ini
 */

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

O teste será executado três vezes e $args conterá sempre os valores da seção mysql, postgresql ou sqlite.

Existe ainda uma variante onde escrevemos a anotação com um ponto de interrogação como @dataProvider? file.ini. Neste caso, o teste é pulado se o arquivo INI não existir.

As possibilidades da anotação não terminam aqui. Após o nome do arquivo INI, podemos especificar condições sob as quais o teste será executado para a seção correspondente. Estenderemos o arquivo 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:"

e usaremos a anotação com condição:

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

O teste será executado apenas uma vez e para a seção postgresql 9.1. As outras seções não passarão pelo filtro da condição.

Da mesma forma, em vez de um arquivo INI, podemos referenciar um script PHP. Ele deve retornar um array ou Traversable. Arquivo databases.php:

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

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

@multiple

Escrevemos como @multiple N, onde N é um número inteiro. O teste será executado exatamente N vezes.

@testCase

A anotação não tem parâmetros. Usamos quando escrevemos testes como classes TestCase. Nesse caso, o executor de testes da linha de comando executará os métodos individuais em processos separados e em paralelo em múltiplas threads. Isso pode acelerar significativamente todo o processo de teste.

@exitCode

Escrevemos como @exitCode N, onde N é o código de retorno do teste executado. Se, por exemplo, exit(10) for chamado no teste, escrevemos a anotação como @exitCode 10 e se o teste terminar com um código diferente, é considerado uma falha. Se a anotação não for especificada, o código de retorno 0 (zero) é verificado.

@httpCode

A anotação se aplica apenas se o binário PHP for CGI. Caso contrário, é ignorada. Escrevemos como @httpCode NNN onde NNN é o código HTTP esperado. Se a anotação não for especificada, o código HTTP 200 é verificado. Se NNN for escrito como uma string avaliada como zero, por exemplo, any, o código HTTP não é verificado.

@outputMatch e @outputMatchFile

A função das anotações é idêntica às asserções Assert::match() e Assert::matchFile(). O padrão (pattern), no entanto, é procurado no texto que o teste enviou para sua saída padrão. Encontra aplicação se supormos que o teste terminará com um erro fatal e precisarmos verificar sua saída.

@phpIni

Define valores de configuração INI para o teste. Escrevemos, por exemplo, como @phpIni precision=20 e funciona da mesma forma como se tivéssemos especificado o valor a partir da linha de comando através do parâmetro -d precision=20.