Cobertura e Relatórios
Cobertura mede quais linhas seus testes executam. Ela revela branches não testados, não a qualidade do teste - use-a para encontrar lacunas, não apenas como uma métrica de qualidade.
Receita
uv add --group dev pytest-cov
uv run pytest --cov=src --cov-report=term-missingQuando usar isso:
- Identificar caminhos de código não testados antes do lançamento
- Exigir cobertura mínima em CI
- Gerar relatórios HTML para revisão
Exemplo de Trabalho
[tool.pytest.ini_options]
addopts = "--cov=src --cov-report=term-missing --cov-fail-under=80"
[tool.coverage.run]
source = ["src"]
branch = true
omit = ["*/tests/*", "*/__main__.py"]
[tool.coverage.report]
show_missing = true
skip_covered = falseuv run pytest
# Nome Stmts Miss Branch BrPart Cover
# src/myapp/billing.py 42 3 12 2 91%uv run pytest --cov=src --cov-report=html
open htmlcov/index.htmlO que isso demonstra:
--cov=srcmede o pacote instalado, não os testesbranch = truerastreia caminhos if/else--cov-fail-under=80bloqueia CI abaixo do limite- O relatório HTML destaca linhas não cobertas em vermelho
Análise Profunda
Lendo o Relatório
| Coluna | Significado |
|---|---|
| Stmts | Declarações executáveis |
| Miss | Declarações nunca executadas |
| Branch | Branches condicionais |
| BrPart | Branches parcialmente cobertos |
O que a Cobertura Perde
- Asserções corretas (100% de cobertura com testes errados)
- Falhas de integração
- Bugs de concorrência
- Violações de contrato de API
Armadilhas
- Perseguir 100% de cobertura - testes não afirmam nada significativo. Correção: alvo de 80-90%; foque em caminhos críticos.
- Cobertura em
tests/- números inflados. Correção: use apenas--cov=src. - Sem cobertura de branch - branches
elseperdidos. Correção:branch = truena configuração de cobertura. - Portão de cobertura sem revisão - branches importantes ignorados. Correção: combine o limite com a revisão de PR da saída
term-missing. - Código gerado na cobertura - alvos impossíveis. Correção:
omitmigrações e arquivos gerados.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| teste de mutação (mutmut) | Auditoria de qualidade de teste | Busca rápida de lacunas |
| diff-cover | Cobertura com escopo de PR | Auditoria completa do projeto |
| Nenhuma ferramenta de cobertura | Protótipo | Serviços de produção |
FAQs
Qual é um bom alvo de cobertura?
80% é um piso comum. Módulos críticos (cobrança, autenticação) devem ter um valor maior.
Cobertura significa bons testes?
Não. Ela apenas mostra linhas executadas. Combine com revisão e testes de mutação.
Como excluo linhas?
# pragma: no cover em código defensivamente inalcançável.
Como vejo branches não cobertos?
--cov-report=term-missing com branch = true.
Posso impor cobertura em CI?
--cov-fail-under=80 em addopts do pytest.
Como faço cobertura de um único módulo?
pytest --cov=src/myapp/billing.
O que é diff-cover?
Relata cobertura apenas em linhas alteradas. Bom para portões de PR.
Relatório HTML ou de terminal?
Terminal para CI. HTML para exploração local de lacunas.
Como combino cobertura de execuções paralelas?
coverage combine e depois coverage report após execuções de pytest-xdist.
Devo cobrir __init__.py?
Apenas se contiver lógica. Arquivos __init__.py vazios são omitidos.
Relacionados
- Configuração do pytest - configuração de addopts
- Melhores Práticas de Teste - política de cobertura
- Testes Baseados em Propriedades - cobertura de caminho mais profunda
- Linting em CI/CD - portões de CI
Versões da Stack: Esta página foi escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.