Testando APIs Web
Testes de API acessam sua aplicação em processo, sem iniciar um servidor. O TestClient do FastAPI, o cliente de teste do Flask e o Client do Django enviam requisições e verificam as respostas.
Receita
from fastapi.testclient import TestClient
from myapp.main import app
client = TestClient(app)
def test_health():
response = client.get("/health")
assert response.status_code == 200
assert response.json() == {"status": "ok"}Quando usar isso:
- Verificando manipuladores de rota, códigos de status e corpos de resposta
- Testando middleware de autenticação e respostas de erro
- Testes de CI que não devem depender de serviços externos
Exemplo de Trabalho
# tests/conftest.py
import pytest
from fastapi.testclient import TestClient
from myapp.main import app
@pytest.fixture
def client():
return TestClient(app)
@pytest.fixture
def auth_client(client):
client.headers.update({"Authorization": "Bearer test-token"})
return clientdef test_create_invoice(client):
response = client.post("/invoices", json={"amount": 100.0, "currency": "USD"})
assert response.status_code == 201
data = response.json()
assert data["amount"] == 100.0
assert "id" in data
def test_unauthorized(auth_client):
response = auth_client.get("/admin/users")
assert response.status_code in (200, 403)
def test_validation_error(client):
response = client.post("/invoices", json={"amount": -1})
assert response.status_code == 422O que isso demonstra:
TestClientexecuta o aplicativo ASGI em processo- Teste de requisição/resposta JSON com
.json() - Fixture para cliente autenticado
- Erros de validação do Pydantic retornam 422
Mergulho Profundo
Clientes de Framework
| Framework | Cliente | Importar |
|---|---|---|
| FastAPI | TestClient | fastapi.testclient |
| Flask | test_client() | app.test_client() |
| Django | Client | django.test.Client |
| Qualquer ASGI | httpx + transport | httpx.ASGITransport |
Testes Assíncronos
import httpx
from httpx import ASGITransport
@pytest.fixture
async def async_client():
transport = ASGITransport(app=app)
async with httpx.AsyncClient(transport=transport, base_url="http://test") as c:
yield cArmadilhas
- TestClient com ciclo de vida assíncrono - eventos de inicialização podem não ser executados. Correção: use o gerenciador de contexto
with TestClient(app) as client:. - Estado compartilhado mutável do aplicativo - testes afetam uns aos outros. Correção: aplicativo com escopo de fixture ou substituição de dependências por teste.
- Testando contra banco de dados real - lento, instável. Correção: substitua a dependência do banco de dados por SQLite em memória nos testes.
- Não testando caminhos de erro - apenas respostas 200 testadas. Correção: afirme explicitamente respostas 400, 401, 404, 422.
- Tokens de autenticação codificados em testes - desviam da autenticação real. Correção: fixture que espelha a substituição de dependência de autenticação de produção.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| httpx contra servidor em execução | Testes E2E em staging | Testes de unidade/rota |
| Schemathesis | Fuzzing OpenAPI | Rotas CRUD simples |
| Postman/Newman | Exploração manual | Testes de unidade automatizados de CI |
FAQs
TestClient ou httpx?
TestClient para testes síncronos (mais simples). httpx AsyncClient para suítes de teste assíncronas.
Como substituo dependências do FastAPI?
app.dependency_overrides[dep] = lambda: mock_value na configuração/limpeza da fixture.
Como testo aplicativos Flask?
client = app.test_client() e então client.get("/path").
Como testo views do Django?
pytest-django + client.get("/url/") com o Cliente de teste do Django.
Preciso de um servidor em execução?
Não. Clientes em processo são mais rápidos e determinísticos.
Como testo WebSockets?
TestClient(app).websocket_connect("/ws") para FastAPI/Starlette.
Como testo uploads de arquivos?
client.post("/upload", files={"file": ("test.txt", b"content")}).
Como testo middleware?
Envie requisições que acionam o middleware. Afirme mudanças de cabeçalho e status.
Testes de API devem usar um banco de dados real?
Testes de integração: sim (banco de dados de teste). Testes de rota de unidade: substitua por mock ou SQLite.
Como testo o esquema OpenAPI?
Afirme a estrutura de /openapi.json ou use Schemathesis para testes de API baseados em propriedades.
Relacionados
- Testando Código Assíncrono - cliente httpx assíncrono
- Fixtures - fixtures de cliente
- Mocking & Patching - substitua dependências
- Testando FastAPI - padrões específicos do FastAPI
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+.