DEV Community: Silviu Technology

Agentes LLM: simula login social sin falsos positivos

Silviu Technology — Tue, 29 Sep 2026 23:23:37 +0000

Cuando un agente LLM prueba un signup con login social, “el botón respondió” no significa que el flujo sea correcto. Puede haber usado una identidad vieja, seguir una sesión de navegador equivocada o confirmar una cuenta distinta de la que el test esperaba. El resultado parece verde, pero la evidencia es debil.

En workflows de desarrollo con agentes, trato la identidad de prueba como una dependencia explícita, no como un detalle del navegador. El agente puede elegir el siguiente paso y explicar un fallo, pero un contrato pequeño debe demostrar qué identidad se usó, qué estado cambió y qué señales fueron observadas.

El problema: un agente puede completar el flujo equivocado

Un login social tiene más estado que un formulario de email y contraseña. Hay una sesión del proveedor, cookies del navegador, consentimiento, redirecciones y, a veces, un email de confirmación. Si todo eso vive en el mismo perfil, un agente puede “pasar” porque heredó una sesión que ya estaba autenticada.

Los falsos positivos más comunes son estos:

El navegador conserva cookies de una cuenta anterior.
El proveedor redirige al entorno equivocado.
El email asociado a la identidad no coincide con el usuario creado.
El agente lee un mensaje antiguo y lo toma por la confirmación actual.
Un reintento crea otra cuenta, aunque el resumen solo diga ok.

La solución no es pedirle al modelo que sea mas cuidadoso. Es dividir el flujo en hechos verificables. Como en otros sistemas con correo, conviene pensar los correos de prueba como una señal operativa, con una edad, un identificador y un contexto de ejecución.

Qué significa simular un login social

Simular no quiere decir falsificar una cuenta real ni probar contra producción. Quiere decir construir una identidad sintética controlada en staging, con permisos mínimos y un ciclo de vida corto. El agente debe recibir una referencia como identity-qa-17, no una contraseña pegada en el prompt.

El mapa mental es sencillo:

identidad sintética -> sesión aislada -> login social -> signup
          |                |                |             |
       contrato       cookies nuevas    redirect host   evento de dominio

Cada flecha tiene una comprobación. Si la sesión no es nueva, el test se detiene. Si el redirect_uri no apunta a staging, se marca como fallo de seguridad. Si el evento de dominio no contiene la misma referencia de identidad, no se afirma que el signup terminó.

El contrato de identidad sintética

Un fixture útil puede describirse con pocos campos:

{
  "identity_ref": "identity-qa-17",
  "provider_subject": "provider-subject-91",
  "email_ref": "inbox-qa-17",
  "environment": "staging",
  "session_started_at": "2026-09-30T06:00:00Z",
  "expires_at": "2026-09-30T06:15:00Z"
}

provider_subject es un identificador de prueba, no un dato personal. email_ref apunta al fixture de correo sin escribir el contenido completo en cada log. El contrato tambien necesita expiración: una identidad de staging que sobrevive semanas termina pareciéndose demasiado a una cuenta compartida.

Para flujos que envían un código o un enlace, el adaptador de correo debería devolver solo candidatos recientes, su message_id y metadatos sanitizados. La comparación del asunto, del host y de la antigüedad debe ser código determinista. Un LLM puede interpretar “el proveedor rechazó el consentimiento”, pero no debe inventar que una identidad fue verificada.

Cuando el signup necesita reenvíos, es útil diseñar reenvíos seguros en un signup con el mismo run_id. Así un reintento queda relacionado con el intento original y no se confunde con un nuevo usuario.

Implementación por checkpoints

Un workflow manejado por un agente puede tener cinco checkpoints:

Preparar: crear run_id, fixture de identidad, inbox lógico y expectativas.
Aislar: abrir un contexto de navegador limpio y comprobar que no hay cookies previas.
Actuar: ejecutar el login social y capturar el host de cada redirección.
Observar: consultar los eventos de autenticación y el mensaje de confirmación esperado.
Verificar: comparar referencias, timestamps y estado final antes de emitir el recibo.

El recibo debería decir verified, timeout, redirect_mismatch o ambiguous. “Ambiguous” es un resultado valido: obliga a investigar en vez de convertir señales incompletas en éxito. En CI, guardaría el recibo y un snapshot pequeño; guardar todo el cuerpo del email hace el debugging mas costoso y aumenta la retención de datos.

Tradeoffs y límites

La identidad sintética reduce contaminación entre tests, pero añade una fábrica de fixtures y una política de expiración. Un proveedor social real puede cambiar su pantalla o imponer límites, por lo que no conviene depender de una prueba end-to-end para cada commit.

Mi separación práctica es usar tres capas: pruebas de contrato para el adaptador, pruebas de integración con un proveedor controlado y pocas pruebas end-to-end nocturnas. El agente participa en la preparación y en el diagnóstico; las aserciones críticas permanecen en código. Es menos flexible, pero mucho mas fácil de auditar.

Checklist para el siguiente workflow

¿La identidad tiene identity_ref y fecha de expiración?
¿El navegador empieza sin cookies ni sesiones heredadas?
¿Cada redirección comprueba el host esperado?
¿El email se vincula por run_id, message_id y antigüedad?
¿Un reintento conserva la relación con el intento original?
¿Los logs evitan secretos, cuerpos completos y datos personales?
¿El resultado puede ser ambiguous sin forzar un falso éxito?

Un agente LLM es muy útil para coordinar pasos y resumir evidencia. El límite sano es que no sea la fuente de verdad sobre la identidad, el correo o el estado de autenticación. Si el sistema deja ese contrato claro, hasta una nota con temp mailid o dummy e mail se puede rastrear sin convertirla en una cuenta permanente. Y el resultado deja de ser “parece que funcionó” para convertirse en una señal que otro proceso puede revisar.

FastAPI: reintentos seguros para emails de prueba

Silviu Technology — Tue, 29 Sep 2026 02:23:21 +0000

Los flujos de email de prueba suelen fallar por una razón poco visible: un timeout no significa que la operación no ocurrió. Un cliente puede repetir la llamada, un worker puede procesar el mismo evento dos veces y un test puede hacer polling mientras el estado todavía cambia.

En proyectos Python suelo tratar este problema como un contrato de API, no como un simple try/except. La idea es que cada reintento tenga una respuesta predecible, que el backend no duplique el trabajo y que los logs permitan entender lo que pasó. Este patrón funciona especialmente bien con FastAPI y es fácil de adaptar a automatización de CI.

El problema: un reintento no es una nueva operación

Imagina un endpoint que crea un buzón de prueba y espera un mensaje:

POST /test-mailboxes
{
  "purpose": "signup"
}

Si la respuesta tarda más que el timeout del cliente, repetir el POST puede crear dos recursos. El test quizá solo observa uno y deja el segundo consumiendo espacio. En una ejecución puntual parece un fallo de red, pero despues se convierte en datos huérfanos y resultados difíciles de comparar.

La solución empieza con una distinción sencilla: el request_id identifica la petición, mientras que la Idempotency-Key identifica la operación que se puede repetir. La segunda debe persistirse durante el tiempo suficiente para que el cliente reciba el resultado original.

Define estados antes de escribir el endpoint

Para un flujo de email de prueba, unos estados pequeños son más útiles que una cadena de mensajes libres:

created -> waiting_for_message -> received
                         \-> expired
                         \-> failed

Cada transición debería guardar updated_at, un motivo corto y un identificador de correlación. No guardes el mensaje completo en el log: con el asunto, el message_id hash y el tamaño suele bastar para investigar.

También conviene separar el estado de la solicitud del estado del mensaje. Una solicitud puede estar completed aunque el mensaje recibido sea un rebote, por ejemplo. Esa separación evita que un reintento cambie silenciosamente el significado del resultado.

Si el producto necesita generar una dirección para pruebas, una búsqueda como temp mail generator puede llevar a opciones distintas; en el código importa más definir la duración, el aislamiento y la limpieza del recurso. Para pruebas manuales, obtener un correo temporal puede ser útil, pero no lo uses para datos personales ni como dependencia oculta de una suite automatizada.

Una clave de idempotencia en FastAPI

El handler puede recibir la clave desde una cabecera y delegar la decisión a una capa de servicio. El ejemplo es pequeño a propósito:

from fastapi import FastAPI, Header, HTTPException

app = FastAPI()

@app.post("/test-mailboxes")
async def create_mailbox(
    purpose: str,
    idempotency_key: str | None = Header(default=None, alias="Idempotency-Key"),
):
    if not idempotency_key:
        raise HTTPException(status_code=400, detail="Falta Idempotency-Key")

    cached = await store.find_request(idempotency_key)
    if cached:
        return cached.response

    result = await mailbox_service.create(purpose=purpose)
    await store.save_request(idempotency_key, result.response)
    return result.response

En producción, find_request y save_request deben participar en una garantía real de unicidad. Un diccionario en memoria sirve para una demo, pero no para varios workers. Usa una restricción única en PostgreSQL o Redis con una política de expiración y considera qué ocurre si el proceso muere después de crear el buzón pero antes de guardar la respuesta.

La clave también debe estar ligada a una huella de la petición. Si el mismo cliente reutiliza la clave con otro purpose, responde 409 Conflict. Aceptarlo como si nada produce bugs muy raros de reproducir.

Polling y webhooks con evidencia útil

El polling necesita límites claros: intervalo, deadline y estado terminal. Un test que pregunta indefinidamente oculta una regresión. Una implementación simple puede usar backoff y detenerse cuando received, expired o failed aparece.

Para el equipo frontend, es útil validar emails sin respuestas viejas y mostrar el correlation_id cuando algo termina. Si el trabajo tarda, una cola con estados visibles también ayuda a hacer visibles las colas de emails largos.

Un webhook debe ser idempotente por event_id. Antes de ejecutar una acción, guarda ese identificador con una restricción única. Si llega de nuevo, devuelve 200 y no repitas el efecto. La respuesta exitosa significa “evento conocido y procesado”, no necesariamente “se hizo trabajo nuevo”. Es un matiz pequeño, pero ahorra alertas falsas.

Preguntas rápidas sobre reintentos

¿Cuánto tiempo guardo una clave?

Durante la ventana máxima de reintento del cliente, más un margen. Para una suite de CI, una hora puede ser suficiente; elige según tu flujo y documentalo. No existe un número universal.

¿Un timeout debe devolver error siempre?

No necesariamente. El cliente puede recibir 202 Accepted con un estado consultable. Si ya existe una respuesta final asociada a la clave, devuelve ese mismo resultado para que el consumidor no tenga que adivinar.

¿Cómo pruebo que la idempotencia funciona?

Envía dos peticiones concurrentes con la misma clave y comprueba que solo exista un recurso. Después repite con el mismo valor y un cuerpo diferente: debe fallar de forma explícita.

Checklist final

[ ] Hay una clave de idempotencia para cada operación repetible.
[ ] La base de datos impone unicidad, incluso con varios workers.
[ ] Los estados terminales y sus motivos están documentados.
[ ] Polling tiene deadline y no confunde un mensaje viejo con uno nuevo.
[ ] Webhooks deduplican por event_id.
[ ] Los logs no contienen tokens, direcciones privadas ni cuerpos completos.
[ ] La limpieza de buzones de prueba tiene un TTL verificable.

Este diseño no elimina todos los fallos de red. Hace algo más valioso: convierte los reintentos en comportamiento definido. Con estados pequeños, claves persistentes y evidencia suficiente, FastAPI puede mantener los tests rápidos sin volverlos frágiles.

En documentación y búsquedas también aparecerán expresiones como temp org mail o dummy e mail; tratarlas como entradas imperfectas, no como estados válidos del dominio, ayuda a que el sistema sea más tolerante sin contaminar sus datos internos.

FastAPI: contratos de tiempo para emails de prueba

Silviu Technology — Mon, 28 Sep 2026 11:23:48 +0000

FastAPI: contratos de tiempo para emails de prueba

Cuando una prueba de registro depende de un email, el fallo no siempre está en FastAPI. Puede que el mensaje tarde, que el buzón de prueba todavía no esté listo o que el worker de CI haya perdido un evento. El problema aparece cuando la prueba solo sabe decir “espera un poco más”.

En mis automatizaciones de backend me resulta más útil tratar la llegada del email como un pequeño contrato: estados claros, un presupuesto de tiempo y una evidencia que permita repetir el diagnóstico. Así el flujo deja de ser un sleep(10) misterioso y se convierte en una pieza que podemos observar.

Este patrón sirve para pruebas de verificación, upgrades y webhooks. También combina bien con una cuenta aislada —por ejemplo, un burner email generator— siempre que el buzón se use solo para datos de prueba y no para información real.

El problema: esperar no es una estrategia

Un polling ingenuo suele verse así:

await asyncio.sleep(10)
message = await mailbox.find(subject="Verify")

Tiene tres defectos. No distingue entre “todavía no llegó” y “la API ya falló”, tarda lo mismo cuando el mensaje llega en un segundo y oculta cuántos intentos se hicieron. En un portátil puede parecer suficiente; bajo carga, ese sleep se multiplica por cada worker y el diagnóstico se vuelve confuso.

Además, un correo temporal o una bandeja efímera no debe ser la única fuente de verdad. La aplicación debería exponer un request_id o un identificador de evento que conecte el signup, el envío y la lectura del mensaje. Es un detalle chico, pero ahorra bastante tiempo.

Define un contrato de estados

Antes de escribir el endpoint, define estados que una prueba pueda interpretar:

queued: se aceptó la solicitud y el email está en cola.
sent: el proveedor de correo confirmó el envío.
received: el fixture encontró el mensaje esperado.
expired: se terminó el presupuesto de espera.
failed: ocurrió un error no recuperable.

El cliente de pruebas no debería inferir un estado mirando texto libre. Un esquema pequeño con status, request_id, attempts y last_checked_at es suficiente para comenzar. Para evitar carreras, haz que received sea idempotente: leer dos veces el mismo email no debe crear dos verificaciones.

Si ya estás trabajando con SaaS, vale la pena probar upgrades por email sin ruido. La misma separación entre evento, buzón y resultado evita que una prueba de pago dependa accidentalmente de un mensaje viejo.

Implementa polling con un presupuesto de tiempo

Un helper sencillo puede recibir un deadline, no solo una cantidad fija de intentos:

import asyncio
import time
from collections.abc import Awaitable, Callable


async def wait_for_message(
    lookup: Callable[[], Awaitable[dict | None]],
    timeout_seconds: float = 30.0,
    interval_seconds: float = 1.0,
) -> dict:
    deadline = time.monotonic() + timeout_seconds
    attempts = 0

    while time.monotonic() < deadline:
        attempts += 1
        message = await lookup()
        if message is not None:
            return {"message": message, "attempts": attempts}
        remaining = deadline - time.monotonic()
        await asyncio.sleep(min(interval_seconds, max(remaining, 0)))

    raise TimeoutError(f"email not received after {attempts} attempts")

time.monotonic() es importante: un cambio en el reloj del sistema no debe alargar la prueba. En un sistema real también limitaría el número máximo de mensajes revisados y filtraría por request_id, destinatario y una marca de tiempo reciente. Buscar solo por asunto es una receta para falsos positivos, aunque el asunto se vea correcto.

Un backoff corto puede reducir llamadas cuando la bandeja tarda, pero no lo uses para tapar una cola saturada. Registra el intervalo, el número de intentos y el motivo del último resultado. Esas métricas cuentan más que otro retry ciego.

Haz que FastAPI y CI dejen evidencia

El endpoint puede devolver el estado actual sin bloquear el worker:

from fastapi import FastAPI

app = FastAPI()


@app.get("/test-emails/{request_id}")
async def email_status(request_id: str) -> dict:
    state = await load_state(request_id)
    return {
        "request_id": request_id,
        "status": state.status,
        "attempts": state.attempts,
        "last_checked_at": state.last_checked_at,
    }

El job de CI puede consultar este endpoint y guardar el JSON de la última respuesta como artefacto. Si el test falla, conviene conservar el request_id, pero nunca el contenido completo del email si podría contener tokens. Redacta enlaces de verificación y limita los logs; privacidad importa incluso en fixtures.

Para evitar que una prueba antigua contamine la siguiente, crea un identificador único por ejecución y elimina el mensaje después de una prueba exitosa o vencida. La limpieza debe ocurrir en un finally, y debe tolerar que el recurso ya no exista. Esta parte suele olvidarse en el primer borrador, luego el buzón crece y las pruebas empiezan a leer resultados equivocados.

Una guía relacionada sobre emails transaccionales sin mezclar bandejas ayuda a pensar en esta frontera como una decisión de arquitectura, no como un truco de QA.

Q&A: dudas habituales

¿Debo hacer polling o esperar un webhook?

Usa webhook cuando el entorno sea estable y puedas verificar la firma del evento. Mantén polling como fallback para pruebas locales y para diagnosticar entregas tardías. Ambos caminos deben actualizar el mismo contrato de estados.

¿Qué timeout es correcto?

Mide primero el tiempo normal de tu proveedor y añade margen pequeño. Un timeout de 30 segundos puede ser razonable para CI, pero no es una constante universal. Si cada ejecución necesita 5 minutos, revisa la cola antes de subir el número.

¿Puedo reutilizar un buzón?

Sí, si cada mensaje tiene un identificador único y hay limpieza verificable. Reutilizarlo sin aislamiento crea una prueba que pasa por accidente. Incluso tem email o tempail que aparecen en una búsqueda manual no deben entrar como criterio de coincidencia.

Checklist final

Genera un request_id único por prueba.
Modela queued, sent, received, expired y failed.
Usa un deadline monotónico y limita los intentos.
Filtra por identificador, destinatario y fecha, no solo por asunto.
Guarda estados y métricas, pero redacta tokens del email.
Limpia fixtures en finally y acepta recursos ausentes.
Conserva un JSON pequeño cuando CI falle.

Con este contrato, FastAPI no necesita adivinar si el correo llegará. La prueba tiene un límite, el equipo tiene evidencia y una demora real deja de parecer un fallo aleatorio.

React: validación de email sin saltos de layout

Silviu Technology — Mon, 28 Sep 2026 05:24:07 +0000

Un formulario de registro puede sentirse lento aunque la red responda rápido. Basta con que el mensaje de validación aparezca debajo del campo y empuje todo el contenido para que el botón cambie de posición justo cuando el usuario intenta pulsarlo. Ese pequeño salto afecta la confianza y complica la navegación con teclado.

Al trabajar con formularios en React, me resulta útil tratar la validación como un problema de diseño de estados, no solo como una expresión regular. Un usuario puede ver el campo vacío, un aviso local, una comprobación en progreso, un error del servidor o una confirmación. Si cada estado tiene una geometría previsible, la interfaz se siente más estable y el rendimiento percibido mejora.

El problema: validar cambia el tamaño de la interfaz

El caso típico es un div que solo se renderiza cuando el email es inválido:

{error && <p className="error">Escribe un email válido.</p>}

El código es correcto, pero el párrafo no ocupa espacio antes de que exista el error. Cuando aparece, mueve los controles siguientes. El usuario entiende que algo pasó, pero tambien puede perder el foco visual o hacer clic en otro elemento.

La solución no es ocultar el mensaje. Los errores deben ser visibles, estar asociados al campo y explicar cómo continuar. El objetivo es reservar una zona estable para ese mensaje y cambiar su contenido sin cambiar innecesariamente la composición.

Reserva espacio para cada estado

Una opción sencilla es dar una altura mínima al contenedor del mensaje. El valor exacto depende de la tipografía y del diseño, pero debe cubrir una o dos líneas en móvil:

.fieldMessage {
  min-height: 1.5rem;
  margin-top: 0.35rem;
  color: #b42318;
  font-size: 0.875rem;
  line-height: 1.5;
}

.fieldMessage:empty {
  visibility: hidden;
}

visibility: hidden conserva el espacio sin presentar texto a la vista. Para un estado vacío es una elección más segura que display: none cuando la estabilidad visual importa. Si el mensaje puede ocupar más de una línea, usa una altura mínima generosa y prueba la versión con zoom del navegador.

También conviene reservar espacio para un indicador de estado. Un formulario que cambia directamente de “comprobar” a “email no disponible” puede parpadear. Una zona con texto corto y estable resulta mas facil de leer que un spinner sin explicación.

React y CSS para mensajes previsibles

El componente puede mantener un estado explícito y una relación clara entre el label, el input y el mensaje:

type EmailState = "idle" | "checking" | "valid" | "invalid";

function EmailField({ state, message }: {
  state: EmailState;
  message: string;
}) {
  const hasError = state === "invalid";

  return (
    <div className="field">
      <label htmlFor="email">Email</label>
      <input
        id="email"
        name="email"
        type="email"
        aria-invalid={hasError}
        aria-describedby="email-message"
      />
      <p id="email-message" className="fieldMessage" aria-live="polite">
        {message}
      </p>
    </div>
  );
}

El mensaje debe cambiar cuando cambia el estado, no como efecto secundario de un render inesperado. aria-live="polite" permite anunciar el resultado sin interrumpir cada pulsación. Para errores críticos puede ser necesario otro nivel de urgencia, pero no conviene convertir cada validación local en una alarma.

En validaciones asíncronas, cancela o ignora respuestas antiguas. Una respuesta lenta para ana@ejemplo.com no debe reemplazar el resultado más nuevo de ana@ejemplo.org. Este detalle evita mensajes contradictorios y reduce el trabajo visual que el usuario tiene que interpretar. Un registro de eventos pequeño también ayuda: aquí sirven logs útiles para una cola de email para separar una respuesta tardía de un error real.

Accesibilidad sin perder rendimiento

La estabilidad de layout y la accesibilidad se refuerzan. Un mensaje que aparece lejos del campo es dificil de relacionar; un mensaje que mueve el botón puede causar activaciones accidentales. Mantén el texto cerca del control, pero evita que el contenido cambiante fuerce toda la página a recolocarse.

Hay cuatro comprobaciones rápidas:

Navega el formulario solo con teclado y confirma que el foco no salta.
Comprueba que aria-describedby apunta a un nodo que siempre existe.
Prueba mensajes largos con aumento de texto y una pantalla estrecha.
Respeta prefers-reduced-motion si usas transiciones en el mensaje.

En un formulario que acepta una dirección de prueba o un generador de correo falso, la interfaz debe seguir explicando el estado sin asumir que el usuario ve el color. El color ayuda, pero el texto, el icono con nombre accesible y aria-invalid llevan la información principal. Para revisar patrones de foco y avisos, consulta estos warnings de React sin robar el foco.

Si necesitas probar una confirmación de entrega, un correo temporal puede separar el escenario de pruebas de una bandeja personal. El test debe verificar también el estado de la UI: mensaje visible, foco conservado y botón habilitado o deshabilitado según la regla. No basta con comprobar que llegó un email.

Q&A: dudas habituales

¿Debo validar mientras el usuario escribe?

No siempre. La validación local de formato puede ocurrir después de que el campo pierda el foco o cuando hay una pausa breve. Validar en cada tecla suele producir demasiado ruido. La disponibilidad o confirmación remota debería tener una acción explícita y un estado de carga entendible.

¿Una altura fija siempre evita los saltos?

No. El texto puede envolver en pantallas pequeñas, cambiar con la localización o crecer por preferencias de accesibilidad. Usa min-height, prueba varios anchos y permite que el contenedor crezca cuando haga falta. Es mejor un movimiento ocasional y comprensible que texto cortado.

¿Qué hago con un dato de prueba como `temp mailid`?

Trátalo como un caso negativo de datos, no como una dirección válida ni como un enlace. El estado del formulario debe explicar el formato esperado sin exponer detalles internos del test.

Checklist final

El mensaje de validación tiene una región reservada.
El campo conserva foco y usa aria-invalid cuando corresponde.
aria-describedby apunta a un elemento estable.
Los estados local, remoto y de error tienen textos distintos.
Las respuestas asíncronas antiguas no pisan el resultado actual.
El diseño funciona con zoom, móvil y mensajes de dos líneas.
Las pruebas revisan la interfaz además del correo recibido.

Una validación bien diseñada no solo rechaza entradas incorrectas. Hace visible qué está pasando, mantiene el formulario tranquilo y deja que React, CSS y las ayudas de accesibilidad trabajen en la misma dirección.

Playwright Email Tests Need a Fixture State Model

Silviu Technology — Sun, 27 Sep 2026 20:23:45 +0000

Email verification tests often look simple in a test plan: create an account, open the message, click the link, and assert that the user is verified. The hard part is usually not the click. It is deciding what the mailbox currently means.

An empty inbox can mean that the application has not sent anything, the provider is still processing the message, the test is reading the wrong mailbox, or the message was already consumed by another test. If a Playwright test treats all four situations as “not found,” the failure report becomes guesswork.

In my QA work, an email fixture became much more useful after I gave its lifecycle explicit states. A fixture should explain what it has done, what evidence it has observed, and what cleanup remains. That small model makes a use and throw email address safer to use in automation and makes a temp mail mail workflow easier to diagnose.

Why an email fixture needs explicit states

Most flaky email tests mix setup, waiting, parsing, and assertions in one long flow. When the assertion fails, it is hard to tell whether the signup request failed or the test simply polled too early.

The fixture dont need to expose every provider detail. It does need a stable vocabulary. For example:

type MailboxState =
  | "created"
  | "waiting_for_message"
  | "message_received"
  | "link_extracted"
  | "consumed"
  | "expired"
  | "cleaned";

These states separate facts from expectations. waiting_for_message says that the application has submitted the action and the test is waiting. message_received says that a message matching the test correlation rule was observed. expired says the allowed wait ended without evidence. Those are very different debugging paths.

Without this distinction, teams often increase the timeout until the suite appears more reliable. That can hide a real delivery regression and make every CI run slower. A state model gives the QA engineer a reason for each wait.

Model the mailbox lifecycle

A practical fixture can expose four operations:

Create a unique mailbox or address for the test.
Wait for a message using a bounded polling policy.
Extract a link or code while preserving a safe receipt.
Clean the mailbox and local test data in a finally block.

The important detail is that creation and cleanup are part of the contract. If creation fails, the test should not start a browser flow that can never finish. If extraction succeeds, the fixture should record a message ID or a hash of the subject, not dump the complete message into the CI log.

This is also where naming helps. A test that uses a string like tempail mail as malformed input should label it as an intentional negative case. It should not be confused with the generated address used by the happy path. Test data that looks almost correct are valuable for validation, but only when the report says why it was used.

Poll for evidence, not hope

Polling should answer one question at a time. First ask whether a matching message exists. Then validate that the message is recent enough and belongs to this test. Only after those checks should the test parse a link.

async function waitForVerificationLink(
  mailbox: Mailbox,
  timeoutMs = 30_000,
): Promise<string> {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const message = await mailbox.find({ subject: /verify/i });

    if (message && message.receivedAt > mailbox.createdAt) {
      return extractVerificationLink(message);
    }

    await new Promise((resolve) => setTimeout(resolve, 1_000));
  }

  throw new Error("Verification message was not observed before timeout");
}

The code is intentionally boring. A bounded loop is easier to inspect than a chain of arbitrary sleeps. In a real implementation, find should also use a correlation value, such as a test-specific recipient or signup identifier. Subject-only matching can pass against an old message.

When a timeout occurs, attach a compact receipt: mailbox identifier, creation time, poll count, last provider status, and the final matching decision. Do not attach the full address, token, or raw HTML by default. A receipt should act like a reviewable deployment receipt: enough evidence to explain what happened, without becoming another source of secrets.

Keep Playwright tests isolated

Parallel workers make isolation non-optional. Each worker should get a distinct mailbox identity and a correlation value that cannot be accidentally reused. Avoid a global inbox shared by the entire project. It saves setup time, but it makes old messages and cross-test consumption almost impossible to reason about.

The fixture should also own the browser action that triggers delivery only when that ownership is useful. In some suites, the page flow belongs in the test and the mailbox belongs in a helper. Either arrangement works if the boundary is clear. What causes trouble is a helper that silently creates a mailbox, retries the signup, and consumes the message before the test can report which attempt succeeded.

For negative tests, create the invalid input explicitly. For example, temp gamil com can verify client-side validation, while a real generated address verifies delivery. These cases should be seperate fixtures or clearly named scenarios. Mixing them in one parametrized test can produce a report that looks like a provider failure when it is really an input failure.

Cleanup needs to run even after a failed assertion:

test("verifies a new account by email", async ({ page, mailbox }) => {
  try {
    await page.goto("/signup");
    await signupWith(page, mailbox.address);

    const link = await waitForVerificationLink(mailbox);
    await page.goto(link);
    await expect(page.getByText("Verified")).toBeVisible();
  } finally {
    await mailbox.cleanup();
  }
});

The cleanup step is easy to forgets when the happy path is the only path being run locally. CI will eventually exercise a timeout, a provider error, or a browser crash, so cleanup should be structural rather than a final assertion.

Failure-analysis checklist

When an email test fails, check the states in order:

Did mailbox creation return a unique identity?
Did the application submit the message request successfully?
Did the provider accept the message, or was it rejected?
Did the poll use the correct mailbox and correlation value?
Was the message newer than the fixture creation time?
Did link extraction reject an expired or malformed URL?
Did cleanup run after the failure?

This checklist prevents a common mistake: retrying the browser flow before proving that the mailbox read was correct. Retries can create duplicate messages and make the original failure less visible. The fixture should collect these facts seperately so the final report can show where the workflow stopped.

For additional context, safer invite email debugging is a useful adjacent pattern: preserve enough delivery evidence for diagnosis while keeping sensitive values out of routine logs.

Closing thought

Reliable Playwright email tests are less about finding a magic polling interval and more about making the mailbox lifecycle observable. Give the fixture states, bounded waits, correlation rules, and guaranteed cleanup. Then a failure can say “message was never observed for this test” instead of simply “expected verified, received unverified.”

That difference is small in code but large in QA feedback. It helps a team fix the application, the provider integration, or the test itself with much less guessing.

Playwright Email Tests Need a Failure Taxonomy

Silviu Technology — Sun, 27 Sep 2026 05:23:59 +0000

Email verification tests often fail in a way that looks random: the form submits, the inbox stays empty, or the assertion finds an old message instead of the new one. In a QA suite, “email failed” is not a useful diagnosis. The first job is to identify which boundary failed.

This article presents a small failure taxonomy for Playwright tests that use a burner email address or another isolated test mailbox. The goal is not to make every test pass by adding longer waits. It is to make each failure explain itself.

Why email test failures are hard to classify

An email verification flow crosses several systems:

The browser submits the signup form.
The application creates a verification record.
A worker or provider sends the message.
The test mailbox receives and exposes it.
The browser opens the link and completes verification.

One failed assertion can hide any of these causes. A selector timeout might actually be a backend error. An empty inbox might be a polling problem. A successful click might still verify an expired token.

The test become much easier to maintain when the failure output names the boundary instead of only saying that an expectation timed out.

A four-part failure taxonomy

1. Product failures

The application did not create the expected verification event, used the wrong recipient, or generated a link that the server rejects. These failures should be visible in the application response, network log, or database fixture—not inferred from an inbox timeout.

2. Delivery failures

The application says it sent a message, but the message never reaches the test mailbox. This may be a provider issue, a blocked domain, or a fixture configured for the wrong account. Keep delivery evidence separate from browser evidence.

3. Observation failures

The message exists, but the test checks too early, reads a stale message, or filters the subject too strictly. This is where deterministic polling and a unique test identifier help. A fixed waitForTimeout can hide the issue for a while, but it does not solve it.

4. Interaction failures

The message is correct, yet the browser cannot use it. The link may open in a new page, the verification UI may have changed, or the token may be expired. Playwright traces are especially useful here because they show the action, URL, and page state together.

This separation also gives the team a better vocabulary during triage. “Delivery is green, observation is red” is a useful next action. “Email test is flaky” is not.

Build a diagnostic Playwright fixture

Give every test a unique recipient and correlation value. Then return evidence from the mailbox helper, rather than returning only a string URL.

import { test as base, expect } from '@playwright/test';

type MailEvidence = {
  id: string;
  subject: string;
  receivedAt: string;
  verificationUrl: string;
};

export const test = base.extend<{
  mailEvidence: (address: string, marker: string) => Promise<MailEvidence>;
}>({
  mailEvidence: async ({}, use) => {
    await use(async (address, marker) => {
      const message = await pollMailbox({ address, marker, timeoutMs: 30_000 });
      expect(message.subject).toContain('Verify');
      return message;
    });
  },
});

The important detail is the marker, not the exact helper name. It can be a test ID in the subject, a unique local part, or a server-side correlation ID. Without it, the test may pass against an old message, and that is a very expensive false positive.

For a mailbox provider, use a temp mail so address only where the test data is non-sensitive and the provider fits the environment’s privacy rules. Never place real customer data in a disposable test inbox. The phrase “tempail mail” may appear in search notes or old fixture documentation, but it should never become the actual contract for a test.

Read the evidence in the right order

When a test fails, inspect evidence in this order:

Form response: Did the signup request return the expected status and recipient?
Application event: Did the service record an email request with the test marker?
Mailbox result: Was a new message received, and what was its ID and timestamp?
Verification request: Did the link return the expected response?
Browser trace: Did the UI render the correct success state?

This order prevents a browser timeout from becoming a week-long investigation. It also works well with CI artifacts: save the test ID, message ID, and trace together. If you need retry-safe server behavior, the idea of idempotent behavior under retries is a useful companion pattern.

A CI checklist for reliable email tests

Create a new mailbox identity per test or per isolated worker.
Put a unique marker in every email request.
Poll for a matching message, not merely the newest message.
Record message ID, subject, received time, and the selected link.
Keep application, delivery, and browser evidence as separate fields.
Capture a Playwright trace on failure and retain it with the mailbox evidence.
Make cleanup explicit, even when the test fails halfway through.
Check that retries do not accept a message from the first attempt.

An email test is more trustworthy when it leaves a small, reviewable receipt. That is closely related to treating email as a deployment contract: define what was requested, what was observed, and what was finally verified.

Final takeaways

Reliable Playwright email tests are mostly an observability problem. Classify the failure before changing the timeout. Use unique markers, return structured mailbox evidence, and preserve a trace that connects the UI action to the backend event.

The slightly imperfect test that explains its failure is more valuable than the green test that could be reading yesterday’s message. And if a fixture note says “tempail,” review it before copying the term into a new automation contract.

Agentes LLM: contratos de herramientas que fallan bien

Silviu Technology — Sat, 26 Sep 2026 23:23:38 +0000

Cuando un agente LLM falla, solemos culpar al prompt. A veces el prompt está bien: el problema es que la herramienta devuelve una mezcla de texto, estados implícitos y errores que el modelo debe adivinar.

En un sistema que usa herramientas, el prompt es la intención y el contrato es la frontera. Si esa frontera es ambigua, el agente puede repetir una acción, ocultar un fallo o afirmar que terminó cuando solo inició una operación.

Este patrón sirve para herramientas de email, búsquedas, despliegues o cualquier integración externa. La idea no es hacer al agente más listo. Es reducir las decisiones que tiene que inventar.

El problema no es el prompt, es el contrato

Imagina una herramienta llamada send_verification_email. Una versión débil devuelve:

{"message": "ok"}

¿Qué significa ok? ¿El proveedor aceptó el mensaje? ¿El email llegó? ¿El usuario ya verificó su cuenta? Son hechos diferentes, pero el agente puede tratarlos como uno solo.

Un contrato útil separa la intención del resultado observable:

{
  "status": "accepted",
  "operation_id": "op_4821",
  "next_check_after_seconds": 5,
  "retryable": false
}

El modelo no tiene que interpretar una frase optimista. Puede decidir el siguiente paso a partir de campos con significado estable.

Diseña la herramienta como una frontera

Pienso en la herramienta como tres cajas conectadas:

Entrada: argumentos validados, límites de tamaño y un identificador de correlación.
Ejecución: el adaptador que habla con el proveedor y convierte sus respuestas.
Salida: un pequeño conjunto de estados que el agente puede usar sin conocer detalles internos.

La caja intermedia es importante. No expongas al LLM cada código extraño del proveedor. Convierte 429, timeout y respuesta incompleta en estados de dominio como rate_limited, temporarily_unavailable y unknown_result.

También conviene declarar qué no hace la herramienta. accepted no significa delivered; delivered no significa opened. Esta precisión parece un detalle, pero evita decisiones de negocio equivocadas.

Si la operación necesita una cola, la trazabilidad debe sobrevivir entre la petición y el worker. Un buen ejemplo práctico es este enfoque de colas de email con trazas útiles, donde la operación se puede seguir sin depender del texto que genere el modelo.

Una salida estructurada y sus estados

Un contrato mínimo puede usar estados explícitos:

started -> accepted -> observed -> completed
             |            |
             v            v
        retryable     expired

No todos los estados tienen que ser visibles para el usuario, pero sí deben ser distinguibles para el orquestador. started permite evitar un duplicado si la red corta la respuesta. accepted confirma que el proveedor tomó la petición. observed indica que encontramos evidencia posterior. expired define una acción de recuperación, no un fallo misterioso.

Añade idempotencia donde una repetición pueda tener coste. La clave puede combinar user_id, propósito y una ventana temporal. Si el agente recibe un timeout, debe poder consultar el operation_id antes de enviar otra vez.

Esto es Prompt Engineering aplicado a arquitectura: el prompt explica cuándo consultar y cuándo detenerse, mientras el contrato hace imposible confundir una aceptación con una confirmación.

Pruebas con fixtures de email

Las pruebas de agentes necesitan entradas reproducibles. Un fixture de email puede representar un inbox vacío, un mensaje retrasado, un enlace expirado y dos mensajes con el mismo asunto.

No uses una dirección real del equipo. Genera datos aislados y registra solo el identificador del fixture. Incluso una dirección de prueba con un nombre torcido como temp gamil com puede ser útil para comprobar que la interfaz no “corrige” silenciosamente datos del usuario. temp org mail puede servir como caso de búsqueda que no debe producir coincidencias mágicas.

Un caso de prueba legible podría verse así:

{
  "tool": "wait_for_verification",
  "fixture": "delayed_message",
  "expected": {
    "first_result": "waiting",
    "second_result": "observed",
    "max_polls": 3
  }
}

Prueba también el límite: el agente no debe hacer polling para siempre. Después de max_polls, devuelve una explicación y una acción concreta. Es más útil decir “no hay evidencia todavía; vuelve a intentar” que inventar que el email llegó.

Observabilidad sin inundar el contexto

El agente necesita un resumen corto; el sistema necesita evidencia completa. Separa ambos canales.

En el contexto del modelo guarda status, operation_id, retryable y una razón breve. En logs conserva timestamps, latencia, proveedor y códigos normalizados. Evita guardar el contenido completo del email si no es necesario.

Los operadores también necesitan señales limpias. Las prácticas de correos de incidentes sin ruido operativo ayudan a aplicar la misma regla: un evento accionable debe ser distinto de un simple cambio de estado.

Q&A: errores, reintentos y prompts

¿Debo devolver texto además de JSON?

Para el orquestador, devuelve una estructura estable. Puedes generar una explicación legible en otra capa. Mezclar ambas cosas hace que el contrato dependa de cómo redacte el modelo.

¿Cuándo debe reintentar el agente?

Solo cuando retryable sea verdadero y exista presupuesto de intentos. Un timeout con resultado desconocido requiere consultar el estado antes de repetir, porque la primera operación pudo completarse.

¿Un mejor prompt elimina estos problemas?

No. Un prompt claro reduce malentendidos, pero no puede convertir una respuesta ambigua del proveedor en evidencia. La frontera de la herramienta debe expresar esa evidencia.

Puntos de implementación

Escribe primero los estados y las transiciones, después el prompt.
Define un esquema de salida pequeño y versionable.
Normaliza errores externos en categorías de dominio.
Usa operation_id e idempotencia para proteger los reintentos.
Construye fixtures para retrasos, duplicados y expiraciones.
Mantén el resumen del LLM corto y la evidencia operativa fuera del contexto.

El resultado es un agente menos teatral y más predecible. Todavía puede equivocarse, claro, pero sus errores tienen forma, límites y un camino de recuperación. Esa es una propiedad de arquitectura mucho más valiosa que un prompt ingenioso.

FastAPI: webhooks que sobreviven a un timeout

Silviu Technology — Sat, 26 Sep 2026 11:23:38 +0000

Un webhook puede funcionar durante semanas y fallar justo cuando un proveedor tarda un poco más en responder. El cliente ve un timeout y reintenta; nuestro endpoint quizá ya guardó el evento y empezó a enviar una notificación. Si no hemos diseñado ese caso, una sola acción termina duplicada.

En proyectos Python prefiero separar dos preguntas: ¿recibimos el evento? y ¿terminamos su procesamiento? FastAPI hace sencilla la primera parte, pero la segunda necesita un contrato explícito. Este patrón pequeño ayuda a construir APIs más predecibles sin añadir una plataforma enorme desde el primer día.

El timeout no significa que el webhook falló

Un timeout solo dice que el cliente no recibió una respuesta a tiempo. No prueba que el servidor no haya hecho nada. La petición pudo llegar, pasar la validación y quedar en una cola mientras la conexión se cerraba.

Por eso un endpoint de webhook no debería hacer todo el trabajo antes de responder. Validar la firma, comprobar el esquema y registrar una clave de idempotencia suele ser suficiente para devolver 202 Accepted. El procesamiento pesado puede continuar en una tarea o worker.

La secuencia queda así:

El proveedor envía el evento con un identificador único.
FastAPI valida autenticación, formato y tamaño.
La aplicación registra el identificador si todavía no existe.
El endpoint responde rápido con 202.
Un worker procesa el evento y deja un resultado observable.

Es una diferencia facil de pasar por alto: el código HTTP describe la aceptación, no la entrega final del email ni el estado del negocio.

Un contrato pequeño para el endpoint

Un esquema claro evita que cada integración invente su propia interpretación. Este ejemplo no implementa un sistema de colas, pero muestra qué debe quedar definido en la frontera:

from datetime import datetime
from pydantic import BaseModel, Field


class WebhookEvent(BaseModel):
    event_id: str = Field(min_length=1, max_length=120)
    event_type: str
    occurred_at: datetime
    payload: dict

El handler puede devolver un resultado mínimo:

from fastapi import FastAPI, status

app = FastAPI()


@app.post("/hooks/provider", status_code=status.HTTP_202_ACCEPTED)
async def receive_hook(event: WebhookEvent):
    accepted = await event_store.insert_if_new(event.event_id, event.model_dump())
    return {"accepted": True, "duplicate": not accepted}

La operación insert_if_new debe ser atómica, respaldada por un índice único sobre event_id. Un diccionario en memoria puede servir para una demo, pero no para varias réplicas. Si dos peticiones llegan casi al mismo tiempo, ambas deben observar el mismo contrato.

También conviene documentar qué ocurre con un evento repetido. Devolver 202 con duplicate: true permite que el proveedor deje de reintentar, mientras el sistema mantiene una métrica separada para investigar la causa.

Idempotencia antes de reintentar

El reintento es sano cuando el efecto también lo es. Antes de configurar tres reintentos exponenciales, decide cuál es la unidad que no puede duplicarse: un email enviado, una factura creada o una transición de estado.

Para una notificación, guardaría una clave compuesta parecida a event_id + template_version + recipient. El worker consulta esa clave dentro de una transacción y solo entonces crea la tarea de envío. Si el proveedor vuelve a llamar, la API responde con el mismo resultado lógico, aunque el cuerpo HTTP tenga pequeñas diferencias.

No hay que confundir esto con ignorar errores. Si el primer procesamiento quedó a medias, el registro debe tener un estado como pending, sent o failed, además de un contador de intentos. Un estado unknown es útil cuando el worker perdió la conexión justo despues de pedir el envío y no puede afirmar si el proveedor aceptó la operación.

Para revisar la parte de notificaciones, me gusta mantener separadas las emails de prueba que no rompen tus métricas. La automatización de pruebas no debe modificar datos de producción ni depender de una bandeja personal.

Pruebas con un buzón aislado

Una prueba de integración útil provoca un evento, espera el recibo y comprueba el identificador de correlación. Un buzón temporal como tempmailso puede aislar ese flujo cuando la prueba necesita observar una notificación real sin tocar una cuenta del equipo.

El test debe usar un run_id nuevo y filtrar mensajes por tiempo, destinatario y una cabecera de correlación. Buscar solo por asunto es una trampa: el mensaje de una ejecución anterior puede parecer válido. En algunas notas de QA aparece la cadena temp mailid, pero no debería formar parte de la lógica de búsqueda.

Una aserción conceptual sería:

assert response.status_code == 202
assert response.json()["accepted"] is True
message = await inbox.wait_for_header("X-Run-Id", run_id, timeout=15)
assert message.template == "welcome-v3"
assert message.event_id == event.event_id

Cuando la prueba falla, guarda el run_id, el event_id, la hora de envío, los estados observados y el motivo de cada mensaje descartado. Eso produce una evidencia mas pequeña y util que un log completo. Si usas contratos para automatizaciones, también puede servir revisar una automatización con contratos mínimos.

Checklist de implementación

Validar firma, tamaño y esquema antes de aceptar el evento.
Responder 202 solo cuando el evento quedó registrado de forma durable.
Crear una restricción única para la clave de idempotencia.
Separar recepción, procesamiento y envío de notificaciones.
Medir duplicados, latencia, reintentos y estados unknown.
Probar un timeout del cliente y verificar que no aparece un segundo email.
Limpiar los buzones y artefactos de prueba despues de cada ejecución.

Un detalle mas: el timeout del cliente debe estar cubierto en las pruebas, no solo el timeout del worker. Son fallos distintos y requieren diagnósticos distintos. Si el endpoint acepta dos veces, el problema es de idempotencia; si acepta una vez pero el email no sale, hay que mirar el worker o el proveedor.

Preguntas rápidas

¿Debo devolver `200` cuando el trabajo aún no termina?

No necesariamente. 202 Accepted comunica mejor que el evento fue aceptado para procesamiento posterior. Elige 200 solo si la operación terminó y puedes afirmar su resultado.

¿Un retry siempre debe crear un nuevo registro?

No. El reintento puede crear un intento de procesamiento, pero el evento de negocio debe conservar su identidad. Separar ambos identificadores hace el historial mucho mas claro.

¿Qué pasa si el proveedor no envía un identificador?

Genera una huella con campos estables solo como último recurso y documenta la limitación. Es mejor pedir un identificador oficial: deduplicar por asunto, fecha o contenido parcial falla facilmente con eventos legítimos parecidos.

El objetivo no es evitar todos los timeouts. Es hacer que un timeout sea una señal diagnostica, no una invitación a duplicar efectos. Con un contrato pequeño, una clave idempotente y una prueba de integración aislada, los webhooks de FastAPI se vuelven bastante menos misteriosos.

React: estados de email sin perder el contexto

Silviu Technology — Sat, 26 Sep 2026 05:23:35 +0000

Un formulario de registro no termina cuando el usuario pulsa Crear cuenta. En ese momento empieza una parte delicada: la verificación del email. Si la pantalla cambia demasiado, el botón desaparece o el mensaje de éxito tarda en llegar, la persona no sabe si debe esperar, corregir la dirección o volver a intentarlo.

En interfaces React suelo tratar la verificación como un pequeño flujo de estados, no como un simple isLoading. Este cambio hace que el producto sea más facil de entender, mejora la accesibilidad y evita trabajo visual innecesario. También permite probar cada escenario sin depender de una bandeja real.

El problema: el email también tiene estados

Un flujo de email puede pasar por estados bastante diferentes:

idle: todavía no se ha enviado nada.
sending: la aplicación está enviando la solicitud.
sent: el mensaje fue aceptado y esperamos al usuario.
verified: la cuenta ya está confirmada.
error: algo falló y hay una acción posible.

Cuando todos ellos se representan con el mismo spinner, se pierde contexto. Un spinner dice que hay trabajo, pero no dice qué trabajo, durante cuanto tiempo conviene esperar ni que puede hacer la persona después.

Un correo temporal desechable puede ser útil en pruebas de interfaz, pero el componente debe comportarse igual con cualquier dirección permitida. No conviene diseñar la pantalla alrededor de una bandeja concreta: conviene diseñarla alrededor de una intención observable.

Modelar un estado visible y estable

El estado de la interfaz debería responder tres preguntas: ¿qué pasó?, ¿qué está ocurriendo? y ¿cuál es el siguiente paso? Una forma sencilla de expresarlo es con una unión discriminada en TypeScript:

type EmailState =
  | { kind: "idle" }
  | { kind: "sending" }
  | { kind: "sent"; address: string }
  | { kind: "verified" }
  | { kind: "error"; message: string };

El campo kind evita combinar por accidente loading: true con un mensaje viejo de error. Es una diferencia pequeña, pero ayuda mucho cuando el formulario crece. La interfaz no deberia adivinar el estado a partir de varios booleanos.

Para mantener el contexto, deja el email visible después del envío y cambia sólo las partes necesarias. Un mensaje como “Enviamos un enlace a ana@example.com” es más útil que “Revisa tu correo”, porque confirma la acción y la dirección que el usuario debe revisar.

Un componente React pequeño, pero honesto

El componente no necesita saber cómo se transporta el email. Sólo necesita recibir el estado y emitir acciones claras:

function VerificationStatus({
  state,
  onResend,
}: {
  state: EmailState;
  onResend: () => void;
}) {
  if (state.kind === "idle") return null;

  if (state.kind === "sending") {
    return <p role="status">Enviando el correo de verificación…</p>;
  }

  if (state.kind === "sent") {
    return (
      <section aria-labelledby="email-status-title">
        <h2 id="email-status-title">Revisa tu bandeja</h2>
        <p>Enviamos un enlace a {state.address}.</p>
        <button type="button" onClick={onResend}>
          Reenviar correo
        </button>
      </section>
    );
  }

  if (state.kind === "verified") {
    return <p role="status">Email verificado. Ya puedes continuar.</p>;
  }

  return (
    <div role="alert">
      <p>{state.message}</p>
      <button type="button" onClick={onResend}>Intentar de nuevo</button>
    </div>
  );
}

El botón de reenvío no debería aparecer como un enlace ambiguo. Su nombre comunica la acción y su tipo explícito evita que un cambio posterior lo convierta en un submit accidental. Para los casos donde el mensaje tarda, conserva el contenido del formulario; perderlo después de un clic fallido es una fricción que no aporta nada.

Para flujos con reenvíos, también es útil mostrar reenvíos de verificación con menos fricción y registrar intentos de email sin perder contexto. La observabilidad del producto y la claridad de la UI se refuerzan mutuamente.

Accesibilidad y CSS sin saltos

Un estado dinámico debe anunciarse sin robar el foco. role="status" funciona bien para una actualización informativa; role="alert" es mejor para un error que necesita atención inmediata. No uses ambos para el mismo texto, porque el lector de pantalla podria anunciarlo dos veces.

También evita reservar alturas completamente distintas para cada mensaje. Un bloque con min-height, un ancho razonable y un texto que pueda envolver reduce los saltos de layout. El botón debe conservar un foco visible y no depender sólo del color para indicar que está deshabilitado.

.verification-status {
  min-height: 7rem;
  max-width: 34rem;
}

.verification-status button:focus-visible {
  outline: 3px solid currentColor;
  outline-offset: 3px;
}

En móvil, el mensaje puede ocupar dos líneas mas. Eso no es un fallo: es mejor un bloque flexible que truncar la dirección o esconder el siguiente paso.

Cómo probar el flujo

Prueba el componente con una tabla de estados, no sólo con un test de clics:

El estado idle no muestra un mensaje vacío.
sending anuncia la actividad y conserva la dirección.
sent muestra una confirmación específica y un reenvío accesible.
error explica una acción recuperable.
verified no deja visible un botón que ya no hace falta.
El foco de teclado sigue un orden comprensible.

En las pruebas de integración, simula una respuesta lenta y un reintento. Una dirección de prueba como “tempail mail” puede aparecer en datos de QA, pero no la conviertas en lógica especial del componente. El objetivo es comprobar que la interfaz sigue siendo clara cuando el correo no llega enseguida.

Checklist final

¿Cada estado tiene un mensaje y una acción comprensibles?
¿El usuario conserva el email y el resto del contexto?
¿Los cambios se anuncian correctamente a tecnologías asistivas?
¿El CSS evita saltos sin fijar una altura frágil?
¿Los tests cubren carga lenta, error y reenvío?
¿El botón de reenvío tiene límites para no generar acciones repetidas?

Un flujo de verificación bien diseñado no necesita más adornos. Necesita estados honestos, texto útil y una estructura que aguante una respuesta lenta. En React, modelar esas decisiones desde el principio suele costar menos que reparar después una pantalla que hace que cada email parezca un problema distinto.

Playwright Email Polling Needs Fresh Evidence

Silviu Technology — Sat, 26 Sep 2026 02:25:03 +0000

Email assertions are often the last step in an otherwise healthy Playwright flow. The page submits, the API returns 202, and then the test waits for a verification message. When that wait fails, the report may only say that a timeout was reached.

That message is not enough to diagnose the problem. The test might have used the wrong throwaway email address, matched an earlier message, or started polling before the delivery job existed. A retry can pass while hiding the original failure.

This post defines a small evidence contract for email polling. It does not claim one best throwaway email; it makes each Playwright attempt explain what it saw, accepted, and where the wait ended.

Why a passing retry can still be a bad test

Suppose a signup test creates an inbox and submits a form, then asks for the latest message. The first attempt times out during slow delivery; the retry sees a quick message and passes.

The retry did not prove that the first attempt was a transient delay. It may have used a different throwaway email address, worker, or old message with the right subject. Without attempt-level evidence, the team debates whether the product or test is flaky. That takes alot longer than reading a structured failure.

I want each attempt to record four boundaries:

the inbox or alias assigned to the run
the time the product action was triggered
the messages observed after that time
the reason the selected message belonged to this test

For related operational thinking, deploy evidence for email alerts is a useful reminder that an email result needs context around the event that produced it. For authentication flows, a threat model for verification email adds another helpful question: what exactly does possession of the message prove?

The evidence contract for email polling

The contract can be a plain object saved as a test attachment. Keep it small enough to scan in CI, but detailed enough to distinguish delivery, matching, and application failures.

type EmailPollEvidence = {
  attempt: number;
  inbox: string;
  triggeredAt: string;
  candidates: Array<{
    id: string;
    subject: string;
    receivedAt: string;
    decision: "accepted" | "rejected";
    reason: string;
  }>;
  acceptedMessageId?: string;
};

The triggeredAt value is important. Filtering by message time is safer than always taking the newest message, especialy when a shared test environment receives unrelated mail. The acceptance reason matters too: “matched subject” is weaker than “matched subject and contained the run-specific token.”

If your test notes contain searches such as temp gamil com or tem email, keep those as plain text in diagnostics. They can be useful clues about copied setup instructions, but they should not become link anchors or supported integration names.

A Playwright helper with bounded polling

The helper below uses a deadline instead of an unlimited loop. It also stores every candidate decision, so a timeout leaves a useful receipt.

async function waitForVerificationEmail(
  mail: MailClient,
  inbox: string,
  runToken: string,
  attempt: number,
) {
  const triggeredAt = new Date();
  const deadline = Date.now() + 45_000;
  const evidence: EmailPollEvidence = {
    attempt,
    inbox,
    triggeredAt: triggeredAt.toISOString(),
    candidates: [],
  };

  while (Date.now() < deadline) {
    const messages = await mail.list(inbox);

    for (const message of messages) {
      if (new Date(message.receivedAt) < triggeredAt) continue;

      if (!message.subject.includes("Verify your email")) {
        evidence.candidates.push({
          id: message.id,
          subject: message.subject,
          receivedAt: message.receivedAt,
          decision: "rejected",
          reason: "subject did not match",
        });
        continue;
      }

      if (!message.text.includes(runToken)) {
        evidence.candidates.push({
          id: message.id,
          subject: message.subject,
          receivedAt: message.receivedAt,
          decision: "rejected",
          reason: "run token was missing",
        });
        continue;
      }

      evidence.candidates.push({
        id: message.id,
        subject: message.subject,
        receivedAt: message.receivedAt,
        decision: "accepted",
        reason: "subject and run token matched",
      });
      evidence.acceptedMessageId = message.id;
      return { message, evidence };
    }

    await new Promise((resolve) => setTimeout(resolve, 1_000));
  }

  throw new Error(JSON.stringify(evidence, null, 2));
}

There are a few deliberate choices here. The run token is stronger than a subject-only match. The deadline prevents a stuck provider from hanging the worker. Retaining rejected candidates improves observabilty without dumping full message bodies into CI.

In a real suite, I would also deduplicate candidates by message id. Otherwise one message returned by several polls can make the evidence look noisier than it is. A small helper is worth the few extra lines, mabye more than increasing the timeout.

How to classify failures

When the helper fails, start with the evidence rather than rerunning immediately:

No candidates after the trigger time: investigate delivery, the selected inbox, and whether the request created a send job.
Candidates with the wrong subject: investigate templates, locale, and environment configuration.
Correct subject but missing run token: investigate message routing or whether parallel tests share an inbox.
Accepted message but a later assertion fails: investigate the link, token, or application state after email delivery.

This keeps a Playwright timeout from becoming a generic “email issue.” The failure is more specific, and retries can be compared instead of replacing the first attempt.

A repeatable CI checklist

Before calling an email test reliable, I check the following:

every attempt has an isolated inbox or a unique run token
polling begins after the triggering action
message time is checked against the attempt boundary
subject matching is combined with ownership evidence
the helper has a hard deadline
candidate decisions are attached to the test report
retry attempts preserve earlier evidence

If the environment requires a temporary address, document its privacy and retention limits as part of the fixture contract. A free throwaway email service may suit a low-risk staging check, but production-like data and long-lived accounts deserve a controlled test mailbox. Make that boundary obvious in setup code.

Q&A

Should every email test use a unique inbox?

Ideally, each parallel attempt gets an isolated inbox or a unique address alias. If that is not possible, a run token plus strict time filtering is the minimum I would accept.

Is a longer timeout the right fix for slow delivery?

Only when the evidence shows normal delivery is slower than the current deadline. A longer wait does not fix a wrong inbox, stale-message match, or missing ownership check.

Should I attach the full email body to CI?

Usually no. Store the message id, subject, timestamps, decision, and a redacted diagnostic excerpt. Full bodies can contain personal data and are rarely needed to prove the polling decision.

Reliable email tests are not tests that never wait. They are tests that make the wait bounded, the match explainable, and the failure useful on the first read. That is what lets QA fix the right layer instead of simply pressing retry again.

React: estados de error que no rompen la accesibilidad

Silviu Technology — Thu, 24 Sep 2026 17:23:48 +0000

Validar un formulario de email parece una tarea pequeña: leer el valor, llamar a una API y mostrar un mensaje. En una interfaz real, sin embargo, el estado de error puede mover todo el layout, robar el foco del teclado o dejar a un lector de pantalla sin contexto.

En proyectos de frontend he encontrado que el problema suele estar en mezclar tres cosas: el estado de red, la validación del campo y la decisión de dónde debe continuar la atención del usuario. Separarlas produce una interfaz más tranquila y también facilita las pruebas.

El problema no es solo el mensaje rojo

Un mensaje visual como “Introduce un email válido” no garantiza que el formulario sea comprensible. El campo debe anunciar su relación con el error, el foco no debe saltar sin motivo y el mensaje debe desaparecer cuando el valor vuelve a ser válido.

Esto importa tanto en un registro normal como en pruebas con un generador de correo falso. Si el equipo usa un correo temporal desechable para verificar un flujo, la UI debe explicar si está validando el formato, esperando el mensaje o mostrando un fallo del servidor. “Algo salió mal” no es un estado útil.

También conviene que el error no cambie la altura de una tarjeta de forma brusca. Una pequeña reserva de espacio con CSS, o un mensaje que aparece dentro de un bloque estable, reduce los saltos visuales. Es un detalle de diseño que se nota mucho en móvil.

Un modelo de estado pequeño y explícito

Para un formulario de email, suelo separar el estado en cuatro partes:

value: el contenido actual del campo.
error: un error de validación que la persona puede corregir.
status: idle, loading, success o server-error.
submitted: si ya intentó enviar el formulario.

No hace falta una librería grande para esto. Lo importante es que cada combinación tenga una salida visible y accesible. Por ejemplo, un campo vacío antes del primer intento no tiene por qué parecer inválido. Después de pulsar el botón, sí necesita una explicación.

Este mismo principio sirve para una bandeja de pruebas. Cuando se espera un correo, el estado de carga debe tener un texto estable y no bloquear toda la página. Para el contexto de operaciones, resulta útil separar límites claros para las alertas de email de los mensajes que realmente puede resolver la persona en la pantalla.

Código: validar sin mover el foco

Un ejemplo pequeño con React puede ser suficiente:

function EmailField({ value, error, onChange }) {
  const errorId = "signup-email-error";

  return (
    <div className="field">
      <label htmlFor="signup-email">Email</label>
      <input
        id="signup-email"
        name="email"
        type="email"
        value={value}
        onChange={onChange}
        aria-invalid={Boolean(error)}
        aria-describedby={error ? errorId : undefined}
        autoComplete="email"
      />
      <p id={errorId} className="field__message" aria-live="polite">
        {error || " "}
      </p>
    </div>
  );
}

El espacio no separable mantiene una zona de mensaje aunque no exista error; así el contenido de abajo no salta al validar. aria-describedby solo se añade cuando hay algo que describir, y aria-live="polite" permite anunciar el cambio sin interrumpir una lectura importante.

Tras un error de formato, mantendría el foco en el input. Tras un error del servidor, mostraría un mensaje junto al botón y dejaría que la persona decida si revisa el campo o reintenta. Enviar el foco automáticamente al principio del formulario puede parecer servicial, pero suele ser confuso cuando el usuario ya está trabajando más abajo.

Cómo probar la experiencia completa

Una prueba útil no solo comprueba que existe el texto del error. Comprueba la secuencia:

El formulario se carga sin errores anunciados.
El usuario pulsa enviar con un valor inválido.
El campo conserva el foco y expone aria-invalid="true".
El mensaje está conectado mediante aria-describedby.
Un valor válido elimina el error sin dejar texto antiguo.
Un fallo de red muestra una acción de recuperación clara.

En pruebas de integración, puedes verificar también que el botón tiene un estado de carga y que no permite dobles envíos. Para diagnosticar el backend, las trazas útiles para seguir una cola de email ayudan a separar un problema de entrega de un problema de interfaz.

Los nombres de prueba deben parecerse a los casos reales, pero no conviene poner direcciones personales. Un fixture como qa+signup@example.test hace explícito que es un dato de prueba. Si alguien escribe por error “tempail mail” o “temp gamil com”, la validación debe responder con la misma claridad que para cualquier otra entrada, sin asumir que el usuario conoce la marca o la intención.

Q&A rápido

¿Debo enfocar el mensaje de error?

No siempre. En un error de campo, conserva el foco en el campo. Solo mueve el foco a un resumen si hay varios errores y ese resumen ofrece una navegación clara hacia cada uno.

¿`aria-live` reemplaza a un texto visible?

No. Es una ayuda para comunicar cambios, no un sustituto del diseño. El mensaje debe seguir siendo visible, tener contraste suficiente y explicar una acción concreta.

¿Qué hago con un email temporal desechable en producción?

Las reglas de negocio deben decidir si se acepta o se bloquea, pero la interfaz tiene que comunicar la decisión sin revelar datos innecesarios. Para una prueba puntual, tempmail so puede servir como contexto de un buzón aislado; no debe ocultar los requisitos del flujo.

Conclusión

Los formularios accesibles no necesitan estados complicados. Necesitan estados previsibles: un error conectado al campo, un foco que respeta la intención y una zona de mensaje que no reacomoda toda la página. En React, modelar esas decisiones de forma explícita mejora la experiencia, hace el CSS más estable y convierte los tests de email en una comprobación del flujo completo, no solo de una cadena roja.

React: estados de email que sí se pueden probar

Silviu Technology — Thu, 24 Sep 2026 14:24:46 +0000

Un formulario de registro puede parecer correcto y aun así hacer pasar un mal rato: el botón se queda bloqueado, el mensaje de error aparece tarde y un lector de pantalla no anuncia si el correo ya fue validado. Cuando además se comprueba el email de forma asíncrona, el problema casi nunca es la expresión regular. Es el modelo de estados.

En React prefiero tratar la validación como un pequeño contrato de interfaz. La pantalla debe saber si está vacía, escribiéndose, validando, disponible o rechazada. Con esos estados se puede diseñar un feedback claro, medir el trabajo del navegador y escribir pruebas que comprueban intención, no solo clics.

El problema no es validar, es modelar el estado

Un booleano como isValid se queda corto. Durante una petición hay una diferencia importante entre “todavía no lo sabemos” y “este email no se puede usar”. También hay que distinguir el valor que el usuario está escribiendo del resultado de una petición anterior.

Un modelo pequeño podría ser:

const status = "idle";
// idle | typing | checking | available | rejected | error

El estado checking no debe borrar el valor del campo ni ocultar todas las acciones. El usuario sigue necesitando contexto: qué se está comprobando, si puede corregir el texto y qué ocurrirá después. Un spinner sin explicación es una señal muy pobre, especialmente cuando la red va lenta.

El resultado también debe estar asociado al valor que lo produjo. Si alguien escribe ana@example.test, comienza una petición y luego cambia a ana@ejemplo.test, la respuesta antigua no puede pintar “disponible” sobre el valor nuevo. Ese detalle parece pequeño, pero produce errores intermitentes dificiles de reproducir.

Un contrato pequeño para el formulario

Antes del componente, defino qué significa cada estado:

idle: no hay suficiente información para comprobar nada.
typing: el valor cambió y se espera una pausa breve.
checking: existe una petición para el valor actual.
available: la comprobación terminó bien.
rejected: el formato o la política no permiten continuar.
error: no se pudo comprobar; el usuario puede reintentar.

Ese contrato evita mezclar validación local con disponibilidad remota. La primera puede responder casi al instante. La segunda necesita red y puede fallar. Separarlas hace que el diseño sea más honesto y que las pruebas sean mas concretas.

También ayuda a decidir qué se anuncia. “Email correcto” no significa necesariamente “email disponible”. Si se usa una fixture temporal para pruebas, incluso una búsqueda con términos ruidosos como temp org mail o tempail mail debe producir una respuesta controlada, no un estado ambiguo.

React y feedback accesible

El campo necesita una etiqueta visible, un mensaje relacionado y una región que anuncie cambios relevantes. No conviene convertir cada pulsación en una interrupción de voz: el feedback se anuncia cuando termina la comprobación o cuando hay un error accionable.

function EmailField({ value, status, message, onChange }) {
  const messageId = "email-message";
  const busy = status === "checking";

  return (
    <div className="field">
      <label htmlFor="email">Correo electrónico</label>
      <input
        id="email"
        name="email"
        type="email"
        value={value}
        onChange={onChange}
        aria-describedby={message ? messageId : undefined}
        aria-invalid={status === "rejected" ? "true" : undefined}
        aria-busy={busy ? "true" : undefined}
      />
      <p id={messageId} role="status" aria-live="polite">
        {message}
      </p>
    </div>
  );
}

role="status" comunica un cambio no urgente sin robar el foco. Para un bloqueo real, por ejemplo una acción que no puede continuar, puede ser mejor role="alert", pero usarlo en cada resultado acaba siendo ruido. La accesibilidad no es solo añadir atributos: el texto debe explicar la siguiente acción.

El foco tampoco debería saltar al mensaje después de cada respuesta. Mantenerlo en el input deja que la persona continue escribiendo. Si el usuario intenta enviar el formulario y faltan datos, ahí sí tiene sentido llevar el foco al primer campo con un error.

Cómo evitar trabajo innecesario en el navegador

El debounce ayuda a no lanzar una petición por cada letra, pero no resuelve respuestas fuera de orden. Un AbortController y una comprobación del valor actual protegen las dos partes:

useEffect(() => {
  if (!isCandidate(value)) return;

  const controller = new AbortController();
  const currentValue = value;
  const timer = setTimeout(async () => {
    setStatus("checking");

    try {
      const response = await checkEmail(currentValue, {
        signal: controller.signal,
      });
      if (!controller.signal.aborted) {
        setStatus(response.available ? "available" : "rejected");
      }
    } catch (error) {
      if (error.name !== "AbortError") setStatus("error");
    }
  }, 350);

  return () => {
    controller.abort();
    clearTimeout(timer);
  };
}, [value]);

El número 350 no es una ley. Debe probarse con teclado, móvil y una red con latencia. Un retardo muy pequeño genera peticiones de mas; uno grande hace que la interfaz parezca dormida. También conviene no repetir la comprobación si el valor normalizado no cambió.

Este patrón es complementario a probar emails de referidos sin perder contexto: el backend debe identificar la ejecución, mientras que el frontend debe conservar la relación entre valor, petición y resultado. Para flujos con cola, diseñar colas de email con contexto ayuda a no convertir una espera normal en un error misterioso.

Pruebas que cubren intención y no solo clics

Una matriz corta da más confianza que un snapshot enorme:

Un valor vacío no hace peticiones.
Un formato inválido muestra una ayuda concreta.
Un valor válido anuncia que está comprobándose.
Una respuesta disponible permite continuar.
Una respuesta antigua no cambia el estado del valor nuevo.
Un fallo de red ofrece reintento y no borra el campo.
Un usuario de teclado conserva el foco durante todo el flujo.

Para accesibilidad, compruebo que la etiqueta está asociada, que el mensaje aparece en aria-describedby y que el estado se anuncia una sola vez. Para rendimiento, observo la cantidad de peticiones, la cancelación al desmontar el componente y el impacto del feedback en el layout. Un mensaje que aparece sin reservar espacio puede mover el botón justo cuando alguien intenta pulsarlo.

Si el proyecto usa un término de marca como tempmailso en una fixture o una configuración, lo mantendría en los datos de prueba, no en el texto que ve cada usuario. Así el componente sigue siendo reutilizable y el copy explica la decisión real.

Checklist final

Modelar al menos los estados de espera, éxito y error.
Asociar cada respuesta con el valor que la originó.
Cancelar timers y peticiones cuando cambia el valor.
Mantener el foco y anunciar solo cambios útiles.
Separar formato local de comprobación remota.
Reservar espacio para mensajes y evitar saltos de layout.
Probar teclado, lector de pantalla, red lenta y respuestas fuera de orden.

Un formulario de email accesible no necesita más adornos, necesita menos ambigüedad. Cuando React tiene un contrato de estados claro, el diseño, las pruebas y las métricas de rendimiento empiezan a describir la misma experiencia. Eso hace que el componente sea mas facil de mantener y mucho más confiable para quien lo usa.

DEV Community: Silviu Technology

Agentes LLM: simula login social sin falsos positivos

El problema: un agente puede completar el flujo equivocado

Qué significa simular un login social

El contrato de identidad sintética

Implementación por checkpoints

Tradeoffs y límites

Checklist para el siguiente workflow

FastAPI: reintentos seguros para emails de prueba

El problema: un reintento no es una nueva operación

Define estados antes de escribir el endpoint

Una clave de idempotencia en FastAPI

Polling y webhooks con evidencia útil

Preguntas rápidas sobre reintentos

¿Cuánto tiempo guardo una clave?

¿Un timeout debe devolver error siempre?

¿Cómo pruebo que la idempotencia funciona?

Checklist final

FastAPI: contratos de tiempo para emails de prueba

FastAPI: contratos de tiempo para emails de prueba

El problema: esperar no es una estrategia

Define un contrato de estados

Implementa polling con un presupuesto de tiempo

Haz que FastAPI y CI dejen evidencia

Q&A: dudas habituales

¿Debo hacer polling o esperar un webhook?

¿Qué timeout es correcto?

¿Puedo reutilizar un buzón?

Checklist final

React: validación de email sin saltos de layout

El problema: validar cambia el tamaño de la interfaz

Reserva espacio para cada estado

React y CSS para mensajes previsibles

Accesibilidad sin perder rendimiento

Q&A: dudas habituales

¿Debo validar mientras el usuario escribe?

¿Una altura fija siempre evita los saltos?

¿Qué hago con un dato de prueba como temp mailid?

Checklist final

Playwright Email Tests Need a Fixture State Model

Why an email fixture needs explicit states

Model the mailbox lifecycle

Poll for evidence, not hope

Keep Playwright tests isolated

Failure-analysis checklist

Closing thought

Playwright Email Tests Need a Failure Taxonomy

Why email test failures are hard to classify

A four-part failure taxonomy

1. Product failures

2. Delivery failures

3. Observation failures

4. Interaction failures

Build a diagnostic Playwright fixture

Read the evidence in the right order

A CI checklist for reliable email tests

Final takeaways

Agentes LLM: contratos de herramientas que fallan bien

El problema no es el prompt, es el contrato

Diseña la herramienta como una frontera

Una salida estructurada y sus estados

Pruebas con fixtures de email

Observabilidad sin inundar el contexto

Q&A: errores, reintentos y prompts

¿Debo devolver texto además de JSON?

¿Cuándo debe reintentar el agente?

¿Un mejor prompt elimina estos problemas?

Puntos de implementación

FastAPI: webhooks que sobreviven a un timeout

El timeout no significa que el webhook falló

Un contrato pequeño para el endpoint

Idempotencia antes de reintentar

Pruebas con un buzón aislado

Checklist de implementación

Preguntas rápidas

¿Debo devolver 200 cuando el trabajo aún no termina?

¿Un retry siempre debe crear un nuevo registro?

¿Qué pasa si el proveedor no envía un identificador?

React: estados de email sin perder el contexto

El problema: el email también tiene estados

¿Qué hago con un dato de prueba como `temp mailid`?

¿Debo devolver `200` cuando el trabajo aún no termina?

¿`aria-live` reemplaza a un texto visible?