08 — Testes e Qualidade¶
A qualidade da PyCobrança é sustentada por dois pilares: testes automatizados e lint/format consistentes, verificados na CI a cada mudança.
Estratégia de testes¶
| Nível | Escopo | Ferramenta |
|---|---|---|
| Unitário | dígitos verificadores, datas, documentos, linha/barra | pytest |
| Por banco | valores conhecidos de linha digitável e código de barras | pytest + parametrização |
| CNAB | remessa byte-a-byte, parsing de retorno | pytest + fixtures |
| Valores-limite | cada campo de cada banco sem dados, com 1 caractere, no máximo declarado e máximo+1; agência, conta e nosso número em todos os tamanhos — no boleto e na remessa | pytest + parametrização |
| PIX | payload EMV, CRC16, QR Code | pytest |
| Contrato | artefatos vs. OpenAPI (contrato REST) | pytest |
| Renderização | geração de PDF sem erro, presença de elementos | pytest |
| Exemplos | os scripts de examples/ rodam ponta a ponta |
examples/executa_todos.py |
A leitura voltada para quem está avaliando adotar a biblioteca — método de verificação, paridade com a BrCobrança e como reproduzir — está em 17 — Compatibilidade e validação.
Fixtures de referência¶
Arquivos de referência (código de barras, linha digitável, remessa e retorno) são a fonte primária de fixtures. Cada banco portado deve trazer ao menos:
- Um caso de boleto com linha digitável e código de barras conhecidos.
- Fixtures de remessa (quando houver CNAB) para comparação byte-a-byte.
- Fixtures de retorno para validar o mapeamento de ocorrências.
Fixture prova menos do que parece. Ela prende a saída de hoje para um conjunto de dados; se a implementação de referência erra, a fixture congela o erro junto — foi o que aconteceu com quatro remessas que saíam fora de 400/240 posições. Por isso cada camada é conferida também contra algo que não vem da referência: o manual do banco (posição a posição), o invariante do formato (25 posições no campo livre, 400/240 no registro) e um verificador FEBRABAN independente, que reimplementa as regras do zero. A procedência de cada fixture está em
docs/bancos/README.md.
Ferramentas de qualidade¶
| Ferramenta | Papel |
|---|---|
| pytest | Execução de testes. |
| ruff | Lint + formatação (rápido, substitui flake8/isort/black). |
| coverage / pytest-cov | Cobertura. |
| build | Verificação de empacotamento (PEP 517). |
Configuração centralizada em pyproject.toml.
Comandos locais¶
# instalar dependências de desenvolvimento
pip install -e ".[dev]"
# rodar testes
pytest
# rodar com cobertura
pytest --cov=pycobranca --cov-report=term-missing
# lint e formatação
ruff check .
ruff format --check .
# exemplos executáveis (documentação que não envelhece)
python examples/executa_todos.py
# verificar build do pacote
python -m build
Exemplos como teste de fumaça¶
examples/ reúne scripts curtos que exercitam a API pública — boleto, Bolepix, remessa 400/240,
retorno, OFX, carnê, fatura, contrato REST e tratamento de erros. A CI executa todos a cada push
(job Exemplos executáveis), instalando o pacote sem as dependências de desenvolvimento:
quebra de API pública, dado de exemplo defasado ou arquivo faltando no wheel aparecem ali antes de
chegar ao usuário.
Metas de cobertura¶
- Núcleo (
core/,boleto/): cobertura ≥ 80%. - Cada banco/layout portado entra com testes; sem regressão de cobertura.
- Ampliação contínua da suíte.
Critérios para aceitar uma mudança¶
- CI verde em toda a matriz Python.
- Testes cobrindo o comportamento novo (e as fixtures de referência intactas).
- Cobertura dentro da meta.
- Documentação atualizada para o recurso entregue.