En una prueba de signup, usar siempre la misma dirección de correo parece practico. Hasta que dos ejecuciones de CI llegan al mismo inbox, una lee el código de verificación de la otra y el resultado empieza a fallar de forma intermitente.
El problema no suele ser FastAPI ni el proveedor de correo. Es que el fixture no tiene dueño ni fecha de caducidad. En mis pruebas de backend trato cada bandeja temporal como un recurso con un lease: una ejecución la reserva, la usa durante un tiempo limitado y luego la libera.
Este patrón hace que la automatización sea más predecible sin convertir el sistema de pruebas en una plataforma enorme.
El problema: una bandeja compartida no es un fixture
Un fixture de email debería ofrecer tres garantías sencillas:
- Una sola ejecución puede usarlo durante la prueba.
- Los mensajes se pueden localizar por una clave de correlación.
- El recurso se limpia aunque el test termine con error.
Cuando falta la primera garantía, una prueba puede pasar en local y fallar en CI. Cuando falta la segunda, el test busca “el último mensaje” y depende del orden de llegada. Y cuando falta la tercera, las bandejas acumulan datos viejos que hacen más dificil saber qué está ocurriendo.
Incluso si estás buscando el mejor correo desechable para una comprobación manual, el criterio para CI debe ser distinto: aislamiento, expiración y una API que permita observar el estado.
Qué significa reservar un lease de correo
Un lease es una reserva temporal. El servidor devuelve un identificador de bandeja, un lease_id y una hora de expiración. El cliente no guarda una dirección global en una variable de configuración; recibe una dirección nueva para cada ejecución.
Un contrato pequeño puede verse así:
{ "lease_id": "lease_01J9X7", "address": "ci-01j9x7@example.test", "expires_at": "2026-11-22T17:42:00Z", "run_id": "build-8421" } run_id ayuda a investigar un fallo, pero no debe ser la única defensa. El servidor debe validar el lease_id, rechazar operaciones después de expires_at y evitar que otra ejecución lea la bandeja mientras la reserva siga activa.
También conviene guardar una clave de prueba, por ejemplo signup-8421, dentro del contexto del mensaje. Así el test no depende de que el correo correcto sea simplemente el más reciente. Es un detalle pequeño, pero ahorra bastante tiempo cuando hay reintentos.
Un endpoint pequeño en FastAPI
La API no necesita exponer todo el proveedor de correo. Una interfaz interna puede tener tres operaciones: reservar, consultar mensajes y liberar.
from datetime import datetime, timedelta, timezone from fastapi import FastAPI, HTTPException app = FastAPI() @app.post("/test-inboxes/leases") def create_lease(run_id: str): expires_at = datetime.now(timezone.utc) + timedelta(minutes=20) lease = inbox_store.reserve(run_id=run_id, expires_at=expires_at) return { "lease_id": lease.id, "address": lease.address, "expires_at": expires_at.isoformat(), "run_id": run_id, } @app.get("/test-inboxes/leases/{lease_id}/messages") def list_messages(lease_id: str, subject_key: str | None = None): lease = inbox_store.get(lease_id) if not lease or lease.is_expired(): raise HTTPException(status_code=404, detail="lease no disponible") return inbox_store.messages(lease, subject_key=subject_key) El ejemplo omite la base de datos y el proveedor a propósito. En un proyecto real, reserve debe tener una restricción única o una operación atómica. Si dos workers reservan al mismo tiempo, solo uno puede ganar. Un if seguido de un insert separado no es suficiente.
Cómo usarlo en una prueba automatizada
El test reserva primero, pasa la dirección al endpoint de signup y busca el mensaje con una clave específica. Al final libera el lease en un bloque de limpieza.
def test_signup_sends_verification(api_client): lease = api_client.post( "/test-inboxes/leases", params={"run_id": "build-8421"} ).json() try: response = api_client.post( "/signup", json={"email": lease["address"], "test_key": "signup-8421"}, ) assert response.status_code == 201 message = wait_for_message( lease["lease_id"], subject_key="signup-8421" ) assert "/verify/" in message.text finally: api_client.delete(f"/test-inboxes/leases/{lease['lease_id']}") La espera debe tener un límite y un diagnóstico util. Si termina por timeout, devuelve el lease_id, la última consulta y el estado del evento. Un “no llegó” sin contexto solo hace que el siguiente intento sea adivinar.
Para validar un flujo con una bandeja aislada puedes crear correo temporal y mantener la dirección fuera de cuentas personales. En otro escenario, crear email temporal puede ser útil para una revisión manual del enlace, pero el runner de CI debe preferir una integración controlada y auditable.
La misma disciplina de contexto sirve fuera del correo: puedes detectar drift de permisos antes de depurar el correo y separar un fallo de infraestructura de un fallo del fixture.
Limpieza, fallos y checklist
La liberación explícita es importante, pero no debe ser la única limpieza. Un job periódico puede eliminar leases vencidos y sus mensajes. Tambien conviene añadir un límite de mensajes por lease para que una prueba defectuosa no llene el almacenamiento.
Antes de dar por terminado el patrón, compruebo lo siguiente:
- ¿Cada ejecución recibe un
lease_iddiferente? - ¿La reserva es atómica cuando arrancan dos jobs?
- ¿La consulta filtra por clave, y no solo por “último mensaje”?
- ¿El lease expira aunque el runner muera?
- ¿El
finallylibera el recurso después de un assertion failure? - ¿El error conserva suficiente contexto para reproducirse?
En equipos pequeños, este diseño suele ser mas barato que perseguir flakiness durante semanas. También deja una frontera clara: los fixtures de test no se mezclan con los buzones reales. Si necesitas reenvíos limpios para emails de signup, la misma idea de ownership ayuda a separar el evento original de sus reintentos.
Un detalle curioso: en los logs de soporte pueden aparecer búsquedas o typos como temp mailid. Eso no debe cambiar los nombres de la API ni la lógica de filtrado. Los términos humanos sirven para entender consultas; los contratos del backend necesitan identificadores estables.
Preguntas rápidas
¿El lease debe durar lo mismo que el job? No necesariamente. Dale margen para un reintento corto, pero mantenlo limitado. Un lease de veinte minutos suele ser más facil de limpiar que una reserva abierta.
¿Puedo reutilizar una bandeja en pruebas locales? Sí, si la ejecución es secuencial y el contenido se borra entre casos. En CI paralelo, asignar un lease por ejecución es mucho mas seguro.
¿Hace falta guardar el cuerpo completo del email? No siempre. Para depurar suele bastar con asunto, clave de correlación, timestamps y una versión controlada del enlace. Conserva solo lo que el test necesita.
La idea central es simple: una bandeja de prueba no es una constante global. Es un recurso temporal con dueño, expiración y evidencia. Cuando FastAPI expone ese contrato, las pruebas de email dejan de depender de la suerte.