Apêndice B. Anotações

Uma anotação é uma forma especial de metadados sintáticos que podem ser adicionados ao código-fonte de algumas linguagens de programação. Enquanto o PHP não tem um recurso de linguagem dedicado a anotação de código-fonte, o uso de tags como @annotation arguments em bloco de documentação tem sido estabelecido na comunidade do PHP para anotar o código-fonte. Os blocos de documentação PHP são reflexivos: eles podem ser acessados através do método da API de Reflexão getDocComment() a nível de função, classe, método e atributo. Aplicações como o PHPUnit usam essa informação em tempo de execução para configurar seu comportamento.

Este apêndice mostra todas as variedades de anotações suportadas pelo PHPUnit.

@author

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.

@backupGlobals

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()
    {
        // ...
    }
}

@backupStaticAttributes

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()
    {
        // ...
    }
}

@codeCoverageIgnore*

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”.

@covers

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 B.1 mostra a sintaxe da anotação @covers.

Tabela B.1. Anotações para especificar quais métodos são cobertos por um teste

AnotaçãoDescrição
@covers ClassName::methodNameEspecifica que o método de teste anotado cobre o método especificado.
@covers ClassNameEspecifica que o método de teste anotado cobre todos os métodos de uma dada classe.
@covers ClassName<extended>Especifica que o método de teste anotado cobre todos os métodos de uma dada classe e sua(s) classe(s) pai(s) e interface(s).
@covers ClassName::<public>Especifica que o método de teste anotado cobre todos os métodos públicos de uma dada classe.
@covers ClassName::<protected>Especifica que o método de teste anotado cobre todos os métodos protegidos de uma dada classe.
@covers ClassName::<private>Especifica que o método de teste anotado cobre todos os métodos privados de uma dada classe.
@covers ClassName::<!public>Especifica que o método de teste anotado cobre todos os métodos que não sejam públicos de uma dada classe.
@covers ClassName::<!protected>Especifica que o método de teste anotado cobre todos os métodos que não sejam protegidos de uma dada classe.
@covers ClassName::<!private>Especifica que o método de teste anotado cobre todos os métodos que não sejam privados de uma dada classe.
@covers ::functionNameEspecifica que o método de teste anotado cobre todos os métodos que não sejam privados de uma dada classe.


@coversNothing

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 14.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.

@dataProvider

Um método de teste pode aceitar argumentos arbitrários. Esses argumentos devem ser fornecidos por um método provedor (provider() em Exemplo 4.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.

@depends

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 4.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.

@expectedException

Exemplo 4.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.

@expectedExceptionCode

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;
}

@expectedExceptionMessage

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”.

@group

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.

@requires

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 9.3

@runTestsInSeparateProcesses

@runInSeparateProcess

@test

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());
}

@testdox

@ticket

Please open a ticket on GitHub to suggest improvements to this page. Thanks!