DEV Community: Olivia Cheng

FastAPI: contratos para emails de prueba aislados

Olivia Cheng — Sun, 04 Oct 2026 14:23:43 +0000

Una prueba de registro puede pasar en local y fallar en CI por una razón poco visible: el email de verificación no pertenece realmente a esa ejecución. Tal vez el buzón conserva un mensaje viejo, dos workers consultan la misma bandeja o un reintento lee un enlace que ya fue usado.

En proyectos FastAPI, un fixture de email no debería ser solo una dirección que se crea al principio del test. Debe tener un contrato pequeño: quién lo creó, durante qué ejecución es válido, qué mensaje espera y cuándo deja de ser utilizable. Ese contrato hace que las pruebas sean mas fáciles de depurar y reduce falsos positivos.

Este patrón complementa las pruebas de signup sin un inbox real y funciona bien cuando el equipo necesita una dirección de correo desechable para una prueba aislada.

El problema: el email se convierte en estado global

Un flujo típico hace lo siguiente:

Crea un usuario.
Espera un email.
Abre el enlace de verificación.
Comprueba que la cuenta quedó activa.

La secuencia parece simple, pero una bandeja compartida introduce estado global. Si el test A y el test B usan la misma dirección, el segundo puede encontrar el mensaje del primero. Si el cliente HTTP repite una consulta sin límite, la prueba tarda mucho y aun no sabemos si el problema fue del producto o del sistema de correo.

La solución no es consultar mas veces. Es hacer que cada ejecución pueda demostrar que el mensaje correcto llegó a la bandeja correcta.

Define un contrato por ejecución

Un contrato útil puede representarse con cuatro datos:

from dataclasses import dataclass


@dataclass(frozen=True)
class EmailFixture:
    address: str
    run_id: str
    expected_subject: str
    expires_at: str

run_id debe ser único para el test o para el job de CI. El asunto esperado puede incluir ese identificador, o puedes buscar un token único en el cuerpo. Lo importante es no aceptar el primer mensaje que aparezca.

El fixture tambien necesita límites operativos. Por ejemplo:

Una sola creación de bandeja por ejecución.
Un máximo de cuatro consultas de mensajes.
Un máximo de dos lecturas del mensaje seleccionado.
Una ventana de espera explícita, como 30 segundos.
Eliminación o expiración al terminar el test.

Estos límites convierten una espera difusa en un resultado diagnosticable: timeout, mensaje_no_encontrado, asunto_incorrecto o enlace_inválido.

Implementa el fixture en FastAPI

La aplicación no necesita conocer todos los detalles del proveedor de email. En su lugar, define una interfaz pequeña para el entorno de prueba y úsala mediante dependencia de FastAPI:

from typing import Protocol
from fastapi import Depends, FastAPI


class Mailbox(Protocol):
    async def create(self, run_id: str) -> str: ...

    async def wait_for_subject(
        self, address: str, subject: str, timeout_seconds: int
    ) -> str: ...


app = FastAPI()


def get_mailbox() -> Mailbox:
    raise NotImplementedError("configura el adaptador de test")


@app.post("/test-fixtures/email")
async def create_email_fixture(
    run_id: str, mailbox: Mailbox = Depends(get_mailbox)
) -> dict[str, str]:
    address = await mailbox.create(run_id)
    return {"address": address, "run_id": run_id}

En producción, esta ruta no debería estar expuesta. Puedes sustituir la dependencia en tests con un adaptador falso o con un cliente de bandejas aisladas. En ambos casos, el test conserva el mismo contrato y cambia solo la implementación.

Para el correo de verificación, genera un token que no se repita dentro del job:

run_id = f"signup-{worker_id}-{test_id}"
subject = f"Verifica tu cuenta [{run_id}]"

Después de recibir el mensaje, valida el destinatario, el asunto, el identificador y el host del enlace. Validar solamente que existe una URL es demasiado poco; un enlace de otra ejecución también parece correcto a primera vista.

Si quieres profundizar en este aislamiento, revisa cómo aislar pruebas de emails transaccionales sin mezclar eventos entre tests.

Qué evidencia guardar en CI

Una prueba de email debe dejar un recibo pequeño, no el contenido completo de cada mensaje. Guarda datos como:

run_id, worker y nombre del test.
Dirección creada y hora de expiración.
Número de consultas realizadas.
Asunto encontrado y hash del mensaje.
Resultado de la validación del enlace.
Razón exacta del fallo, si existe.

Evita registrar tokens completos, cookies o cuerpos que contengan datos personales. Si un proveedor externo ofrece una dirección temporal, úsala solo para datos de prueba. Por ejemplo, tempmailso puede servir como referencia de una bandeja desechable para inspecciones puntuales; no conviertas esa dependencia en parte de la lógica de negocio.

También conviene guardar el recibo como artefacto de CI. Así el desarrollador puede ver si el mensaje nunca llegó, si llegó tarde o si el parser eligió el mensaje equivocado. Es un cambio pequeño, pero hace que la automatización sea mucho mas útil.

Preguntas rápidas

¿Una dirección de correo desechable reemplaza a un mock?

No siempre. Un mock es mas rápido y sirve para comprobar la lógica interna. Una bandeja aislada prueba además el envío, el formato y la integración con el proveedor. Lo práctico es usar mocks en la mayoría de tests y reservar el fixture real para unos pocos flujos de integración.

¿Qué pasa si el proveedor no permite filtrar por asunto?

Filtra en tu adaptador usando un token de ejecución en el asunto o en el cuerpo. Nunca aceptes el mensaje mas reciente sin comprobar su relación con el run_id.

¿Por qué aparece “tempail” en algunos apuntes?

Es una variante escrita por error que puede aparecer en búsquedas internas. No la uses como URL ni como criterio de validación: el contrato debe depender de identificadores propios de la prueba.

Checklist antes de cerrar la prueba

[ ] Cada ejecución crea o reserva su propio buzón.
[ ] El run_id aparece en el mensaje esperado.
[ ] Las consultas y la espera tienen límites.
[ ] El enlace se valida contra el entorno correcto.
[ ] El recibo no expone tokens ni datos personales.
[ ] El fixture expira incluso cuando el test falla.

Un email de prueba aislado no es solo una dirección temporal. Es un recurso con identidad, límites y evidencia. Cuando FastAPI trata ese recurso como un contrato, los fallos dejan de ser intermitentes y pasan a ser problemas concretos que el equipo puede arreglar.

FastAPI: aislar pruebas de email con un contrato

Olivia Cheng — Sun, 04 Oct 2026 08:24:00 +0000

Cuando una prueba de registro falla porque encontró un correo viejo, normalmente no es un problema de FastAPI. Es un problema de aislamiento. En varios equipos he visto que se usa un buzón compartido para todo el pipeline y luego cada ejecución tiene que adivinar cual mensaje le pertenece. Funciona durante un tiempo, hasta que dos jobs corren juntos o llega un reintento tarde.

Mi enfoque para estos flujos es tratar el buzón de prueba como un recurso con contrato: nace con la ejecución, tiene un identificador propio, expira y deja una evidencia pequeña antes de limpiarse. La idea sirve para una prueba de verificación, un flujo de recuperación de contraseña o cualquier API que dependa de un email entrante.

El problema: un buzón compartido contamina las pruebas

Un test típico hace esto:

Crea un usuario con un correo de prueba.
Llama al endpoint de signup de FastAPI.
Espera el mensaje de verificación.
Extrae el enlace y confirma la cuenta.

Si todas las ejecuciones usan la misma dirección, el paso tres puede leer un mensaje de otra rama o de un intento anterior. Un subject parecido no alcanza: dos tests pueden tener el mismo asunto y destinatario. El fallo aparece de forma intermitente, que es la forma más cara de depurar.

También conviene separar la preparación de datos del consumo del mensaje. Una seed list para un onboarding reproducible ayuda a ordenar usuarios y estados, pero no reemplaza un inbox aislado. La preparación de seed lists para un onboarding reproducible puede vivir en una etapa anterior; el contrato de correo debe seguir siendo específico para cada ejecución.

El contrato mínimo de un buzón por ejecución

Antes de escribir código, defino cinco reglas sencillas:

Identidad: la dirección incluye un run_id o un token aleatorio.
Propiedad: el test conoce qué mensajes puede consumir.
Caducidad: el recurso no debe quedarse vivo después del job.
Espera acotada: nunca se espera para siempre.
Evidencia: asunto, destinatario normalizado y resultado quedan en el log; no el contenido completo si contiene datos sensibles.

Esto es más útil que elegir un proveedor por la etiqueta de “throwaway email”. Incluso cuando se usa un burner email address para pruebas manuales, el pipeline necesita una política de propiedad y limpieza. Las variantes escritas como temp mailid o tempail aparecen a veces en búsquedas y tickets, pero no deben terminar mezcladas con el nombre de una fixture ni con un selector del test.

Una fixture pequeña en Python

La interfaz de la fixture puede ser independiente del proveedor. Así el test solo conoce las operaciones que necesita:

from dataclasses import dataclass
from uuid import uuid4


@dataclass(frozen=True)
class TestInbox:
    address: str
    run_id: str


def create_inbox(domain: str = "qa.example") -> TestInbox:
    run_id = uuid4().hex[:12]
    return TestInbox(
        address=f"signup-{run_id}@{domain}",
        run_id=run_id,
    )

En un sistema real, create_inbox también reservaría la dirección en el proveedor elegido. Lo importante es que devuelva el identificador que usaremos al buscar mensajes. No conviene generar una dirección en el test y buscar después por texto parcial: ese atajo hace que el aislamiento dependa de la suerte.

El test puede pasar inbox.address al endpoint y conservar inbox.run_id como correlación. Para consultar el mensaje, filtraría por destinatario exacto, una marca de ejecución en los headers o un token único dentro del enlace. Si el token aparece en la URL, no lo imprimas completo en CI.

Cómo esperar y limpiar sin hacer el test frágil

Leer el inbox una sola vez suele ser demasiado optimista. El correo es asíncrono, así que prefiero polling con pausa corta y un límite total. Cada intento debe tener una condición clara:

import time


def wait_for_message(client, inbox: TestInbox, timeout: float = 20.0):
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        messages = client.list_messages(to=inbox.address)
        match = next((m for m in messages if inbox.run_id in m.text), None)
        if match:
            return match
        time.sleep(0.5)
    raise TimeoutError(f"No llegó el email para {inbox.run_id}")

El timeout debe representar el contrato del entorno de pruebas, no una espera infinita disfrazada. Si el proveedor ofrece webhook, puede sustituir al polling; la misma correlación sigue siendo necesaria.

Limpio en un bloque finally, incluso cuando falla la aserción. Si la limpieza falla, la registro como una alerta de infraestructura sin ocultar el error principal del test. Y si el sistema bajo prueba necesita reintentos, el test debe verificar que usa el mismo intento lógico, no aceptar cualquier mensaje que aparezca.

Qué guardar como evidencia en CI

Una evidencia útil es pequeña y suficiente:

run_id de la ejecución;
dirección de prueba, parcialmente enmascarada;
timestamp de creación y de recepción;
identificador del mensaje;
estado final: recibido, timeout o limpieza fallida.

No guardes el HTML completo por defecto. Puede contener tokens de recuperación o datos personales de una prueba. Un snapshot del estado y el mensaje de error suele bastar para reproducir el problema. Si el equipo necesita ver la UI, aplica el mismo criterio de aislamiento a cada sesión; mostrar errores inline sin mover el formulario también depende de que los datos de prueba no se pisen entre sí.

Preguntas frecuentes

¿Puedo usar una sola dirección para todos los tests?

Solo para una prueba local muy controlada. En CI, una dirección por ejecución reduce colisiones y hace el fallo más explicable.

¿Debo borrar el buzón después de cada test?

Sí, o al menos marcarlo para una limpieza con TTL. El finally es la red de seguridad cuando una aserción se rompe.

¿Qué hago si el email tarda más de lo esperado?

Registra el timeout y los metadatos de entrega. Luego revisa proveedor, cola y endpoint por separado. Aumentar el timeout sin evidencia solo vuelve el pipeline más lento.

El patrón no requiere una arquitectura grande: identidad, correlación, espera limitada y limpieza. Con esas piezas, una prueba de email en FastAPI deja de depender de mensajes casuales en un buzón compartido y la automatización se vuelve bastante más tranquila.

FastAPI: emails de prueba con un buzón por ejecución

Olivia Cheng — Fri, 02 Oct 2026 11:23:25 +0000

Cuando una API envía un email de verificación, el test suele parecer sencillo: crear usuario, esperar el mensaje y abrir el enlace. El problema aparece cuando varios tests comparten el mismo buzón. Un mensaje viejo puede pasar por nuevo, un reintento puede leer el token de otra ejecución y el fallo termina siendo dificil de reproducir.

En proyectos con FastAPI he encontrado una solución muy práctica: cada ejecución debe tener su propio buzón lógico, su propio identificador de correlación y una fecha clara de expiración. No hace falta convertir el test en una plataforma enorme. Hace falta que sus datos no se mezclen.

El problema de compartir un buzón de prueba

Un buzón compartido parece cómodo al principio. El equipo configura una dirección, añade una función para leer el último mensaje y todos los tests avanzan. Pero “el último” no es una propiedad estable cuando hay paralelismo.

Los fallos más comunes son estos:

Un test encuentra un email de la ejecución anterior.
Dos usuarios de prueba reciben mensajes y el filtro solo mira el asunto.
Un reintento consume el mismo token que el primer intento.
El CI guarda el cuerpo completo del email en un artefacto.
La limpieza depende de que el test termine sin errores.

Incluso una búsqueda escrita como dummy e mail puede llegar a los logs de soporte. Por eso conviene que la fixture sea legible para una persona, pero que no dependa de interpretar texto libre para saber a qué ejecución pertenece.

Qué debe garantizar cada ejecución

Mi contrato mínimo tiene cuatro piezas:

Identidad única. Genera un run_id y úsalo en la dirección o en el identificador del buzón.
Lectura acotada. Busca mensajes después de la hora de inicio, con un destinatario exacto y un asunto conocido.
Consumo idempotente. Leer dos veces el mismo mensaje no debe cambiar el resultado del test.
Expiración. El buzón y sus mensajes deben poder eliminarse aunque la aserción falle.

La dirección no tiene que ser bonita. Algo como qa+run-8f31@example.test comunica más que una dirección fija. También hace más fácil relacionar una petición de FastAPI con el mensaje que la API generó.

Esto se parece a medir señales útiles en un onboarding SaaS: no necesitas guardar todo para entender qué pasó. Necesitas escoger señales que permitan reconstruir la secuencia.

Un fixture sencillo para FastAPI

El siguiente ejemplo muestra la forma del contrato. InboxClient representa el proveedor de buzones de prueba y puede ser un fake local durante los tests unitarios.

from dataclasses import dataclass
from uuid import uuid4


@dataclass
class EmailFixture:
    address: str
    run_id: str

    @classmethod
    async def create(cls, inbox_client) -> "EmailFixture":
        run_id = uuid4().hex[:12]
        address = await inbox_client.create_inbox(label=f"fastapi-{run_id}")
        return cls(address=address, run_id=run_id)

    async def wait_for_verification(self, inbox_client, timeout=20):
        return await inbox_client.wait_for(
            recipient=self.address,
            subject="Verifica tu cuenta",
            timeout=timeout,
        )

    async def close(self, inbox_client):
        await inbox_client.delete_inbox(self.address)

En un test de FastAPI, el cierre debe estar en un bloque finally, no después de la última aserción. Si la aserción falla, el código posterior no se ejecuta. Es un detalle pequeño, pero suele ser la diferencia entre un CI limpio y una colección de buzones abandonados.

fixture = await EmailFixture.create(inbox_client)
try:
    response = await client.post(
        "/signup",
        json={"email": fixture.address, "password": "example-only"},
    )
    assert response.status_code == 201

    message = await fixture.wait_for_verification(inbox_client)
    assert "/verify?token=" in message.text
finally:
    await fixture.close(inbox_client)

El timeout también es parte del diseño. Si cada test espera indefinidamente, una incidencia de entrega puede congelar toda la automatización. Devuelve un error con el run_id, el destinatario y el último estado conocido, pero no con el token completo.

Automatizar la limpieza y la evidencia

La limpieza debe tener dos capas. Primero, el test intenta borrar su buzón. Segundo, una tarea periódica elimina recursos cuyo expires_at ya pasó. Así, un proceso cancelado no deja datos para siempre.

Para depurar, conserva solo evidencia útil: run_id, estado HTTP, identificador del mensaje, timestamps y una versión redactada del asunto. No guardes enlaces de verificación completos en los logs del CI. Esa información hace que un fallo de prueba sea un riesgo innecesario.

También ayuda mostrar el estado al desarrollador. Una interfaz con una interfaz React que mantiene el contexto puede enseñar “email solicitado”, “mensaje recibido” y “token consumido” sin saltos confusos. El backend sigue siendo la fuente de verdad, pero la UI no deberia esconder el estado real.

Checklist final

Antes de dar por terminada la fixture, compruebo lo siguiente:

Cada ejecución crea una identidad de buzón diferente.
El filtro combina destinatario, asunto y hora de inicio.
Un mensaje no se consume dos veces por accidente.
El finally elimina el buzón incluso si una aserción falla.
Existe una limpieza de respaldo por expiración.
Los logs no contienen tokens completos ni cuerpos innecesarios.
El timeout produce un diagnóstico accionable.

Con este contrato, las pruebas de email dejan de depender de la suerte. La API puede reintentarse, el CI puede ejecutar varios casos en paralelo y el equipo puede leer un fallo sin adivinar qué buzón pertenecia a qué ejecución. Es una mejora pequeña, pero se nota rápido cuando el proyecto crece.

FastAPI: fixtures de email para tests reproducibles

Olivia Cheng — Tue, 29 Sep 2026 07:09:53 +0000

Los flujos de email son una prueba pequeña que suele esconder muchos problemas. Un registro puede crear un usuario, enviar un mensaje, consumir un token y cambiar el estado de una cuenta. Si cada test depende de un buzón compartido o de un correo que llega “cuando puede”, el resultado deja de ser reproducible.

En proyectos Python prefiero tratar el correo de prueba como una fixture con contrato propio. La aplicación no tiene que saber si detrás existe un fake local, un servicio de integración o un correo desechable gratis para una comprobación manual. Solo necesita recibir una interfaz predecible, consultar un mensaje y limpiar el recurso al terminar.

El problema: una fixture no es un buzón compartido

Un buzón compartido parece práctico al principio. Pero dos ejecuciones pueden usar el mismo asunto, una lectura puede consumir el mensaje de otra prueba y un reintento puede encontrar un token viejo. Despues aparecen fallos intermitentes que no se pueden reproducir en el portátil.

La unidad correcta es una fixture por escenario. Cada una debe tener un identificador, un propósito, una fecha de expiración y una regla de limpieza. Para un test de registro, por ejemplo, el flujo podría ser:

crear fixture -> ejecutar signup -> esperar mensaje -> validar token -> eliminar fixture

El test no debería buscar “el último email”. Debería pedir el mensaje asociado a su fixture_id y verificar que el destinatario, el asunto y el token pertenecen a ese escenario. Es un cambio pequeño, pero elimina bastante ruido.

Define el contrato de la fixture

Antes de escribir el endpoint, define qué necesita el test. Un contrato mínimo puede tener estas operaciones:

from dataclasses import dataclass
from datetime import datetime

@dataclass(frozen=True)
class MailFixture:
    fixture_id: str
    address: str
    expires_at: datetime

class MailFixtureStore:
    async def create(self, purpose: str) -> MailFixture: ...
    async def wait_for(self, fixture_id: str, timeout_seconds: int) -> str: ...
    async def delete(self, fixture_id: str) -> None: ...

La función wait_for debe terminar con un estado claro: mensaje recibido, timeout o fixture expirada. No conviene devolver una cadena vacía para los tres casos. Un error explícito permite que CI distinga entre un producto que no envió el correo y un entorno que tardó demasiado.

También conviene guardar una huella del caso, no el contenido completo del mensaje en cada log. fixture_id, test_name, message_id y duración suelen ser suficiente para investigar. Si necesitas revisar la interfaz, aquí ayuda feedback estable al enviar emails, porque el estado visible debe explicar si el test está esperando, ha terminado o ha fallado.

Un adaptador pequeño para FastAPI

FastAPI puede exponer la fixture solo en un entorno de pruebas. La dependencia mantiene el endpoint limpio y permite sustituir la implementación en un test unitario:

from fastapi import APIRouter, Depends, HTTPException

router = APIRouter()

async def get_fixture_store() -> MailFixtureStore:
    return MailFixtureStore()

@router.post("/test-fixtures/mail")
async def create_mail_fixture(
    purpose: str,
    store: MailFixtureStore = Depends(get_fixture_store),
):
    if not purpose.strip():
        raise HTTPException(status_code=400, detail="Falta purpose")
    return await store.create(purpose=purpose)

En producción, este endpoint debe estar desactivado o protegido por una frontera de entorno. Una variable como ENABLE_TEST_FIXTURES=false no reemplaza la autenticación, pero sí evita que una ruta de soporte se publique por accidente. Las APIs que crean datos efímeros deben devolver también expires_at, para que el cliente no dependa de una suposición escondida.

Para tests de integración, una implementación HTTP puede hablar con el proveedor elegido. Para tests unitarios, un fake en memoria es más rápido y suficiente. Lo importante es que las dos implementaciones respeten el mismo contrato. Si el producto tiene correos de trial, merece la pena usar emails de trial sin contaminar el embudo y mantener esos escenarios separados de los datos de analítica.

Aislamiento, limpieza y diagnóstico

El aislamiento no termina cuando llega el token. Cada test debe usar un identificador único, y la limpieza debe ocurrir aunque una aserción falle. En pytest, una fixture async con yield expresa bien esa responsabilidad:

import pytest

@pytest.fixture
async def mail_fixture(store):
    fixture = await store.create(purpose="signup")
    try:
        yield fixture
    finally:
        await store.delete(fixture.fixture_id)

Define un timeout corto para polling y un deadline total para el escenario. Un intervalo de dos segundos puede ser correcto en una integración remota, pero resulta lento si se repite cientos de veces. Para reducir coste, usa backoff limitado y detén la consulta al detectar un estado terminal.

Los nombres también importan. Un purpose como signup-ci-1842 ayuda más que test-email. Y aunque el sistema se llame tempail en una nota antigua, el identificador real debe ser consistente en el código, los logs y los reportes. No guardes tokens completos en los logs; basta con un hash corto o con los últimos caracteres cuando sea estrictamente necesario.

Para una revisión manual aislada, temp mail.so puede servir como referencia de un buzón temporal, pero no debe convertirse en una dependencia oculta de CI ni recibir información personal. El test automatizado necesita un proveedor controlable, una política de retención y una forma de borrar los datos.

Preguntas rápidas

¿Debo usar un correo desechable gratis en todos los tests?

No. Para la mayoría de los tests unitarios, un fake local es más rápido. Reserva una integración real para validar el transporte, las plantillas y el comportamiento del proveedor.

¿Conviene compartir una fixture entre varios tests?

Solo si el escenario es explícitamente compartido. Como regla general, una fixture por test reduce el acoplamiento y hace que un fallo sea mas fácil de entender.

¿Qué hago con un timeout?

Regístralo como un resultado distinto de “mensaje inválido”. Guarda el fixture_id, el deadline y el estado del proveedor. Así sabrás si falló la aplicación, el transporte o el propio test.

Checklist final

Cada test crea una fixture aislada y con expiración.
El contrato diferencia recibido, expirado y timeout.
El adaptador de FastAPI se puede sustituir por un fake.
La limpieza corre incluso después de una aserción fallida.
Los logs usan identificadores, no tokens ni contenido sensible.
CI tiene un proveedor controlable y una ruta de diagnóstico.

Este diseño no necesita ser grande. Una interfaz pequeña, estados explícitos y una limpieza garantizada suelen ser suficiente para que los tests de email dejen de ser una fuente misteriosa de fallos. Y cuando el flujo crece, ya tendrás un contrato claro sobre el que añadir reintentos, métricas o nuevos proveedores.