Testing FastAPI
Ejercita rutas con TestClient, anulaciones de dependencias y clientes asíncronos.
Receta
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
from fastapi import FastAPI
from fastapi.testclient import TestClient
app = FastAPI()
@app.get("/health")
def health() -> dict[str, str]:
return {"status": "ok"}
def test_health():
client = TestClient(app)
r = client.get("/health")
assert r.status_code == 200
assert r.json()["status"] == "ok"Cuándo usar esto:
- Pruebas de regresión para rutas
- Dobles de prueba de autenticación y base de datos
- Comprobaciones de contrato OpenAPI
Ejemplo de trabajo
import pytest
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
app = FastAPI()
def get_db():
return {"items": ["fixture"]}
@app.get("/items")
def items
Lo que esto demuestra:
- Prueba de humo de TestClient
- Fixture de pytest con anulaciones
- Limpieza de anulaciones
Análisis Profundo
Cómo funciona
TestClientejecuta la aplicación ASGI en proceso sin red.- Las anulaciones reemplazan las dependencias para pruebas aisladas.
- Usa
httpx.AsyncClientconASGITransportpara rutas asíncronas.
Errores Comunes
- Validación de límites omitida - Los datos no válidos llegan a las capas de persistencia. Solución: Valida con Pydantic o formularios del framework en el borde.
- Fugas de trazas de pila - Los clientes ven errores internos. Solución: Mapea excepciones a respuestas HTTP estables.
- Bucles asíncronos bloqueantes - Los trabajadores se detienen bajo carga concurrente. Solución: Usa controladores asíncronos o envoltorios de pool de hilos.
- Secretos en control de versiones - Las credenciales se filtran a través del historial de git. Solución: Carga secretos desde el entorno o una bóveda en tiempo de ejecución.
- Falta de observabilidad - Los incidentes son difíciles de depurar. Solución: Agrega registros estructurados, métricas e IDs de solicitud.
Alternativas
| Alternativa | Usar cuándo | No usar cuándo |
|---|---|---|
| Framework alternativo en este cookbook | Estándar del equipo o monolito existente | API nueva con diferentes restricciones |
| BaaS administrado | MVP solo CRUD | Autenticación, flujos de trabajo o necesidades de cumplimiento personalizadas |
| gRPC | RPC interno de alto rendimiento | Clientes HTTP públicos y acceso al navegador |
Preguntas Frecuentes
¿Cuándo debería adoptar las pruebas de FastAPI?
Úsalo cuando los patrones y las compensaciones de esta página coincidan con los límites de tu API o datos.
¿Cuál es el principal error de producción con las pruebas de FastAPI?
Omitir la validación, los tiempos de espera o los contratos de error explícitos en el borde HTTP.
¿Cómo pruebo las pruebas de FastAPI?
Usa el cliente de prueba del framework, anula las dependencias y afirma el estado más la forma del JSON.
¿Las pruebas de FastAPI funcionan con Python 3.14?
Sí, los ejemplos se dirigen a Python 3.14 con versiones de framework fijadas del pie de página de la pila.
¿Cómo se relacionan las pruebas de FastAPI con Pydantic 2?
Valida y serializa en los límites; mantén los servicios funcionando con objetos de dominio tipados.
¿Síncrono o asíncrono?
Prefiere rutas asíncronas cuando el I/O domina; mantén el trabajo de CPU pequeño o descárgalo a trabajadores.
¿Dónde debe residir la lógica de negocio?
Controladores delgados; los servicios poseen las reglas; los repositorios poseen las consultas.
¿Cómo documento las API?
Publica documentación OpenAPI o de esquema que coincida con los modelos de respuesta en el código.
¿Cómo manejo el versionado?
Versionado explícito de URL o encabezado con ventanas de deprecación; evita roturas silenciosas.
¿Qué debería leer a continuación?
Sigue los enlaces Relacionados para obtener la siguiente capa de profundidad en esta sección.
¿Cómo me mantengo seguro?
Autentica a los llamadores, autoriza por recurso, limita la tasa y nunca registres secretos.
¿Primer paso para el rendimiento?
Mide la latencia de la base de datos y de los sistemas externos antes de cambiar de framework.
Relacionado
- Conceptos básicos de FastAPI - Rutas y modelos principales
- Inyección de dependencias - Proveedores por solicitud
- Testing FastAPI - Patrones de cliente de prueba
- Despliegue de FastAPI - Servir en producción
Versiones de la pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.