Anotações de teste
******************

.[perex]
As anotações determinam como os testes serão tratados pelo [corredor de teste da linha de comando |running-tests]. Elas são escritas no início do arquivo de teste.

As anotações são insensíveis a maiúsculas e minúsculas. Elas também não têm efeito se o teste for executado manualmente como um script PHP regular.

Exemplo:

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

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


TEST .[filter]
--------------
Na verdade, não é uma anotação. Ela apenas define o título do teste que é impresso em caso de falha ou em registros.


@skip .[filter]
---------------
O teste é pulado. É útil para a desativação temporária do teste.


@phpVersion .[filter]
---------------------
O teste é pulado se não for executado pela versão PHP correspondente. Nós escrevemos anotações como `@phpVersion [operator] version`. Podemos deixar de fora o operador, o padrão é `>=`. Exemplos:

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


@phpExtensão .[filter]
----------------------
O teste é pulado se todas as extensões PHP mencionadas não forem carregadas. As extensões múltiplas podem ser escritas em uma única anotação, ou podemos usar a anotação várias vezes.

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


@dataProvider .[filter]
-----------------------
Esta anotação serve quando queremos fazer o teste várias vezes, mas com dados diferentes. (Não confundir com a anotação com o mesmo nome para [TestCase |TestCase#dataProvider]).

Escrevemos anotações como `@dataProvider file.ini`. O caminho do arquivo INI é relativo ao arquivo de teste. O teste é executado tantas vezes quanto o número de seções contidas no arquivo INI. Vamos supor que o arquivo 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:"
```

e o arquivo `database.phpt` no mesmo diretório:

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

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

O teste será executado três vezes e `$args` conterá valores das seções `mysql`, `postgresql` ou `sqlite`.

Há mais uma variação quando escrevemos anotações com um ponto de interrogação como `@dataProvider? file.ini`. Neste caso, o teste é pulado se o arquivo INI não existir.

As possibilidades de anotação ainda não foram todas mencionadas. Podemos escrever condições após o arquivo INI. Os testes para a seção dada só serão realizados se todas as condições coincidirem. Vamos estender o arquivo 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:"
```

e usaremos anotações com condições:

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

O teste é executado apenas uma vez para a seção `postgresql 9.1`. As outras seções não correspondem às condições.

Da mesma forma, podemos passar para um script PHP ao invés de INI. Ele deve retornar array ou Traversable. Arquivo `databases.php`:

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

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


@multiple .[filter]
-------------------
Escrevemos como `@multiple N` onde `N` é um número inteiro. O teste é exatamente N-times.


@testCase .[filter]
-------------------
A anotação não tem parâmetros. Nós a usamos quando escrevemos um teste como classes [TestCase |TestCase]. Neste caso, o executor do teste de linha de comando executará os métodos individuais em processos separados e em paralelo em várias roscas. Isto pode acelerar significativamente todo o processo de teste.


@exitCode .[filter]
-------------------
Escrevemos como `@exitCode N` onde `N` is the exit code of the test. For example if `exit(10)` é chamado no teste, escrevemos a anotação como `@exitCode 10`. É considerado reprovado se o teste terminar com um código diferente. O código de saída 0 (zero) é verificado se deixarmos de fora a anotação


@httpCode .[filter]
-------------------
A anotação é avaliada somente se o binário PHP for CGI. É ignorado de outra forma. Nós a escrevemos como `@httpCode NNN` onde se espera que `NNN` seja o código HTTP. O código HTTP 200 é verificado se deixarmos de fora a anotação. Se escrevermos `NNN` como uma string avaliada como zero, por exemplo `any`, o código HTTP não é verificado de forma alguma.


@outputMatch a @outputMatchFile .[filter]
-----------------------------------------
O comportamento das anotações é consistente com as afirmações `Assert::match()` e `Assert::matchFile()`. Mas o padrão é encontrado na saída padrão do teste. Um caso de uso adequado é quando assumimos que o teste termina por erro fatal e precisamos verificar seu resultado.


@phpIni .[filter]
-----------------
Define os valores de configuração INI para teste. Por exemplo, nós o escrevemos como `@phpIni precision=20` e funciona da mesma forma como se passássemos o valor da linha de comando pelo parâmetro `-d precision=20`.