Relatório de cobertura de testes (Code Coverage) com o PHPUnit

O PHPUnit é um framework para a criação de testes unitários. Ele possui uma série de recursos que ajudam o desenvolvedor a criar uma suíte de teste eficiente. Hoje vamos falar sobre Code Coverage.

Curso PHP - Testes unitários com PHPUnit

Conhecer o curso

Instalação

O php-code-coverage é um módulo nativo do PHPUnit. Se você verificar no arquivo composer.json do PHPUnit ele é uma dependência:

https://github.com/sebastianbergmann/phpunit/blob/5.7/composer.json#L26

"phpunit/php-code-coverage": "^4.0.3",

Além do pacote acima (que já vem instalado por padrão), é necessário apenas ativar o XDebug, caso ele já não esteja ativo no seu PHP. É possível até utilizar o phpdbg como alternativa, caso você tenha uma grande quantidade de testes e o desempenho do XDebug deixe a desejar.

Gerar o relatório de cobertura

Para gerar o relatório de cobertura de testes precisamos usar o binário do PHPUnit. O comando é bem simples, veja a sintaxe:

phpunit --whitelist diretório-arquivos-projeto --tipo-de-saída local-saída 

É possível gerar diferentes tipos de saída:

--coverage-clover <file> Gera relatório no formato Clover (https://www.atlassian.com/software/clover).
--coverage-crap4j <file> Gera relatório no formato Crap4J (http://www.crap4j.org/).
--coverage-html   <dir>  Gera relatório visual no formato HTML
--coverage-php    <file> Exporta PHP_CodeCoverage objetos para arquivo.
--coverage-text=<file>   Gera o relatório no formato texto simples.
--coverage-xml    <dir>  Gera o relatório no padrão XML do próprio PHPUnit.

Veja um exemplo real do comando acima:

vendor/bin/phpunit --whitelist src/ --coverage-html cover/

Abrindo o relatório

Se executar o comando com a opção para gerar o relatório em HTML, dentro do diretório gerado terá uma série de arquivos .html, o principal é o index.html. Ao abri-lo uma listagem é exibida com o nome dos arquivos do projeto:

Nessa tabela padrão são exibidas 3 métricas para ajudar a entender o nível de cobertura dos testes:

• Lines: Quantidade de linhas executáveis em cada arquivo e quantas linhas foram testadas.
• Functions e Methods: Quantidade de funções e métodos no arquivo e quantos foram testados. Só é considerado coberto um método que possui teste para todas as linhas executáveis.
• Classes and Traits: Quantidade de classes e traits do arquivo, e quantas foram testadas. Só é considerada testada uma classe ou trait se todos os métodos foram cobertos.

Ao clicar sobre um arquivo é possível ver todos os detalhes sobre ele, inclusive a cobertura linha-a-linha:

Formação Desenvolvedor PHP

Conhecer a formação

Ignorando partes

Por motivos diversos pode ser necessário ignorar desde partes isoladas do código-fonte até métodos e classes inteiras, para isso basta usar anotações especificas, por exemplo:

Ignorando uma classe completa:

/**
 * @codeCoverageIgnore
 */
class Foo
{
    public function bar()
    {
    }
}

Ignorando um método:

class Bar
{
    /**
     * @codeCoverageIgnore
     */
    public function foo()
    {
    }
}

Ignorando um trecho de código:

if (FALSE) {
    // @codeCoverageIgnoreStart
    print '*';
    // @codeCoverageIgnoreEnd
}

Conclusão

O relatório de cobertura de testes é uma grande ferramenta, principalmente para quem está começando com testes, mas ele não deve ser levado de forma radical na busca de 100% de cobertura. Outro detalhe importante é que esse relatório pode levar a uma falsa confiança de que todos os casos estão cobertos (o que normalmente não é verdade), por isso não se deve confiar cegamente nele.