Capítulo 10. Análise de Cobertura de Código

 

A beleza de testar não se encontra no esforço, mas na eficiência.

Saber o que deveria ser testado é lindo, e saber o que está sendo testado é lindo.

 
 --Murali Nandigama

Neste capítulo você aprenderá tudo sobre a funcionalidade de cobertura de código do PHPUnit que lhe dará uma perspicácia sobre quais partes do código de produção são executadas quando os testes são executados. Isso ajuda a responder questões como:

  • Como você descobre o código que ainda não foi testado -- ou, em outras palavras, ainda não foi coberto por um teste?

  • Como você mede o quanto os testes estão completos?

Um exemplo sobre o quê podem significar as estatísticas de cobertura de código é que se existir um método com 100 linhas de código, e apenas 75 dessas linhas são realmente executadas quando os testes são executados, então considera-se que o método tem uma cobertura de código de 75 porcento.

A funcionalidade de cobertura de código do PHPUnit faz uso do componente PHP_CodeCoverage que por sua vez aproveita a funcionalidade da cobertura de declarações fornecida pela extensão Xdebug para PHP.

Deixe-nos gerar um relatório de cobertura de código para a classe ContaBancaria de ???.

phpunit --coverage-html ./report ContaBancariaTest
PHPUnit 3.8.0 by Sebastian Bergmann.

...

Time: 0 seconds

OK (3 tests, 3 assertions)

Generating report, this may take a moment.

Figura 10.1 mostra um resumo do relatório de Cobertura de Código. Linhas de código que foram executadas enquanto os testes executavam estão destacadas em verde, linhas de código que são executáveis mas não foram executadas estão destacadas em vermelho, e o "código morto" está destacado em cinza. O número à esquerda da linha de código atual indica quantos testes cobrem aquela linha.

Figura 10.1. Cobertura de Código para setSaldo()

Cobertura de Código para setSaldo()


Clicando no número da linha de uma linha coberta abrirá um painel (veja Figura 10.2) que mostra os casos de testes que cobrem esta linha.

Figura 10.2. Painel com informações sobre cobertura de testes

Painel com informações sobre cobertura de testes


O relatório de cobertura de código para nosso exemplo ContaBancaria mostra que não temos quaisquer testes ainda que chamem os métodos setBalance(), depositMoney(), e withdrawMoney() com valores legais. Exemplo 10.1 mostra um teste que pode ser adicionado à classe de caso de teste ContaBancariaTest para cobrir completamente a classe ContaBancaria.

Exemplo 10.1: Teste perdido para conseguir completa cobertura de código

<?php
require_once 'ContaBancaria.php';

class ContaBancariaTest extends PHPUnit_Framework_TestCase
{
// ...

public function testDepositarSacarDinheiro()
{
$this->assertEquals(0, $this->cb->getSaldo());
$this->cb->depositarDinheiro(1);
$this->assertEquals(1, $this->cb->getSaldo());
$this->cb->sacarDinheiro(1);
$this->assertEquals(0, $this->cb->getSaldo());
}
}
?>


Figura 10.3 mostra a cobertura de código para o método setSaldo() com o teste adicional.

Figura 10.3. Cobertura de Código para setSaldo() com teste adicional

Cobertura de Código para setSaldo() com teste adicional


Especificando métodos cobertos

A anotação @covers (veja Tabela A.1) pode ser usada em um código de teste para especificar qual(is) método(s) um método de teste quer testar. Se fornecido, apenas a informação de cobertura de código para o(s) método(s) especificado(s) será considerada. Exemplo 10.2 mostra um exemplo.

Exemplo 10.2: Testes que especificam quais métodos querem cobrir

<?php
require_once 'ContaBancaria.php';

class ContaBancariaTest extends PHPUnit_Framework_TestCase
{
protected $cb;

protected function setUp()
{
$this->cb = new ContaBancaria;
}

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

/**
* @covers ContaBancaria::sacarDinheiro
*/
public function testSaldoNaoPodeFicarNegativo()
{
try {
$this->cb->sacarDinheiro(1);
}

catch (ExcecaoContaBancaria $e) {
$this->assertEquals(0, $this->cb->getSaldo());

return;
}

$this->fail();
}

/**
* @covers ContaBancaria::depositarDinheiro
*/
public function testBalanceCannotBecomeNegative2()
{
try {
$this->cb->depositarDinheiro(-1);
}

catch (ExcecaoContaBancaria $e) {
$this->assertEquals(0, $this->cb->getSaldo());

return;
}

$this->fail();
}

/**
* @covers ContaBancaria::getSaldo
* @covers ContaBancaria::depositarDinheiro
* @covers ContaBancaria::sacarDinheiro
*/

public function testDepositarSacarDinheiro()
{
$this->assertEquals(0, $this->cb->getSaldo());
$this->cb->depositarDinheiro(1);
$this->assertEquals(1, $this->cb->getSaldo());
$this->cb->sacarDinheiro(1);
$this->assertEquals(0, $this->cb->getSaldo());
}
}
?>


Também é possível especificar que um teste não deve cobrir qualquer método usando a anotação @coversNothing (veja “@coversNothing”). Isso pode ser útil quando escrever testes de integração para certificar-se de que você só gerará cobertura de código com testes unitários.

Exemplo 10.3: Um teste que especifica que nenhum método deve ser coberto

<?php
class IntegracaoLivroDeVisitasTest extends PHPUnit_Extensions_Database_TestCase
{
/**
* @coversNothing
*/
public function testAdicionaEntrada()
{
$livrodevisitas = new LivroDeVisitas();
$livrodevisitas->adicionaEntrada("suzy", "Olá mundo!");

$tabelaQuery = $this->getConnection()->criarTabelaQuery(
'livrodevisitas', 'SELECT * FROM livrodevisitas'
);
$expectedTable = $this->criarConjuntoDadosXmlPlano("livroEsperado.xml")
->getTabela("livrodevisitas");
$this->assertTablesEqual($tabelaEsperada, $tabelaQuery);
}
}
?>
      


Ignorando Blocos de Código

Às vezes você tem blocos de código que não pode testar e que pode querer ignorar durante a análise de cobertura de código. O PHPUnit permite que você o faça usando as anotações @codeCoverageIgnore, @codeCoverageIgnoreStart e @codeCoverageIgnoreEnd como mostrado em Exemplo 10.4.

Exemplo 10.4: Usando as anotações @codeCoverageIgnore, @codeCoverageIgnoreStart e @codeCoverageIgnoreEnd

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

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

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


As linhas de código que estão marcadas para serem ignoradas usando as anotações são contadas como executadas (se forem executáveis) e não serão destacadas.

Incluindo e Excluindo Arquivos

Por padrão, todos os arquivos de código-fonte que contêm pelo menos uma linha de código que tenha sido executada (e apenas esses arquivos) são incluídos no relatório. Os arquivos de código-fonte que são incluídos no relatório podem ser filtrados usando uma abordagem de lista-negra ou lista-branca.

A lista-negra é pré-preenchida com todos os arquivos de código-fonte do próprio PHPUnit assim como os testes. Quando a lista-branca está vazia (padrão), a lista-negra é usada. Quando a lista-branca não está vazia, a lista-branca é usada. Cada arquivo na lista-branca é adicionado ao relatório de cobertura de código independentemente de ter sido executado ou não. Todas as linhas em tal arquivo, incluindo aquelas que não são executáveis, são contadas como não executadas.

Quando você define processUncoveredFilesFromWhitelist="true" na sua configuração do PHPUnit (veja “Incluindo e Excluindo Arquivos para Cobertura de Código”) então esses arquivos serão incluídos pelo PHP_CodeCoverage para calcular adequadamente o número de linhas executáveis.

Nota

Por favor, note que o carregamento de arquivos de código-fonte que é realizado quando processUncoveredFilesFromWhitelist="true" é definido pode causar problemas quando um arquivo de código-fonte contém código fora do escopo de uma classe ou função, por exemplo.

O arquivo de configuração XML do PHPUnit (veja “Incluindo e Excluindo Arquivos para Cobertura de Código”) pode ser usado para controlar as listas branca e negra. Usar uma lista-branca é a melhor prática recomendada para controlar a lista de arquivos incluídos no relatório de cobertura de código.

Casos Extremos

De modo geral é seguro dizer que o PHPUnit oferece a você uma informação de cobertura de código "baseada em linha", mas devido ao modo que a informação é coletada, existem alguns casos extremos dignos de atenção.

Exemplo 10.5:

<?php
// Por ser "baseado em linha" e não em declaração,
// uma linha sempre terá um estado de cobertura
if(false) esta_chamada_de_funcao_aparece_como_coberta();

// Devido ao modo que a cobertura de código funciona internamente,
// estas duas linhas são especiais.
// Esta linha vai aparecer como não-executável
if(false)
	// Esta linha vai aparecer como coberta, pois de fato é a cobertura
	// da declaração if da linha anterior que é mostrada aqui!
	tambem_vai_aparecer_como_coberta();

// Para evitar isso é necessário usar chaves
if(false){
	esta_chamada_nunca_aparecera_como_coberta();
}
?>


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