Configuração do pytest
O pytest descobre e executa testes por convenção - nenhuma classe de teste boilerplate é necessária. Um diretório tests/, um bloco de configuração pyproject.toml e uv add --group dev pytest são suficientes para começar.
Receita
uv add --group dev pytest
mkdir tests[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]uv run pytestQuando usar isto:
- Ao iniciar testes em um novo projeto Python
- Ao migrar de
unittestpara pytest - Ao configurar a descoberta de testes para o layout
src/
Exemplo de Trabalho
myapp/
├── pyproject.toml
├── src/myapp/core.py
└── tests/
├── conftest.py
└── test_core.py
# tests/test_core.py
from myapp.core import add
def test_add():
assert add(2, 3) == 5[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
addopts = "-ra -q"
filterwarnings = ["error"]uv run pytest -v
uv run pytest tests/test_core.py::test_addO que isto demonstra:
- Testes ficam em
tests/, nomeadostest_*.py pythonpath = ["src"]permite imports sem instalação editável em configurações simplesconftest.pycontém fixtures compartilhadasaddoptsdefine flags CLI padrão para cada execução
Mergulho Profundo
Regras de Descoberta
- Arquivos:
test_*.pyou*_test.py - Funções:
test_* - Classes:
Test*(sem__init__) - Plugins estendem a descoberta (ex:
pytest-asynciopara testes assíncronos)
Locais de Configuração
| Arquivo | Prioridade |
|---|---|
pyproject.toml [tool.pytest.ini_options] | Preferencial |
pytest.ini | Legado |
Hooks do conftest.py | Por diretório |
Armadilhas Comuns
- Testes na raiz do projeto - coletados acidentalmente. Correção:
testpaths = ["tests"]limita a descoberta. - Erros de importação sem
srcno caminho -ModuleNotFoundError. Correção:pythonpath = ["src"]oupip install -e .. - Executando pytest sem dependências de desenvolvimento -
pytest: command not found. Correção:uv sync --group devouuv run pytest. - Fixtures duplicadas em
conftest.py- colisões de nomes entre diretórios. Correção: escopo de fixtures cuidadosamente; use nomes únicos. - Avisos como ruído - problemas reais ocultos. Correção:
filterwarnings = ["error"]para falhar em avisos inesperados.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| unittest | Apenas stdlib, sem dependências | Você quer fixtures e plugins |
| nose2 | Migração de nose legado | Novos projetos |
| behave | Testes de aceitação BDD | Testes unitários/de integração |
FAQs
Onde os testes devem ficar?
tests/ na raiz do projeto é a convenção. Espelhe a estrutura de src/ dentro dele.
Preciso de __init__.py em tests/?
Não para pytest 7+. Um tests/ vazio sem __init__.py funciona bem.
Como executo um único teste?
pytest tests/test_core.py::test_add ou pytest -k "add".
O que é conftest.py?
Fixtures e hooks compartilhados. Carregado automaticamente do diretório de teste até a raiz.
Como pulo um teste?
@pytest.mark.skip(reason="...") ou @pytest.mark.skipif(condition, reason="...").
O pytest pode executar testes do unittest?
Sim. O pytest coleta subclasses de unittest.TestCase automaticamente.
Como vejo a saída do print?
pytest -s desabilita a captura de saída.
O que é addopts?
Argumentos CLI padrão aplicados a cada invocação do pytest.
Como configuro marcadores?
markers = ["slow: marks slow tests"] na configuração; registre todos os marcadores personalizados.
pytest ou unittest?
pytest para novos projetos. Fixtures mais ricas, plugins e menos boilerplate.
Relacionados
- Assertions & Estrutura de Teste - escrevendo bons testes
- Fixtures - configuração e limpeza
- Cobertura & Relatórios - medindo o alcance dos testes
- Melhores Práticas de Teste - convenções de equipe
Versões das Pilhas: 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+.