Cobertura de Código em PHP: Métricas, Ferramentas e Dicas Práticas

O paradoxo do testador: 100% de cobertura não é uma panaceia

Os desenvolvedores se dividem em dois grupos: os que escrevem testes "só para constar" e os que perseguem os cobiçados 100% de cobertura de código. A verdade, como sempre, está no meio-termo. Neste artigo, vamos explorar o que é cobertura de código em PHP, quais métricas realmente importam e quais podem enganar você. Você descobrirá como usar PHPUnit, Xdebug e Infection para transformar os testes de uma tarefa chata em uma ferramenta poderosa de controle de qualidade.

Vamos deixar claro desde já: este artigo não é sobre "como escrever um teste", mas sobre como entender se seus testes estão funcionando de verdade. Vamos falar na linguagem dos números, métricas e exemplos reais. Se você programa em PHP e quer que seu código não quebre na primeira alteração, está no lugar certo.

O que é cobertura de código (Code Coverage) de verdade?

Cobertura de código é uma métrica que mostra qual porcentagem do código-fonte original é executada durante a execução dos testes. Parece simples, mas por trás desse número existem diferentes níveis de análise:

\n
• Cobertura de linhas (Line Coverage) — a métrica mais básica. Quantas linhas de código são "tocadas" pelos testes.
\n
• Cobertura de ramificações (Branch Coverage) — verifica se todos os caminhos possíveis de condições (if/else, switch) foram executados.
\n
• Cobertura de caminhos (Path Coverage) — a métrica mais complexa. Verifica todas as rotas possíveis de execução do código.
\n
• Cobertura de funções/métodos — quantas funções foram chamadas pelo menos uma vez.
\n

Para o desenvolvedor PHP, o padrão ouro é a cobertura de linhas + ramificações. Mas lembre-se: 80% de cobertura de linhas podem esconder 40% de ramificações não testadas. O código pode ser "executado", mas a lógica pode não ter sido testada.

Por que 100% de cobertura é uma armadilha?

Imagine uma função que processa pagamentos:

<?php\n\nfunction processPayment(float $amount, string $currency): bool {\n    if ($amount <= 0) {\n        throw new InvalidArgumentException('O valor deve ser positivo');\n    }\n    \n    $rate = getRate($currency); // API externa\n    $converted = $amount * $rate;\n    \n    if ($converted > 10000) {\n        return false; // requer confirmação\n    }\n    \n    return saveTransaction($converted); // gravação no BD\n}\n

Um teste que verifica apenas o cenário de sucesso (valor > 0, moeda USD, conversão < 10000) vai te dar 100% de cobertura de linhas. Mas ele não vai testar nem a exceção, nem o caso de pagamento alto. Conclusão: a quantidade de linhas cobertas não equivale à qualidade dos testes.

Ferramentas para medir cobertura em PHP

O ecossistema PHP oferece várias ferramentas poderosas. Vamos ver as três principais: Xdebug, PCOV e PHPUnit com suporte nativo a cobertura.

Xdebug: o veterano com amplas funcionalidades

Xdebug é o depurador e profileador mais popular para PHP. Ele também coleta dados de cobertura de código. A instalação é padrão:

# Instalação via pecl\npecl install xdebug\n\n# Ou via Docker\nRUN pecl install xdebug && docker-php-ext-enable xdebug\n

No php.ini, é preciso ativar o modo de cobertura:

xdebug.mode=coverage\n

Executando com PHPUnit:

./vendor/bin/phpunit --coverage-html ./reports/coverage\n

Pontos positivos do Xdebug: precisão, suporte a ramificações, integração com CI/CD. Pontos negativos: deixa a execução dos testes 3 a 5 vezes mais lenta. Para projetos grandes, isso é crítico.

PCOV: rápido e leve

PCOV (PHP Code Coverage) é uma alternativa ao Xdebug, criada especificamente para coletar cobertura. Ela não deixa a execução lenta, pois não inclui um depurador.

pecl install pcov\n\n# Ativação no php.ini\nextension=pcov.so\npcov.enabled=1\n

Execução