DEV Community: Olivia Cheng

FastAPI: un buzón de prueba que no se repite

Olivia Cheng — Sat, 24 Oct 2026 23:22:48 +0000

Un test de registro que pasa una vez y falla en la siguiente suele esconder el mismo problema: el buzón de prueba se está reutilizando. El mensaje anterior sigue ahí, el enlace ya caducó o dos ejecuciones están esperando el mismo correo. El resultado es una prueba frágil y dificil de diagnosticar.

En proyectos de Python he encontrado más estable tratar cada correo como un recurso temporal, no como una constante global. La idea de use and throw email encaja bien aquí: crear un buzón para una corrida, consumir solo el mensaje esperado y dejarlo fuera del siguiente intento. Es una forma sencilla de que la automatización sea más predecible.

El problema de reutilizar un email de prueba

Imagina un endpoint que registra a un usuario y envía un enlace de confirmación. Un test puede usar qa@example.test en cada ejecución, pero pronto aparecen varios problemas:

Un mensaje viejo coincide con el asunto esperado.
Dos jobs de CI leen el mismo correo casi al mismo tiempo.
Un reintento crea otro usuario, pero conserva la identidad anterior.
El diagnóstico no distingue un fallo de entrega de un fallo de lectura.

Un buzón temporal también puede tener nombres confusos en la documentación interna, como temp org mail o tempail. No importa el nombre comercial o coloquial: el contrato técnico debe decir quién crea el buzón, cuánto vive y qué mensaje puede consumir.

Un contrato pequeño para cada ejecución

Antes de tocar FastAPI, define tres valores por corrida:

run_id: identifica el job de CI o la ejecución local.
mailbox_id: identifica el buzón creado para esa corrida.
expected_token: relaciona el enlace recibido con el usuario que se está probando.

El run_id evita que dos procesos compartan estado por accidente. El mailbox_id permite limpiar el recurso al terminar. El token, por su parte, evita aceptar cualquier mensaje que tenga el mismo asunto. Puede parecer un poco de trabajo extra, pero ahorra horas cuando un test intermitente aparece solo en el pipeline.

Si todavía no tienes una interfaz para aislar tus pruebas, este enfoque combina bien con aislar las pruebas de email con un contrato. La separación importante es entre el contrato del servicio y el proveedor concreto del buzón.

Implementación en FastAPI

Una interfaz pequeña hace que el endpoint sea fácil de probar. No necesitas que FastAPI conozca todos los detalles del proveedor de correo:

from dataclasses import dataclass
from uuid import uuid4

from fastapi import FastAPI

app = FastAPI()


@dataclass(frozen=True)
class Mailbox:
    address: str
    mailbox_id: str


def create_test_mailbox(run_id: str) -> Mailbox:
    mailbox_id = f"{run_id}-{uuid4().hex[:8]}"
    return Mailbox(
        address=f"{mailbox_id}@test.invalid",
        mailbox_id=mailbox_id,
    )


@app.post("/test-users")
def create_test_user(run_id: str):
    mailbox = create_test_mailbox(run_id)
    token = uuid4().hex
    # Guarda mailbox.mailbox_id y token junto al usuario creado.
    return {
        "email": mailbox.address,
        "mailbox_id": mailbox.mailbox_id,
        "verification_token": token,
    }

En una aplicación real, el endpoint no debería devolver el token. El ejemplo solo muestra la frontera entre la creación del usuario y el recurso de email. El adaptador de pruebas puede guardar el token esperado en el contexto del test y buscar un mensaje cuyo enlace lo contenga.

También conviene no generar el mailbox_id únicamente desde el email. Algunos proveedores normalizan direcciones y eso puede juntar dos buzones que parecian distintos. Guarda el identificador del proveedor como dato de primera clase.

Cómo hacerlo seguro para reintentos

La idempotencia empieza con una clave estable por intención. Por ejemplo, signup:{run_id} puede ser la clave de la operación. Si el test reintenta después de un timeout, el servicio puede devolver el usuario ya creado en vez de enviar tres mensajes diferentes.

Para leer el correo, usa una espera acotada y una condición precisa:

async def wait_for_verification(inbox, token, timeout=30):
    deadline = monotonic() + timeout
    while monotonic() < deadline:
        for message in await inbox.messages():
            if token in message.text:
                return message
        await asyncio.sleep(1)
    raise TimeoutError("No llegó el email de verificación")

El código debe distinguir entre “no llegó” y “llegó un mensaje inválido”. El primero puede justificar un reintento de entrega; el segundo señala un problema de plantilla, token o aislamiento. Mezclar ambos estados hace que CI reintente sin necesidad y alarga el diagnóstico.

Al terminar, elimina el buzón o márcalo como cerrado. Si el proveedor no permite borrado inmediato, aplica una política de expiración y no vuelvas a asignar ese identificador. La limpieza que se hace tarde es mejor que ninguna, pero una rutina finally es mucho más confiable.

Checklist para CI

Crea un buzón nuevo por job o por caso de prueba.
Incluye run_id y un token único en los datos de prueba.
Busca el token esperado, no solo el asunto del mensaje.
Define un timeout y registra la última fase conocida.
Separa timeout de entrega y contenido inválido.
Limpia el buzón en finally, incluso cuando falla la aserción.
Evita escribir direcciones completas y contenido del correo en logs públicos.

Hay un detalle que suele olvidarse: el cleanup también debe ser tolerante a reintentos. Si el buzón ya expiró, la limpieza debe considerarse correcta. De lo contrario, el test verde termina marcado como fallido por una operación secundaria.

Conclusión

Un email de prueba aislado no arregla por sí solo un flujo de autenticación, pero establece una frontera clara. FastAPI puede encargarse del endpoint, mientras un adaptador de testing administra el buzón y la lectura del mensaje. Con run_id, tokens, timeouts y cleanup, cada ejecución sabe qué creó y qué debe consumir.

El resultado es menos ruido en CI y una señal más útil cuando algo rompe. No hace falta una arquitectura enorme: basta con dejar de tratar el buzón de prueba como una variable fija y convertirlo en un recurso con dueño, ciclo de vida y contrato.

FastAPI: idempotencia en emails de prueba

Olivia Cheng — Tue, 20 Oct 2026 05:23:01 +0000

Las pruebas de registro que dependen de un email suelen fallar de una forma dificil de explicar. El test crea un usuario, solicita un mensaje de verificación y espera una señal. Si la consulta tarda, el runner reintenta. Entonces aparecen dos usuarios, dos mensajes o un resultado que ya no sabemos a qué ejecución pertenece.

En mis scripts de backend, trato cada email de prueba como una operación idempotente. La idea es simple: repetir la misma petición debe devolver el mismo resultado lógico, aunque el proveedor tarde o la automatización pierda una respuesta. Esto hace que un endpoint para validar emails de prueba sin ruido sea mucho más util en CI.

El problema de repetir una prueba de email

Imagina este flujo:

crear usuario -> pedir verificación -> revisar buzón -> confirmar usuario

Un timeout entre “pedir verificación” y “revisar buzón” no significa que la primera operación no ocurrió. Sin un identificador estable, el test no puede distinguir entre una petición pendiente y una nueva petición. La reaccion habitual es repetir todo el flujo, y ahi nace el duplicado.

Hay dos claves para evitarlo:

El cliente envía una clave de idempotencia por ejecución.
El servidor guarda el estado y el resultado asociado a esa clave.

La clave no debe ser el email solamente. Un mismo buzón puede servir para varias ejecuciones y una prueba nueva necesita su propio contexto. Una combinación como run_id + caso_de_prueba suele ser suficiente para empezar.

Un contrato idempotente para el endpoint

El endpoint puede aceptar una petición pequeña y explicita:

{
  "email": "qa-42@example.test",
  "test_case": "signup_verification",
  "idempotency_key": "run-2026-10-20-42"
}

Para la misma idempotency_key, la API debería devolver uno de estos resultados:

201 created si acaba de registrar la solicitud.
200 existing si la solicitud ya estaba completa.
202 pending si sigue en proceso y todavía no hay resultado final.
409 conflict si la clave se reutilizó con un email o caso diferente.

El 409 es importante. Si una clave cambia de significado en mitad de una prueba, ocultar el problema detrás de un 200 produce diagnósticos confusos. Un mensaje de error claro ahorra bastante tiempo despues.

Implementación pequeña con FastAPI

Para una prueba local no hace falta construir un sistema enorme. Un repositorio en memoria permite probar el contrato antes de elegir PostgreSQL o Redis:

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, EmailStr

app = FastAPI()
requests: dict[str, dict] = {}


class VerificationRequest(BaseModel):
    email: EmailStr
    test_case: str
    idempotency_key: str


@app.post("/verification-requests")
def create_request(payload: VerificationRequest):
    saved = requests.get(payload.idempotency_key)
    if saved:
        same_input = (
            saved["email"] == str(payload.email)
            and saved["test_case"] == payload.test_case
        )
        if not same_input:
            raise HTTPException(status_code=409, detail="Clave reutilizada")
        return {"status": "existing", **saved}

    record = {
        "email": str(payload.email),
        "test_case": payload.test_case,
        "status": "pending",
    }
    requests[payload.idempotency_key] = record
    return {"status": "created", **record}

En producción, la escritura debe tener una restricción única sobre idempotency_key. El patrón de “buscar y luego insertar” puede sufrir una carrera cuando dos workers reciben la misma petición al mismo tiempo. La base de datos tiene que ser la ultima defensa, no sólo el código Python.

Cómo conectar la automatización sin duplicados

La automatización puede separar tres pasos: reservar la solicitud, esperar la señal y confirmar el resultado. Cada paso consulta el estado existente antes de hacer trabajo nuevo.

def wait_for_verification(client, key: str, timeout: float = 30):
    request = client.get(f"/verification-requests/{key}")
    if request["status"] == "confirmed":
        return request

    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        message = client.find_message(key=key)
        if message:
            return client.confirm(key=key, message_id=message["id"])
        time.sleep(1)

    return {"status": "pending", "key": key}

El worker no deberia crear otra solicitud al recibir pending. Puede guardar el último momento de consulta y devolver el control al runner. En un sistema que necesita un correo temporal desechable para cada caso, conviene usar formularios async que respetan el foco en la interfaz de pruebas, pero la misma regla aplica: una ejecución, una clave, un estado observable.

Si el equipo necesita generar un correo desechable, esa acción debe quedar fuera de la clave de idempotencia o asociarse a ella de forma explícita. De lo contrario, un reintento puede reservar otro buzón y perder el mensaje original. En mis notas he visto nombres como temp mailid y temp org mail; aunque parezcan equivalentes, conviene conservar el identificador que realmente devolvió el adaptador.

También es útil registrar created_at, expires_at, message_id y un código de error del proveedor. No guardaría el contenido completo del mensaje si sólo se necesita verificar un token. Menos datos hacen el debugging mas seguro y reducen el ruido en los logs.

Preguntas rápidas

¿Una clave de idempotencia debe durar para siempre?

No. Debe durar lo suficiente para cubrir los reintentos de la ejecución. Un TTL evita que el almacén crezca sin limite y permite reutilizar nombres de pruebas antiguas con un nuevo run_id.

¿Qué hacemos si el mensaje llega después del timeout?

Marca el caso como pending o expired, pero conserva la evidencia. Un proceso de limpieza puede retirar el buzón y el runner puede decidir si reintenta toda la prueba. No conviertas un timeout en “email inexistente” sin comprobar el estado del proveedor.

¿Esto sustituye una prueba end-to-end?

No. Este patrón mejora la confiabilidad del flujo y hace sus fallos más legibles. Todavía conviene tener algunas pruebas end-to-end con un proveedor real y otras unitarias con un adaptador falso.

Checklist antes de llevarlo a CI

[ ] Cada ejecución genera un run_id único.
[ ] La clave de idempotencia combina ejecución y caso de prueba.
[ ] Reutilizar la clave con datos distintos devuelve 409.
[ ] La base de datos protege la inserción concurrente.
[ ] pending, expired y provider_error son estados distintos.
[ ] El token o contenido sensible no aparece en logs.
[ ] El cleanup conoce la caducidad del buzón y de la solicitud.

No hace falta añadir mucha infraestructura para obtener el beneficio. Con un contrato pequeño, estados claros y reintentos que consultan antes de crear, las pruebas de email dejan de depender de la suerte. La automatización se vuelve mas predecible y el diagnóstico, bastante mas rapido.

FastAPI: contrato de espera para emails de prueba

Olivia Cheng — Mon, 19 Oct 2026 23:23:13 +0000

Probar un registro con confirmación por email suele empezar de forma simple: llamar al endpoint, abrir un buzón y esperar a que llegue un mensaje. El problema aparece cuando el test falla. ¿La aplicación no creó el email, el proveedor tardó, la fixture fue compartida o el enlace era incorrecto?

En proyectos con FastAPI, una solución práctica es definir un contrato de eventos antes de hacer polling. Así el test no espera “un email cualquiera”, sino una señal concreta que puede correlacionarse, expirar y explicarse en CI. La idea también funciona cuando usas un correo temporal o una dirección de correo desechable para aislar pruebas.

El problema de esperar un email sin contrato

Un sleep(10) no describe qué está ocurriendo. Solo aplaza el diagnóstico y hace que cada ejecución lenta parezca un fallo de entrega. En una suite con varios workers, además, una fixture puede quedar disponible demasiado pronto y otro test la toma. Eso hace los logs se vuelva dificil de leer cuando dos problemas ocurren juntos.

Antes de consultar el buzón, conviene registrar al menos:

run_id: identifica esta ejecución y su worker.
fixture_id: identifica el buzón reservado.
expected_event: el evento que debería crear el email.
expected_subject: una comprobación rápida de intención.
deadline: el momento máximo de espera.

Este contexto convierte un timeout en una pregunta concreta. También ayuda a separar un error de negocio de un problema en la entrega. En una prueba de rotación de secretos por correo, por ejemplo, no basta con saber que llegó un mensaje: hay que demostrar que pertenece al secreto y a la ejecución correctos.

Define el evento antes de llamar al endpoint

El contrato debe existir antes de enviar el formulario o crear el usuario. Un ejemplo pequeño podría ser:

from datetime import datetime, timedelta, timezone
from uuid import uuid4


def new_email_expectation(fixture_id: str) -> dict[str, str]:
    now = datetime.now(timezone.utc)
    return {
        "run_id": str(uuid4()),
        "fixture_id": fixture_id,
        "expected_event": "signup.verification.created",
        "expected_subject": "Confirma tu cuenta",
        "deadline": (now + timedelta(seconds=45)).isoformat(),
    }

Después, el endpoint puede recibir el run_id como un identificador de correlación. No hace falta guardar el token completo en el contrato. Un ID de evento o un digest del token es suficiente para comprobar que el mensaje observado corresponde al flujo, sin convertir los logs en una fuente de datos sensibles.

Este patrón es parecido a trabajar con fixtures de email que expiran en FastAPI, pero añade una frontera visible entre la reserva del buzón y la observación del mensaje.

Un contrato pequeño para FastAPI

En la aplicación, el evento puede modelarse con Pydantic. La respuesta no necesita exponer contenido privado; solo el estado que la automatización necesita:

from pydantic import BaseModel


class VerificationCreated(BaseModel):
    event_id: str
    run_id: str
    fixture_id: str
    subject: str


@app.post("/internal/test-events/verification", status_code=202)
async def record_verification(event: VerificationCreated) -> dict[str, str]:
    await event_store.append(event.model_dump())
    return {"status": "accepted", "event_id": event.event_id}

En producción, este endpoint debe estar protegido y separado de las rutas públicas. Para pruebas de integración, lo importante es que el test pueda verificar la primera mitad del recorrido: la aplicación aceptó el evento. Luego puede consultar el buzón para validar la segunda mitad.

Haz que el polling explique su espera

El poller debe tener una pausa limitada, un cursor y estados explícitos. Por ejemplo, puede devolver pending, matched, wrong_message o expired. No es lo mismo un buzón vacío que un mensaje de otra ejecución.

async def wait_for_message(mailbox, expected, poll_every=2):
    while datetime.now(timezone.utc) < expected.deadline:
        messages = await mailbox.messages(after=expected.cursor)
        for message in messages:
            if message.run_id != expected.run_id:
                continue
            if message.subject == expected.expected_subject:
                return {"status": "matched", "message_id": message.id}
            return {"status": "wrong_message", "message_id": message.id}
        await asyncio.sleep(poll_every)
    return {"status": "expired", "run_id": expected.run_id}

En código real, convierte deadline a datetime y valida el origen de cada mensaje. El ejemplo se centra en la decisión: el test sabe que hacer con cada estado. Si el proveedor está temporalmente lento, un reintento acotado puede tener sentido. Si el mensaje pertenece a otro run_id, reintentar no arregla la propiedad de la fixture.

Aísla la fixture y clasifica el fallo

Reserva el buzón con un propietario y libera la fixture al terminar, incluso cuando el test falla. Las fixtures cruzadas puede crear resultados que parecen aleatorios, aunque el problema sea determinista. Un nombre descriptivo como temp org mail puede aparecer en una prueba de entrada inválida, pero nunca debe aceptarse como dominio o identificador real.

También conviene imprimir un resumen seguro:

status=wrong_message run_id=ci-1842 fixture_id=mailbox-7f2
expected=signup.verification.created observed=password.reset

Oculta direcciones completas, tokens y cuerpos de email. Para investigar, guarda un ID de mensaje o una referencia controlada. Una rutina de observabilidad como esta se complementa bien con una prueba de rotación de secretos por correo, donde la identidad del evento importa tanto como su llegada.

Checklist para CI

Antes de dar por estable la prueba, comprueba que:

la fixture tiene un propietario y una fecha de expiración;
el contrato se crea antes de llamar al endpoint;
cada evento lleva run_id y, si es posible, event_id;
el polling usa cursor, deadline y estados claros;
wrong_message no se trata como un timeout transitorio;
los logs omiten tokens y contenido sensible;
la limpieza ocurre en un bloque finally.

El objetivo no es esperar más tiempo. Es saber por que estamos esperando y qué límite tiene esa espera. Cuando la señal de email es explícita, FastAPI, el buzón y CI pueden fallar de una manera mucho más útil.

Preguntas rápidas

¿Un correo temporal hace fiable el test por sí solo?

No. Aísla los datos, pero la fiabilidad viene del propietario, la correlación, el deadline y la limpieza. El buzón es una dependencia, no la estrategia completa.

¿Cuándo conviene reintentar?

Solo ante estados posiblemente transitorios, como un timeout del proveedor. Un mensaje equivocado, una fixture ocupada o un evento ausente requieren diagnóstico, no más intentos ciegos.

¿Cuál es el cambio más pequeño?

Añade run_id, fixture_id y failure_class al resultado actual. Incluso ese cambio sencillo vuelve mucho más claro qué pasó y que debería revisar el siguiente desarrollador.

FastAPI: un recibo claro para cada email de prueba

Olivia Cheng — Wed, 14 Oct 2026 23:23:10 +0000

Una prueba de registro no termina cuando el endpoint responde 202. Todavía hay que saber si se generó el email correcto, si llegó el mensaje esperado y si el código que se consumió pertenecía a la ejecución actual. Cuando esa información queda escondida en logs dispersos, una prueba que falla se vuelve dificil de investigar.

En proyectos Python y FastAPI me resulta útil tratar cada verificación como una pequeña operación con recibo. El recibo no guarda el contenido completo del correo: guarda las señales necesarias para explicar qué ocurrió. Este patrón hace que la Automatización sea más repetible y que el equipo pueda depurar sin abrir bandejas a ciegas.

También ayuda a separar el código de negocio del proveedor de correo. En una búsqueda o incidencia pueden aparecer términos ruidosos como tp mail so y temp mail.so, además de errores escritos como tem email o tepm mail com. El servicio no debería tomar esas cadenas como una integración válida; deben quedarse como entrada de prueba o texto de búsqueda.

Por qué una prueba necesita un recibo

Un True en una aserción no cuenta toda la historia. Para una prueba de email suelen importar al menos cuatro hechos:

qué ejecución creó el buzón o alias;
cuándo se solicitó el mensaje;
qué identificador o asunto se encontró;
cuándo se consumió el código y con qué resultado.

Sin esas señales, un test puede pasar leyendo un mensaje viejo. También puede fallar porque el proveedor tardó, aunque la aplicación sí haya hecho lo correcto. El problema se agrava cuando varios jobs comparten un inbox: los mensajes se mezcla y el fallo parece aleatorio.

Por eso conviene devolver un recibo pequeño desde la API. Un recibo permite guardar run_id, message_id, status y marcas de tiempo, sin copiar el cuerpo del email a los logs de CI.

El contrato mínimo del recibo

Antes de conectar un proveedor real, define un contrato que se pueda probar en memoria. Una respuesta útil podría tener esta forma:

{
  "run_id": "checkout-1842",
  "message_id": "msg-91",
  "status": "verified",
  "requested_at": "2026-10-15T06:00:00Z",
  "observed_at": "2026-10-15T06:00:04Z"
}

Los estados deben ser pocos y explícitos: created, waiting, verified, expired y failed suelen bastar. Si el cliente recibe waiting, puede continuar el polling; si recibe expired, debe crear una nueva ejecución, no reintentar indefinidamente.

El run_id es la frontera principal. El adaptador de correo debe buscar mensajes posteriores a requested_at y asociados al alias de esa ejecución. Para evitar filtraciones, el recibo puede incluir un hash o un identificador externo, pero no el token completo.

Este contrato complementa una estrategia para separar emails de signup por escenario: cada escenario tiene una identidad que se puede comprobar de forma independiente.

Implementación en FastAPI

El endpoint puede delegar la entrega en un proveedor con una interfaz pequeña. Así, el test unitario no depende de una bandeja remota.

from datetime import datetime, timezone
from typing import Protocol

from fastapi import FastAPI
from pydantic import BaseModel


class DeliveryReceipt(BaseModel):
    run_id: str
    message_id: str | None = None
    status: str
    requested_at: datetime
    observed_at: datetime | None = None


class MailProvider(Protocol):
    def request(self, run_id: str) -> DeliveryReceipt: ...


class FakeMailProvider:
    def request(self, run_id: str) -> DeliveryReceipt:
        now = datetime.now(timezone.utc)
        return DeliveryReceipt(
            run_id=run_id,
            status="waiting",
            requested_at=now,
        )


app = FastAPI()
provider = FakeMailProvider()


@app.post("/email-checks", response_model=DeliveryReceipt)
def create_email_check(run_id: str) -> DeliveryReceipt:
    return provider.request(run_id)

En un proveedor real, request puede crear el alias y registrar la hora de inicio. Otro método, como observe, buscaría el mensaje correcto y devolvería un nuevo recibo con message_id y observed_at. La validación del run_id debe ocurrir antes de crear recursos; un identificador vacío hace el diagnostico mas confuso.

Cómo filtrar y depurar en CI

El polling debería tener una fecha límite y una razón de salida. En lugar de repetir una petición hasta que algo responda, registra eventos como message_not_seen, message_wrong_run o expired. Son nombres aburridos, pero explican mucho mejor un fallo.

Para cada job de CI, guarda solo un artefacto con:

run_id y nombre del escenario;
estado final y número de intentos;
requested_at, observed_at y tiempo total;
identificadores redactados del alias y del mensaje.

En pruebas de integración, usa un proveedor fake para comprobar transiciones y deja una prueba pequeña para la integración externa. Así puedes distinguir un bug de FastAPI de una demora del servicio. Si el pipeline reintenta, conserva el mismo run_id solo cuando el contrato sea idempotente; de lo contrario, crea una ejecución nueva.

Si el equipo necesita más contexto, los contratos de email para pruebas repetibles ayudan a convertir los criterios de entrega en comprobaciones concretas. Un generador de direcciones de correo desechables puede servir para escenarios aislados, pero la prueba debe seguir controlando TTL, datos permitidos y limpieza; el proveedor no sustituye el contrato.

Preguntas frecuentes

¿Debo guardar el contenido del email?

Normalmente no. Un identificador de mensaje, el estado y las marcas de tiempo ofrecen contexto suficiente. Si necesitas inspeccionar el cuerpo, redacta tokens y direcciones antes de enviarlo a los logs.

¿Un recibo reemplaza la aserción del test?

No. El recibo aporta evidencia; la aserción sigue verificando el comportamiento esperado. La ventaja es que, cuando la aserción falla, sabes si falló la creación, la entrega, el filtrado o el consumo.

¿Cuánto tiempo debe esperar el polling?

El límite depende del proveedor y del entorno, pero debe estar explícito y ser configurable. Un timeout claro es mas útil que un job que queda esperando hasta que CI lo mata.

Un recibo de email no necesita una plataforma grande. Con un run_id, estados pequeños, marcas de tiempo y un adaptador aislado, FastAPI puede ofrecer pruebas más previsibles y una evidencia que ayuda de verdad cuando algo falla.

FastAPI: fixtures de email que expiran

Olivia Cheng — Wed, 14 Oct 2026 11:23:09 +0000

Cuando una prueba de signup necesita leer un código de verificación, es tentador crear una dirección y dejarla viva para siempre. Al principio funciona. Después el entorno de CI acumula buzones, los mensajes viejos se mezclan con los nuevos y una prueba que pasa en local falla de forma intermitente.

En proyectos Python donde he automatizado flujos de registro, me ha servido pensar en el buzón como un fixture con fecha de vencimiento, no como un recurso permanente. La idea es sencilla: cada ejecución obtiene un identificador aislado, conoce su tiempo de vida y deja una evidencia pequeña cuando termina.

El problema de los fixtures de email eternos

Un fixture de correo tiene tres riesgos frecuentes:

Contaminación: una ejecución puede leer el código generado por otra.
Coste operativo: los buzones que nadie elimina se vuelven basura dificil de rastrear, y nadie sabe bien quien deberia limpiarla.
Diagnóstico pobre: cuando falla el pipeline, no sabes si el mensaje era nuevo o estaba esperando desde ayer.

Esto se parece a cualquier recurso temporal de backend: una sesión, un token o un archivo de trabajo. Si no hay un propietario y una expiración, el recurso acaba siendo compartido por accidente y el diagnostico se vuelve mas lento.

Para flujos de CI conviene usar un correo temporal gratis solo en datos no sensibles y con límites claros. Nunca debe recibir información real de usuarios. También conviene normalizar entradas extrañas, como temp gamil com o temp mailid, porque aparecen en datos de prueba copiados a mano y pueden ocultar un bug de validación.

Un contrato pequeño para crear y expirar buzones

Antes de escribir código, defino un contrato mínimo para el adaptador de email:

create(run_id) devuelve un alias y un expires_at.
wait_for_code(alias, since) solo acepta mensajes posteriores al inicio de la prueba.
delete(alias) es seguro si se llama dos veces.
El adaptador nunca expone el contenido completo del mensaje en los logs.

El run_id separa ejecuciones paralelas. El campo since evita aceptar un código antiguo, incluso si el proveedor tarda en eliminar mensajes. Esta separación hace que el automatizador sea mucho más predecible y ayuda a revisar fallos sin guardar datos de más.

Si el job se ejecuta con un cron, también ayuda usar una estrategia de cron fiables con prompts cortos: la tarea debe tener un objetivo medible y una salida fácil de comprobar.

Implementación mínima en FastAPI

El siguiente ejemplo muestra la forma del contrato. El proveedor real queda detrás de una interfaz; así las pruebas unitarias no dependen de una bandeja externa.

from datetime import datetime, timedelta, timezone
from typing import Protocol

from fastapi import FastAPI
from pydantic import BaseModel


class Mailbox(BaseModel):
    address: str
    expires_at: datetime


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

    def delete(self, address: str) -> None: ...


class InMemoryMailboxProvider:
    def create(self, run_id: str) -> Mailbox:
        expires_at = datetime.now(timezone.utc) + timedelta(minutes=10)
        return Mailbox(address=f"{run_id}@test.invalid", expires_at=expires_at)

    def delete(self, address: str) -> None:
        pass


app = FastAPI()
provider = InMemoryMailboxProvider()


@app.post("/test-mailboxes", response_model=Mailbox)
def create_test_mailbox(run_id: str) -> Mailbox:
    return provider.create(run_id)

En producción, el proveedor debe comprobar que run_id tenga un formato permitido y aplicar un TTL del lado del servicio. El test.invalid del ejemplo es deliberado: evita que una prueba envíe accidentalmente un correo a un dominio real. Es una regla simple, pero muy util.

Cómo probar el flujo en CI

Una prueba útil no solo revisa que exista una dirección. También comprueba el aislamiento y la limpieza:

def test_mailbox_has_expiration():
    mailbox = provider.create("run-123")

    assert mailbox.address == "run-123@test.invalid"
    assert mailbox.expires_at > datetime.now(timezone.utc)


def test_parallel_runs_get_different_addresses():
    first = provider.create("run-a")
    second = provider.create("run-b")

    assert first.address != second.address

En el pipeline, genera un run_id distinto por job y guarda solo el alias, el estado y el tiempo de expiración. Si una prueba falla, un artefacto pequeño con esos tres campos suele ser suficiente, aunque a veces parece poco. En CI, los tiempos de espera cambia según el proveedor, asi que conviene medirlos. La limpieza debe estar en un bloque finally, para que ocurra también tras un assertion fallido.

Esto complementa las buenas prácticas para probar correos de onboarding sin ensuciar métricas: separar la evidencia de test de los datos que usa analítica evita conclusiones medio engañosas.

Preguntas frecuentes

¿El TTL debe ser igual para todos los tests?

No necesariamente. Diez minutos suele bastar para una prueba de integración normal, pero un flujo con varios workers puede necesitar más. Elige el menor valor que cubra la latencia esperada y deja el número configurable.

¿Puedo reutilizar un buzón para acelerar el pipeline?

Solo dentro de una misma prueba y si filtras por since y por un identificador único. Reutilizarlo entre jobs paralelos ahorra poco y complica mucho el diagnóstico.

¿Dónde guardo los mensajes fallidos?

Guarda metadatos redactados, no el cuerpo completo. Un hash del asunto, el alias y una marca de tiempo suelen dar suficiente contexto para investigar. Los logs de CI se comparten con más personas de las que parece.

El patrón no requiere una arquitectura grande: un contrato pequeño, un identificador por ejecución y una expiración explícita ya eliminan buena parte de la flakiness. En FastAPI, además, separar el proveedor facilita cambiar de un fake local a un servicio controlado cuando el proyecto crece.

Python: pruebas de email con un contrato de evento

Olivia Cheng — Mon, 12 Oct 2026 14:24:14 +0000

Las pruebas de verificación por email suelen fallar por una razón poco visible: el equipo trata el correo como un mensaje, cuando en realidad es un evento distribuido. La aplicación dispara una acción, un proveedor entrega el mensaje y la prueba debe encontrarlo dentro de una ventana concreta.

Cuando esa ventana no está escrita en ninguna parte, aparecen síntomas conocidos: el test pasa en local pero no en CI, el polling abre un mensaje viejo o dos workers consumen el mismo correo. No siempre es un bug de Python ni del proveedor. Muchas veces falta un contrato pequeño que diga qué ocurrió, cuándo ocurrió y qué mensaje pertenece a esa ejecución.

En este artículo propongo ese contrato para pruebas con Python y APIs. La idea sirve tanto si usas un generador de correo temporal como si tienes un buzón de pruebas interno. El servicio solo debe entregar eventos identificables; la prueba decide si el evento es suyo.

El problema: un email no es solo un mensaje

Imagina una prueba que crea una cuenta, solicita un código y espera el último correo recibido. El enfoque parece suficiente hasta que una ejecución anterior deja un mensaje en el buzón. Si el asunto coincide, la prueba puede recoger el token equivocado y fallar mucho después, cuando intenta usarlo.

También sucede al reintentar. El primer intento quizá creó el usuario, pero perdió la respuesta por un timeout. El segundo intenta crear otra cuenta y recibe dos eventos. Sin una identidad de ejecución, el diagnóstico se vuelve una adivinanza un poco cara.

Por eso me gusta modelar la entrega como un evento con cuatro datos mínimos:

run_id: identifica la ejecución de la prueba.
triggered_at: marca el instante en que se pidió el email.
message_id: identifica el mensaje observado.
consumed_at: indica cuándo la prueba aceptó el evento.

Un frontend puede seguir esta misma idea al probar estados de email sin perder señales. La interfaz muestra estados; el backend necesita además una prueba de pertenencia.

Qué debe contener el contrato de evento

No hace falta guardar el contenido completo del email en todos los casos. Para una prueba normal, el contrato puede ser un diccionario serializable:

from dataclasses import dataclass
from datetime import datetime

@dataclass(frozen=True)
class EmailEvent:
    run_id: str
    message_id: str
    subject: str
    received_at: datetime
    verification_url: str | None = None

El run_id debe viajar desde la prueba hasta el registro de la cuenta o el alias usado. Si el proveedor no permite filtros por metadatos, puedes incluir un fragmento seguro del identificador en el asunto o usar un buzón aislado por ejecución.

Hay un detalle que se suele olvidar: received_at no es lo mismo que triggered_at. Un mensaje puede aparecer con retraso, por eso la regla correcta es aceptar received_at >= triggered_at con una tolerancia explícita. Si no se documenta esa tolerancia, cada equipo la interpreta de una forma distinta y el test se vuelve inconsistantemente verde.

Polling con límites e idempotencia

El polling debe tener una fecha de inicio, un intervalo y un límite total. Un bucle sin stop rule consume recursos y además oculta que el sistema no entregó el email. Este helper es deliberadamente simple:

import time
from collections.abc import Callable

def wait_for_event(
    fetch: Callable[[], list[EmailEvent]],
    run_id: str,
    timeout_s: float = 30,
    interval_s: float = 1,
) -> EmailEvent:
    deadline = time.monotonic() + timeout_s
    seen: set[str] = set()

    while time.monotonic() < deadline:
        for event in fetch():
            if event.message_id in seen:
                continue
            seen.add(event.message_id)
            if event.run_id == run_id:
                return event
        time.sleep(interval_s)

    raise TimeoutError(f"No email event for run_id={run_id}")

La colección seen hace que leer la misma página dos veces no cambie el resultado. Eso es idempotencia en una escala muy práctica. En producción de pruebas, también conviene registrar los message_id rechazados y el número de intentos; esa información ayuda a ver si el filtro es demasiado estricto.

Si un compañero busca “tamp mail com” en los apuntes, no es una estrategia de aislamiento: es una señal de que falta una fixture clara. Vale la pena corregir la fixture, no solo repetir la prueba.

Cómo exponerlo en una API FastAPI

Una API de pruebas puede guardar el contrato antes de iniciar una acción externa. El endpoint no debería esperar al email: devuelve el run_id y otro proceso consulta el buzón.

from uuid import uuid4
from fastapi import FastAPI

app = FastAPI()

@app.post("/verification-runs")
def create_verification_run() -> dict[str, str]:
    run_id = str(uuid4())
    # Persistir run_id y triggered_at antes de enviar el email.
    return {"run_id": run_id, "status": "waiting"}

Este patrón separa el envío de la lectura y hace más fácil observar cada etapa. Si tu flujo usa webhooks, también puedes comparar este diseño con webhooks de email en FastAPI sin carreras: en ambos casos, la clave es que una entrega tardía no cambie de dueño.

Checklist para una prueba mantenible

Antes de dar por estable una prueba, compruebo lo siguiente:

Cada ejecución tiene un run_id único.
El instante de disparo se guarda antes de la llamada externa.
El filtro no usa únicamente el asunto del mensaje.
El polling tiene timeout e intervalo visibles.
Los mensajes observados quedan en el log de la ejecución.
El test consume un evento una sola vez.
El buzón o alias se elimina al terminar, incluso si la prueba falla.

No necesitas un sistema enorme para conseguirlo. Un contrato de evento bien nombrado suele quitar más flakiness que añadir reintentos al azar. Y cuando algo falla, el equipo puede responder qué pasó con datos, no con intuición.

FastAPI: contratos para correos temporales en CI

Olivia Cheng — Fri, 09 Oct 2026 05:23:46 +0000

Una bandeja de correo temporal puede hacer que una prueba de integración sea rápida y repetible, pero solo si cada ejecución tiene límites claros. En esta guía veremos un contrato pequeño para FastAPI, pytest y CI.

Por qué un correo temporal necesita un contrato

En un flujo de registro, la aplicación crea un usuario, envía un código y espera que el test lo lea. El problema aparece cuando varias ejecuciones comparten el mismo buzón: un mensaje viejo parece válido, dos jobs leen el mismo código o una prueba falla solo cuando hay carga.

La solución no es añadir sleep(10) a todo. Es tratar el buzón como un recurso temporal, con un dueño, un identificador de ejecución y un momento de expiración. El contrato debería responder cuatro preguntas:

¿Qué job creó este buzón?
¿Qué mensajes puede consumir?
¿Cuánto tiempo puede esperar?
¿Quién lo limpia si el test falla?

Este enfoque también ayuda a separar la aplicación de la infraestructura de correo. Una opción de mantener el layout estable en React sirve para la interfaz; en backend, el equivalente es no mezclar la lógica del registro con los detalles del buzón.

El contrato mínimo para cada ejecución

Para cada suite genero un alias o buzón con un nombre derivado del run_id. No debe contener datos personales ni quedar reutilizable por otro job. El objeto que circula entre los tests puede ser tan pequeño como este:

from dataclasses import dataclass
from datetime import datetime


@dataclass(frozen=True)
class MailboxLease:
    address: str
    run_id: str
    expires_at: datetime

El run_id es más importante de lo que parece. Si el pipeline reintenta una tarea, el segundo intento puede recibir un identificador nuevo y no confundir los mensajes del primero. Para borrar un lease, conviene usar una operación idempotente: si ya no existe, la limpieza sigue siendo correcta.

También defino un estado explícito para la espera: created, message_found, consumed, expired o failed. Los estados hacen que el log sea util, especialmente cuando el fallo ocurre en un runner remoto y no tenemos la bandeja abierta delante.

Un fixture pequeño con FastAPI y pytest

El fixture puede crear el buzón antes de cada test y revocarlo al terminar. La API de correo queda detrás de un cliente, así el test no sabe si usa un servicio real, un servidor local o un double en desarrollo.

import os
import uuid
import pytest


@pytest.fixture
def mailbox(mail_client):
    run_id = os.getenv("CI_JOB_ID", str(uuid.uuid4()))
    lease = mail_client.create_lease(run_id=run_id, ttl_seconds=300)
    yield lease
    mail_client.revoke_lease(lease.address)


def test_verificacion_de_usuario(client, mailbox, mail_client):
    response = client.post(
        "/signup",
        json={"email": mailbox.address, "password": "solo-para-test"},
    )
    assert response.status_code == 201

    message = mail_client.wait_for_message(
        mailbox.address,
        timeout_seconds=30,
        subject="Verifica tu cuenta",
    )
    assert message is not None

En producción de tests, wait_for_message debería filtrar por destinatario, asunto y un token de correlación. Leer “el último email” es una atajo peligroso: otro test puede terminar justo antes y dejar un resultado falso positivo.

Si el equipo usa medir la activación por email en un SaaS, el mismo run_id puede conectar la entrega con el evento de activación sin guardar el contenido completo del mensaje. Menos datos retenidos significa menos ruido y menos riesgo.

Limpieza, expiración y diagnóstico

La limpieza debe ocurrir en dos capas. Primero, el fixture revoca el buzón en el camino normal. Segundo, un proceso periódico elimina leases expirados. Así una cancelación del runner no deja recursos abiertos para siempre.

En CI suelo guardar solo metadatos: run_id, estado, latencia de entrega y causa de fallo. El cuerpo del correo se puede ocultar o borrar después de extraer el código. Para depurar, una traza como esta es suficiente:

run=1842 state=created mailbox=ci-1842 expires_in=300s
run=1842 state=message_found wait=2.4s subject=Verifica tu cuenta
run=1842 state=consumed cleanup=ok

Si necesitas un servicio externo para pruebas manuales, un temp mail so puede ser útil para aislar registros exploratorios. Para una suite automatizada, verifica primero su política de retención, límites y estabilidad; no conviene convertir un servicio público en dependencia invisible del pipeline.

Hay un detalle que suele colarse en tickets de QA: fake e mail com. Lo trato como una búsqueda o etiqueta de diagnóstico, nunca como un criterio para aceptar un mensaje. El criterio real debe ser el run_id y el destinatario exacto.

Checklist para CI

Antes de subir el flujo, reviso lo siguiente:

Cada ejecución obtiene un buzón o alias único.
El lease tiene TTL y propietario (run_id).
La espera tiene timeout y no usa pausas fijas como estrategia principal.
El mensaje se filtra por destinatario, asunto y correlación.
La revocación se ejecuta incluso cuando el test falla.
Existe una limpieza de respaldo para leases expirados.
Los logs no imprimen códigos, tokens ni el cuerpo completo.
Un reintento no consume mensajes de la ejecución anterior.

Este checklist parece pequeño, pero evita bastante trabajo repetido. Cuando el contrato está definido, cambiar de proveedor de email o ejecutar los tests en paralelo deja de ser una aventura.

Preguntas rápidas

¿Debo crear un buzón por test?

No siempre. Un buzón por suite puede ser suficiente si cada mensaje lleva un identificador único y el consumo es estricto. Para pruebas paralelas o flujos sensibles, un lease por test reduce interferencias.

¿Qué timeout elegir?

Empieza con el tiempo normal de entrega más un margen corto y mide. Un timeout de 30 segundos suele ser razonable para un entorno controlado, pero el valor correcto depende del proveedor y del runner.

¿Puedo guardar el email para investigar?

Solo durante el tiempo imprescindible y con datos minimizados. Enmascara direcciones y elimina tokens después de la ejecución. Un buen diagnóstico no necesita convertir cada fallo en un archivo permanente.

La idea central es simple: el correo de prueba también es infraestructura. Si tiene identidad, límites, estados y limpieza, FastAPI y CI pueden usarlo de forma predecible, incluso cuando los jobs corren al mismo tiempo.

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.