Apêndice A. Anotações

A anotação @author é um apelido para a anotação @group (veja a seção chamada “@group”) e permite filtrar os testes baseado em seus autores.

As operações de backup e restauração para variáveis globais podem ser completamente desabilitadas para todos os testes de uma classe de caso de teste como esta:

/**
 * @backupGlobals disabled
 */
class MeuTest extends PHPUnit_Framework_TestCase
{
    // ...
}

A anotação @backupGlobals também pode ser usada a nível de método de teste. Isso permite uma configuração refinada das operações de backup e restauração:

/**
 * @backupGlobals disabled
 */
class MeuTest extends PHPUnit_Framework_TestCase
{
    /**
     * @backupGlobals enabled
     */
    public function testQueInterageComVariaveisGlobais()
    {
        // ...
    }
}

As operações de backup e restauração para atributos estáticos de classes podem ser completamente desabilitadas para todos os testes de uma classe de caso de teste como esta:

/**
 * @backupStaticAttributes disabled
 */
class MeuTest extends PHPUnit_Framework_TestCase
{
    // ...
}

A anotação @backupStaticAttributes também pode ser usada a nível de método de teste. Isso permite uma configuração refinada das operações de backup e restauração:

/**
 * @backupStaticAttributes disabled
 */
class MeuTest extends PHPUnit_Framework_TestCase
{
    /**
     * @backupStaticAttributes enabled
     */
    public function testQueInterageComAtributosEstaticos()
    {
        // ...
    }
}

As anotações @codeCoverageIgnore, @codeCoverageIgnoreStart e @codeCoverageIgnoreEnd podem ser usadas para excluir linhas de código da análise de cobertura.

Para uso, veja a seção chamada “Ignorando Blocos de Código”.

A anotação @covers pode ser usada no código de teste para especificar quais métodos um método de teste quer testar:

/**
 * @covers ContaBancaria::getSaldo
 */
public function testSaldoEhInicialmenteZero()
{
    $this->assertEquals(0, $this->cb->getSaldo());
}

Se fornecida, apenas a informação de cobertura de código para o(s) método(s) especificado(s) será considerada.

Tabela A.1 mostra a sintaxe da anotação @covers.

A anotação @coversNothing pode ser usada no código de teste para especificar que nenhuma informação de cobertura de código será gravada para o caso de teste anotado.

Isso pode ser usado para testes de integração. Veja Exemplo 10.3 para um exemplo.

A anotação pode ser usada nos níveis de classe e de método e vão sobrepujar quaisquer tags @covers.

Um método de teste pode aceitar argumentos arbitrários. Esses argumentos devem ser fornecidos por um método provedor (provider() em Exemplo 2.4). O método provedor de dados a ser usado é especificado usando a anotação @dataProvider.

Veja a seção chamada “Provedores de Dados” para mais detalhes.

O PHPUnit suporta a declaração de dependências explícitas entre métodos de teste. Tais dependências não definem a ordem em que os métodos de teste devem ser executados, mas permitem o retorno de uma instância do componente de teste por um produtor e passá-la aos consumidores dependentes. Exemplo 2.2 mostra como usar a anotação @depends para expressar dependências entre métodos de teste.

Veja a seção chamada “Dependências de Testes” para mais detalhes.

Exemplo 2.7 mostra como usar a anotação @expectedException para testar se uma exceção é lançada dentro do código testado.

Veja a seção chamada “Testando Exceções” para mais detalhes.

A anotação @expectedExceptionCode em conjunção com a @expectedException permite fazer asserções no código de erro de uma exceção lançada, permitindo diminuir uma exceção específica.

class MeuTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException MinhaExcecao
     * @expectedExceptionCode 20
     */
    public function testExcecaoTemCodigoErro20()
    {
        throw new MinhaExcecao('Alguma Mensagem', 20);
    }
}

Para facilitar o teste e reduzir a duplicação, um atalho pode ser usado para especificar uma constante de classe como uma @expectedExceptionCode usando a sintaxe "@expectedExceptionCode ClassName::CONST".

class MeuTest extends PHPUnit_Framework_TestCase
{
    /**
      * @expectedException MinhaExcecao
      * @expectedExceptionCode MyClass::ERRORCODE
      */
    public function testExcecaoTemCodigoErro20()
    {
      throw new MyException('Alguma Mensagem', 20);
    }
}
class MinhaClasse
{
    const ERRORCODE = 20;
}

A anotação @expectedExceptionMessage trabalha de modo similar a @expectedExceptionCode já que lhe permite fazer uma asserção na mensagem de erro de uma exceção.

class MeuTest extends PHPUnit_Framework_TestCase
{
    /**
     * @expectedException MinhaExcecao
     * @expectedExceptionMessage Alguma Mensagem
     */
    public function testExcecaoTemMensagemCerta()
    {
        throw new MinhaExcecao('Alguma Mensagem', 20);
    }
}

A mensagem esperada pode ser uma substring de uma Mensagem de exceção. Isso pode ser útil para assertar apenas que um certo nome ou parâmetro que foi passado é mostrado na exceção e não fixar toda a mensagem de exceção no teste.

class MeuTest extends PHPUnit_Framework_TestCase
{
     /**
      * @expectedException MinhaExcecao
      * @expectedExceptionMessage quebrado
      */
     public function testExcecaoTemMensagemCerta()
     {
         $param = "quebrado";
         throw new MinhaExcecao('Parâmetro Inválido "'.$param.'".', 20);
     }
}

Para facilitar o teste e reduzir duplicação um atalho pode ser usado para especificar uma constante de classe como uma @expectedExceptionMessage usando a sintaxe "@expectedExceptionMessage ClassName::CONST". Um exemplo pode ser encontrado na seção chamada “@expectedExceptionCode”.

Um teste pode ser marcado como pertencente a um ou mais grupos usando a anotação @group desta forma:

class MeuTest extends PHPUnit_Framework_TestCase
{
    /**
     * @group especificacao
     */
    public function testAlgumaCoisa()
    {
    }

    /**
     * @group regressao
     * @group bug2204
     */
    public function testOutraCoisa()
    {
    }
}

Testes podem ser selecionados para execução baseada em grupos usando os comutadores --group e --exclude-group do executor de teste em linha-de-comando ou usando as respectivas diretivas do arquivo de configuração XML.

A anotação @requires pode ser usada para pular testes quando pré-condição, como a Versão do PHP ou extensões instaladas, não batem.

Uma lista completa de possibilidades e exemplos pode ser encontrada em Tabela 7.3

Como uma alternativa para prefixar seus nomes de métodos de teste com test, você pode usar a anotação @test no Bloco de Documentação de um método para marcá-lo como um método de teste.

/**
 * @test
 */
public function saldoInicialDeveSer0()
{
    $this->assertEquals(0, $this->cb->getSaldo());
}