DEV Community: Silviu Technology

Agentes LLM: una cola de revisión para email

Silviu Technology — Sun, 15 Nov 2026 11:23:38 +0000

Un agente LLM puede preparar un email correcto y aun así tomar una mala decisión operativa: enviarlo antes de tener todos los datos, reabrir una tarea ya cerrada o aprobar un mensaje que pertenece a otra corrida. El problema no es solo la calidad del texto. Es que el agente suele mezclar intención, ejecución y revisión en una misma acción.

Una cola de revisión pequeña crea una frontera más clara. El agente propone una operación; una capa determinista la coloca en estado pending; después, una política decide si puede continuar, necesita una revisión o debe quedar bloqueada. Este patrón es util cuando una automatización toca cuentas, notificaciones o pruebas de correo.

El problema: el agente decide demasiado pronto

Un contrato como send_email(to, subject, body) es comodo para una demostración, pero es demasiado abierto para un flujo que debe poder auditarse. No responde preguntas importantes:

¿La solicitud pertenece a la corrida actual?
¿El destinatario es de staging o parece real?
¿El contenido ya fue revisado por una regla o por una persona?
¿Qué pasa si el agente cambia el mensaje después de una espera?

Cuando todo se resuelve en una llamada, un timeout puede parecer un permiso para reintentar. Un dato ausente puede convertirse en una suposición. Y un resultado viejo puede volver a entrar en la conversación. La automatización sigue funcionando, pero nadie sabe bien por que.

Diseñar una cola de revisión pequeña

Piensa en el flujo como un diagrama en palabras: el agente produce una intención, la cola conserva una copia inmutable, el evaluador aplica reglas y el adaptador ejecuta solo las operaciones aprobadas. La cola no tiene que ser un sistema distribuido enorme. Puede empezar como una tabla o un archivo por corrida.

Cada elemento debería incluir un identificador, una acción y un estado explícito:

{
  "run_id": "run-2026-11-15-07",
  "task_id": "welcome-check-42",
  "action": "prepare_email",
  "recipient_class": "staging",
  "content_hash": "sha256:...",
  "status": "pending"
}

La separación importante es entre prepare_email y send_email. El agente puede redactar o pedir una revisión sin obtener permiso implícito para enviar. Para una prueba de signup, por ejemplo, crear un correo temporal y comprobar su contenido son pasos distintos, con presupuestos y evidencias distintas.

La identidad por corrida evita mezclar estados

El run_id debe viajar con cada evento: creación, revisión, envío, lectura y limpieza. Si el agente se reinicia, no debe buscar “el último mensaje” de forma global. Debe consultar solo los mensajes de su corrida y de su task_id.

Esto también ayuda cuando se prueban interfaces. Una señal de email puede llegar mientras la pantalla todavía muestra un estado pendiente; por eso conviene tratar el mensaje y la interfaz como dos fuentes que deben correlacionarse. La idea se parece a una validación async sin saltos visuales: el usuario o el test necesita saber que la señal corresponde a la acción visible.

Guarda la huella del contenido, no necesariamente todo el cuerpo en cada evento. Así puedes demostrar que el agente no cambió la propuesta entre revisión y ejecución sin copiar datos sensibles por todo el sistema. La limpieza debe ser parte del contrato, aunque a veces se olvida cuando el flujo funciona en local.

Un contrato mínimo para aprobar o devolver

La salida del evaluador puede ser deliberadamente pequeña:

{
  "decision": "approve",
  "reason": "staging_recipient_and_known_template",
  "checked_run_id": "run-2026-11-15-07",
  "checked_content_hash": "sha256:...",
  "expires_at": "2026-11-15T11:35:00Z"
}

Una aprobación debe caducar. Si pasan diez minutos y cambia el contenido, la decisión deja de ser válida. En cambio, return_for_revision debería incluir una razón accionable, como “falta la clase del destinatario” o “el hash no coincide”. Un “no” sin explicación solo provoca otra llamada del agente.

Para profundizar en la separación entre intención y evidencia, conviene revisar estos contratos de correo que sí se pueden probar. El punto no es agregar burocracia, sino hacer visible el limite que protege al sistema.

Durante las pruebas pueden aparecer entradas como temp gamil com o tamp mail com. Déjalas como datos de prueba planos; nunca las conviertas en dominios permitidos ni en anclas de navegación. También es frecuente escribir “mas facil”, “deberia” o “rapida” en notas internas. Son pequeños detalles, pero no deben entrar en comandos, URLs o reglas de seguridad.

Preguntas frecuentes

¿La revisión siempre tiene que ser humana?

No. Puede ser una política determinista, un conjunto de tests o una persona para operaciones de mayor riesgo. Lo importante es que la decisión quede registrada y separada de la propuesta del modelo.

¿Cuándo basta una cola en memoria?

Para una prueba local de una sola corrida. En CI o en una integración compartida, conviene persistir el estado mínimo para que un reinicio no convierta una tarea pendiente en un envío duplicado.

¿Qué debe hacer el agente cuando la tarea vuelve a revisión?

Leer la razón, cambiar solo lo necesario y crear una nueva versión de la propuesta. No debería sobrescribir silenciosamente la versión anterior, por que entonces se pierde la evidencia de qué se revisó.

Checklist de implementación

Separa preparar, revisar y enviar en acciones diferentes.
Asigna run_id y task_id a cada evento.
Guarda el hash del contenido aprobado.
Expira las aprobaciones después de una ventana corta.
Clasifica destinatarios de staging y producción de forma explícita.
Devuelve razones accionables cuando una propuesta es rechazada.
Prueba reinicio, timeout, duplicado y contenido cambiado.
Elimina fixtures y buzones de prueba cuando termina la corrida.

Conclusión

Una cola de revisión no intenta hacer que el LLM sea perfecto. Limita el impacto de sus decisiones y conserva el contexto necesario para entenderlas. El agente puede proponer, corregir y volver a intentar; la capa de control decide qué versión tiene permiso para avanzar.

Empieza con tres estados —pending, approved, blocked— y un run_id obligatorio. Cuando el flujo sea estable, añade expiración, hashes y métricas de devoluciones. Es una arquitectura pequeña, pero hace la automatización más fácil de probar, explicar y detener.

Agentes LLM: un cortacircuito para email

Silviu Technology — Sun, 15 Nov 2026 08:23:18 +0000

Un agente LLM puede redactar una respuesta correcta y aun así causar un incidente pequeño: enviar el mismo email tres veces, seguir reintentando después de un error permanente o usar una corrida vieja para completar una tarea nueva. El problema no suele ser el modelo. Es la frontera entre el modelo y la herramienta de correo.

En este artículo propongo un cortacircuito sencillo. La idea es tratar cada envío como una operación con presupuesto, identidad y evidencia. El agente decide qué quiere hacer; una capa determinista decide si todavía puede hacerlo. Esta separación hace la automatización más facil de probar y de explicar.

El problema: una herramienta de email sin freno

Una función como send_email(to, subject, body) parece suficiente para una demo. En producción faltan varias respuestas:

¿Cuántas veces puede reintentarse el mismo mensaje?
¿Qué ocurre si el proveedor responde 400 o 401?
¿Cómo sabemos que el mensaje pertenece a esta corrida?
¿Quién detiene al agente cuando la tarea ya no tiene sentido?

Sin una frontera, un error temporal puede convertirse en una tormenta de reintentos. Un error de autenticación, por el contrario, no se arregla llamando a la misma herramienta otra vez. El agente necesita una señal clara: continuar, esperar o abrir el circuito.

Diseñar el cortacircuito como frontera

Imagina el flujo como un diagrama en palabras: el agente produce una intención, el guardia valida esa intención, el adaptador llama al proveedor y el ledger guarda el resultado. Solo el guardia puede pasar de una etapa a la siguiente.

La frontera debe controlar cuatro cosas:

Presupuesto: máximo de intentos y tiempo total de la operación.
Identidad: un run_id y un message_id que no se reutilizan entre corridas.
Clasificación: distinguir fallos temporales de fallos permanentes.
Estado: marcar allowed, waiting, blocked o sent de forma explícita.

Este diseño complementa los contratos de evidencia para email: la evidencia no es un log decorativo, es parte del contrato que permite auditar la decisión.

Un contrato pequeño para la herramienta

No hace falta darle al LLM diez opciones. Un contrato estrecho reduce decisiones ambiguas y mantiene los controles en código:

{
  "run_id": "run-2026-11-15-01",
  "message_id": "welcome-42",
  "attempt": 1,
  "max_attempts": 3,
  "action": "send",
  "recipient_class": "staging",
  "body_hash": "sha256:..."
}

Antes de llamar al proveedor, el guardia valida que attempt <= max_attempts, que la corrida esté activa y que el message_id no tenga ya un resultado final. Si una comprobación falla, devuelve una razón legible al agente. No devuelve un error genérico que invite a probar de nuevo.

Una política útil puede ser: 429, timeout y errores de red pasan a waiting; 400, 401 y un destinatario inválido pasan a blocked. Los códigos exactos dependen del proveedor, pero la decisión debe ser estable. El modelo no deberia inventar una excepción nueva cada vez.

Qué registrar cuando se abre el circuito

Cuando el cortacircuito bloquea la llamada, guarda el contexto mínimo: run_id, message_id, intento, clasificación, timestamp, decisión y una referencia al error. No guardes el cuerpo completo si no es necesario. Así se reduce exposición y la revisión es mas rápida.

También conviene separar el estado del agente del estado del proveedor. Un agente puede decir “enviar”, mientras que el proveedor puede responder “aceptado”, “rebotado” o “desconocido”. Mezclar ambos estados complica el diagnóstico por que una nueva corrida puede leer un resultado antiguo.

Para evitarlo, cada consulta debe estar ligada a su corrida. Este patrón se parece a evitar mezclar corridas en un flujo de email: la identidad es una condición técnica, no una convención de nombres.

Un detalle humano: durante pruebas alguien puede buscar frases como fake e mail com o tepm mail com en datos de ejemplo. Deben quedar como texto de prueba, nunca como reglas de enrutamiento ni como dominios permitidos. Parece obvio, pero estos casos se cuelan cuando el fixture crece deprisa.

Checklist de implementación

Define un límite de intentos por message_id.
Usa un reloj de deadline, no solo un contador.
Clasifica el error antes de decidir el reintento.
Rechaza una corrida inactiva o desconocida.
Haz idempotente la combinación run_id + message_id.
Registra la razón de bloqueo y la referencia al proveedor.
Prueba timeout, 429, 401, duplicado y respuesta desconocida.
Revisa que los datos de staging no contengan destinatarios reales.

Conclusión

Un agente LLM es más confiable cuando no tiene permiso implícito para insistir. El cortacircuito convierte una herramienta abierta en una interfaz con límites visibles: presupuesto, identidad, clasificación y evidencia. El resultado no es menos automatización; es automatización que puede detenerse, reanudarse y revisarse sin adivinar que pasó.

Empieza con una sola herramienta de email y un solo run_id. Añade métricas después: porcentaje de llamadas bloqueadas, reintentos por causa y tiempo hasta la decisión final. Es un punto de control pequeño, pero cambia mucho la calidad operativa del sistema.

Playwright Email Fixtures Need Better Failure Evidence

Silviu Technology — Sun, 15 Nov 2026 05:23:31 +0000

Email tests rarely fail because an email is completely absent. More often, the test sees the wrong message, reads the inbox too early, or loses the evidence that would explain what happened. A temp mail generator can provide a useful isolated fixture, but isolation alone does not make an end-to-end test diagnosable.

This is the workflow I use when a Playwright email test is flaky: define the expected states, capture the first useful evidence, and make every retry explain what changed. The goal is not to add more waits. It is to make the failure tell us which boundary broke.

The failure is often a missing state, not a missing email

Consider a signup test that requests a verification code. The test opens an inbox and waits for a message with the subject “Verify your account.” It passes locally, then fails in CI with “message not found.”

That message hides several different failures:

The signup request never completed.
The message was sent to a previous fixture address.
The inbox API returned an older message first.
The email arrived after the polling deadline.
The code was present, but the selector matched the wrong element.
The test found the message but failed while parsing its body.

Each case needs a different fix. A longer timeout only makes some of them slower. The first diagnostic step is to record the boundary events: fixture created, address submitted, request accepted, message observed, code extracted, and verification completed.

Model the fixture as a state ledger

I prefer a small state ledger over a single waitForEmail() helper. The ledger gives each transition a timestamp and a compact detail value without storing the whole mailbox contents in every log line.

type EmailState =
  | "fixture-created"
  | "address-submitted"
  | "message-observed"
  | "code-extracted"
  | "verified"
  | "expired";

const states: Array<{ name: EmailState; at: string; detail?: string }> = [];

function mark(name: EmailState, detail?: string) {
  states.push({ name, at: new Date().toISOString(), detail });
}

The ledger should be attached to the test result when a step fails. Do not log the verification code itself; record its source message ID, subject, and age instead. This keeps the artifact useful without turning a CI report into a copy of the inbox.

A state ledger also catches an easy-to-miss problem: the first clue are often in the order of events. If message-observed occurs before address-submitted, the test may be reading a stale message or sharing a fixture across workers.

Build a diagnostic Playwright helper

The helper should poll for a message using a stable identity, not a broad text match. A good identity usually combines the fixture address, a test-run token, and a bounded age. Subject text can be part of the check, but it should not be the only check.

async function waitForVerification(page: Page, token: string) {
  const deadline = Date.now() + 30_000;

  while (Date.now() < deadline) {
    const message = await readLatestMessage();
    if (message && message.runToken === token) {
      mark("message-observed", message.id);
      const code = extractCode(message.text);
      if (!code) throw new Error(`Message ${message.id} has no code`);
      mark("code-extracted", message.id);
      return code;
    }

    await page.waitForTimeout(1_000);
  }

  mark("expired", `token=${token}`);
  throw new Error("Verification message did not arrive before the deadline");
}

In the real helper, keep the polling interval and deadline configurable. Capture one sanitized response summary on timeout: message count, newest message timestamp, and the requested token. That is usually enough to tell whether delivery or matching failed.

If a selector is involved, prefer a role or a data attribute that the application owns. Avoid a selector such as text=123456; another message can contain the same number. Playwright is very good at reporting selector failures, but only when the test gives it a stable target.

Keep the mailbox boundary explicit

The mailbox is an external dependency even when it is created by a test service. Give each worker a unique address or run token, and clean it up after the test. Also separate the browser timeout from the email delivery timeout. They measure different things and should produce different errors.

When documenting fixtures, search terms can be messy. Someone may write tepm mail com or temp gamil com in a failure ticket. Keep those phrases in troubleshooting notes if they help search older incidents, but do not turn them into selectors or production validation rules. The phrase temp mail mail can likewise appear in an imported test description without being a reliable fixture identifier.

For privacy-sensitive flows, review what the fixture service retains and who can access it. These privacy notes for email checks are a useful reminder that test data still deserves a boundary and a deletion policy.

A repeatable CI failure checklist

When the test fails, check the evidence in this order:

Identity: Was the same address or run token used from setup through message lookup?
Application event: Did the signup request return the expected status before polling began?
Delivery: Did any message arrive within the deadline, even if it had an unexpected subject?
Matching: Did the message contain the current token, or was it stale?
Parsing: Was the message body format different from the local fixture?
Browser state: Did the page navigate, reload, or lose the verification form while waiting?
Artifact quality: Can another engineer replay the relevant inputs from the CI artifact?

If the failure is intermittent, save a small replay pack with the state ledger, sanitized message metadata, request correlation ID, and the final page screenshot. An approach based on replay packs for easier debugging works well because it preserves the facts without asking a developer to guess which retry was meaningful.

Questions that help classify the failure

Should I increase the email timeout first?

No. First determine whether the message arrived late, arrived under a different identity, or was never requested. Increase the deadline only when delivery latency is the known cause, and keep the failure artifact so the new budget remains visible.

Is a temp mail generator suitable for every test?

It is useful for isolated signup and verification scenarios, especially when each run gets a unique fixture. It is less suitable for tests that need long-term mailbox history, guaranteed retention, or sensitive production-like data. In those cases, a controlled fake mail adapter may be more predictable.

What makes an email test reliable?

Reliable tests have unique identity, explicit states, bounded polling, stable selectors, sanitized evidence, and cleanup. They also fail at the first broken boundary. That last part matters most: a test that says “verification failed” is hard to repair, while one that says “message arrived for the previous run token” points directly to fixture isolation.

The practical rule is simple: treat email as a sequence of observable states, not a single asynchronous event. Once Playwright records that sequence, flaky failures become smaller QA problems with evidence instead of mysterious red builds.

Agentes LLM: un presupuesto de latencia para email

Silviu Technology — Sat, 14 Nov 2026 11:23:53 +0000

Los agentes LLM pueden llamar APIs, crear datos de prueba y decidir el siguiente paso de un flujo. Pero cuando el flujo incluye un email, aparece un problema menos vistoso: el agente puede quedarse esperando una bandeja que nunca confirma nada.

La solución no es subir todos los timeouts. Es tratar el email de prueba como un recurso con un presupuesto de latencia. Así el agente sabe cuanto tiempo tiene, qué estados son válidos y cuándo debe entregar el control a un worker o a una persona.

El problema: un agente que espera demasiado

Imaginemos un agente que valida un onboarding. Crea un usuario, solicita una verificación y espera un enlace. Si usa un bucle de “consultar hasta que aparezca”, tenemos tres riesgos:

consume tokens y conexiones mientras no ocurre nada;
confunde una bandeja vacía con un fallo de la aplicación;
reintenta una operación que ya fue aceptada por el proveedor de correo.

En un flujo pequeño, esto solo hace la prueba más lenta. En una cola de automatización, puede ocupar workers, multiplicar el trafico y ocultar el error real. Por eso conviene separar la decisión del agente de la espera del sistema.

Dibujar el presupuesto como un contrato

Un diseño sencillo tiene tres piezas:

Agente LLM: solicita un fixture de correo, inicia la acción y decide qué hacer con el resultado.
Worker de email: consulta la bandeja, normaliza eventos y aplica el timeout.
Ledger de ejecución: guarda run_id, estado, último intento y causa de salida.

En palabras, el recorrido es: agente → comando idempotente → worker → evento terminal → agente. El agente no debería consultar directamente cada pocos segundos. Su contrato puede ser algo así:

deadline = ahora + 45 s
estado inicial = waiting_for_email
resultado terminal = received | expired | rejected
reintento máximo = 2

Los 45 segundos no son una verdad universal. Son una decisión operativa que se puede medir. Para una prueba local quizá basten 15; para un proveedor externo, 60 puede ser más realista. Lo importante es que el límite exista y que esté visible en los logs.

Estados y reintentos que no se pisan

El worker debe distinguir entre “todavía no llegó”, “llegó un evento inválido” y “la fuente no responde”. Un modelo mínimo:

from enum import StrEnum

class EmailState(StrEnum):
    WAITING = "waiting_for_email"
    RECEIVED = "received"
    EXPIRED = "expired"
    REJECTED = "rejected"

Cada consulta debe llevar una clave de idempotencia, por ejemplo run_id:message_type. Si el agente reenvía el mismo comando, el worker recupera el resultado existente en vez de crear otra dirección. Esto es especialmente útil al usar un correo temporal gratis para aislar datos de una ejecución.

También conviene aplicar backoff con un máximo estricto. Una secuencia de 2, 5 y 10 segundos es fácil de razonar. Si el tercer intento termina el presupuesto, el estado es expired; no se debe reiniciar el reloj solo porque el modelo decidió preguntar de nuevo.

Una implementación pequeña

La interfaz del worker puede ser deliberadamente aburrida:

def wait_for_email(run_id: str, deadline: float) -> dict:
    while time.monotonic() < deadline:
        event = inbox.next_event(run_id=run_id, timeout=2)
        if event is None:
            continue
        if event.kind == "verification_link":
            return {"state": "received", "url": event.url}
        if event.kind == "provider_error":
            return {"state": "rejected", "reason": event.reason}

    return {"state": "expired", "reason": "deadline_exceeded"}

El agente recibe un resultado estructurado, no una explicación ambigua. Puede entonces corregir el selector, repetir la acción original o marcar la prueba como no concluyente. En la practica, esta frontera reduce bastante los prompts que intentan “adivinar” si la bandeja ya se actualizó.

Para pruebas manuales, una fuente de correo desechable gratis puede ser suficiente si la política del proyecto permite datos efímeros. No la usaría para cuentas reales, secretos ni recuperación de acceso. El fixture debe tener una duración y un responsable claros.

Señales y límites operativos

El ledger debe registrar al menos:

run_id y nombre del flujo;
edad del mensaje y tiempo restante;
número de consultas y reintentos;
estado terminal y razón;
hash o identificador del fixture, nunca su contenido sensible.

Una métrica útil es email_wait_budget_exhausted_total. Otra es el p95 del tiempo entre la solicitud y el evento recibido. Si sube el p95 pero no aumenta el número de errores del proveedor, el problema puede ser la frecuencia de polling. Si aumentan ambos, hay que revisar la dependencia externa.

En una interfaz humana, estos estados también deben ser comprensibles. El artículo sobre estados de correo en React muestra por qué una UI no debería quedarse congelada durante una espera. Para operaciones, las alertas que guían el diagnóstico siguen la misma idea: indicar acción y contexto, no solo color rojo.

A veces el dato no llegan antes del deadline y eso no significa que el producto esté roto. Significa que el contrato produjo una señal útil. Un circuit breaker puede abrirse después de varios provider_error, mientras que los expired deberían alimentar un análisis distinto. Mezclar ambos estados hace que el equipo persiga por que una prueba aislada falló.

Checklist de implementación

Antes de poner este patrón en una automatización con LLM, revisaría:

¿El agente emite una orden idempotente?
¿Existe un deadline absoluto, independiente del modelo?
¿El worker devuelve estados terminales y una causa?
¿Los reintentos conservan el mismo run_id?
¿Se puede distinguir timeout, rechazo y bandeja vacía?
¿Las métricas muestran p95 y presupuesto agotado?
¿Se eliminan los fixtures al terminar su ciclo?

Las búsquedas humanas pueden escribir “tamp mail com” o “tem email”, pero la arquitectura no debe depender de esas variantes. Debe depender de contratos pequeños y observables. Un agente LLM es más confiable cuando sabe cuándo esperar, cuándo parar y qué evidencia entregar al siguiente componente.

A Failure Budget for Playwright Email Tests

Silviu Technology — Sat, 14 Nov 2026 05:24:32 +0000

Email verification tests often look simple: submit a form, wait for a message, click a link, and confirm the account is active. In a real CI run, that short scenario crosses several systems. A browser submits the request, an API queues a message, a mail service accepts it, a mailbox exposes it, and Playwright reads the result.

When the test fails, the red line rarely tells you which system was late or wrong. A longer timeout can make the dashboard greener while making the diagnosis worse.

I use a failure budget instead. The idea is simple: define how much waiting and retrying each stage is allowed, then preserve evidence when that budget is spent. This gives a QA team a repeatable way to separate a slow email from a broken verification flow.

Why email tests need a budget

An email test has at least four clocks:

The browser clock: how long the UI waits for a response.
The application clock: how long the API takes to create and queue the message.
The delivery clock: how long the message takes to reach the test mailbox.
The processing clock: how long the test takes to parse the message and follow its link.

If these clocks are hidden inside one expect(...).toBeVisible() call, a failure is hard to classify. A burner email address may be valid, but the fixture can still be stale. A message may exist, but contain a link for a different test run. Or the application may never have queued anything.

The budget makes those possibilities visible. Give the API response, mailbox discovery, and link processing separate limits. The values are not universal; the useful part is assigning ownership to each wait.

Define the causal timeline

Before writing assertions, record the identifiers that connect the browser action to the message:

test run ID
user or fixture ID
message request ID, if the API returns one
mailbox address
verification token or message ID, when safe to expose in test logs

Then log milestones, not every polling attempt:

const timeline = {
  startedAt: Date.now(),
  requestSentAt: 0,
  messageFoundAt: 0,
  verificationClickedAt: 0,
};

await page.getByLabel('Email').fill(email);
timeline.requestSentAt = Date.now();
await page.getByRole('button', { name: 'Create account' }).click();

After the mailbox helper finds a message, add messageFoundAt. After the browser completes verification, add verificationClickedAt. If messageFoundAt is zero, the failure is probably delivery or fixture isolation. If the message is found but the link is rejected, inspect token ownership and application state.

The state model should be explicit too. A small union such as requested, delivered, opened, verified, and expired prevents a test from treating every non-success response as the same thing. See type-safe signup email states for a useful pattern.

Classify failures before retrying

Retries are useful only for failures that are plausibly transient. I put failures into three groups:

Application failure: the signup request returns an error, the message is never queued, or the verification endpoint rejects a token that was just issued. Retrying can hide a product bug, so capture the response and stop.

Delivery failure: the request succeeded, but no matching message appears before the mailbox budget expires. Keep the mailbox query, timestamps, and correlation IDs. Do not silently switch to another inbox.

Test-observer failure: the message exists and the token is valid, but the helper parsed the wrong element or the page assertion raced the navigation. Fix the observer or assertion; adding more delivery time will not help.

A retry should create a new fixture identity. Reusing the same address can pick up an earlier message, which makes the second attempt look successful for the wrong reason. This is where a test contract for email probes is useful: it can define matching rules, ownership, expiry, and what evidence a probe must return.

A Playwright implementation

Keep mailbox polling in a helper with a deadline rather than an unbounded loop:

async function waitForVerification(
  inbox: { messages: (address: string) => Promise<Array<{ subject: string; url: string }>> },
  address: string,
  deadlineMs = 30_000,
) {
  const deadline = Date.now() + deadlineMs;

  while (Date.now() < deadline) {
    const messages = await inbox.messages(address);
    const match = messages.find((message) => message.subject.includes('Verify'));
    if (match) return match;
    await new Promise((resolve) => setTimeout(resolve, 1_000));
  }

  throw new Error(`Verification email not found for ${address}`);
}

The helper should return structured data, not only a URL. Include the message ID, received time, subject, and a sanitized parse-failure reason. Avoid dumping full message bodies into CI logs because verification links can contain sensitive tokens.

Also assert the causal relationship. The message should belong to the current run, the link should target the expected environment, and the resulting account should match the fixture. A test that only checks that “some” verification link works is passing a weaker requirement than the product actually has.

A CI review checklist

When a Playwright email test fails, ask these questions in order:

Did the browser request complete, and with which status?
Was a message queued for this run and address?
Did the mailbox return a matching message before the deadline?
Was the link parsed from the expected message?
Did the verification endpoint accept the token?
Did the UI reach the expected state after navigation?

The wording in failure output matters. “Expected verified state” is vague. “No message for run abc after 30 seconds; request completed at 2.1 seconds” gives the next engineer somewhere to start.

Keep test data short-lived: a tem email or temp org mail fixture should be isolated and cleaned up after every run.

Common questions

Should I retry a missing email?

Only after recording that the application request succeeded and the message was queued. Use a bounded retry with a fresh fixture. If the queue event is absent, treat it as an application failure.

Is a longer Playwright timeout a solution?

Usually not. Increase a stage-specific budget only when delivery measurements support it. A global timeout hides which clock is slow and makes unrelated UI failures take longer.

What is the most valuable artifact after a failure?

A causal timeline with the run ID, fixture address, request result, mailbox result, and final browser state. It lets someone reproduce the reasoning without rerunning the whole job.

Reliable email testing is less about waiting longer and more about knowing what happened. Give every stage a budget, make state transitions explicit, and preserve enough evidence to tell a product failure from a delivery delay. That turns a flaky-looking Playwright test into a diagnostic tool for the whole verification system.

Agentes LLM: permisos mínimos para email de prueba

Silviu Technology — Thu, 12 Nov 2026 20:23:39 +0000

Un agente LLM puede crear un buzón, provocar un registro y leer un código de verificación en pocos pasos. Esa capacidad resulta útil para probar productos, pero también crea una frontera de seguridad poco visible: el modelo tiene acceso a una herramienta que puede generar datos, consultar mensajes y mantener recursos vivos.

La solución no es quitar la automatización. Es darle permisos mínimos, un tiempo de vida corto y respuestas que hagan evidente lo que acaba de ocurrir. Un correo de usar y tirar debe ser un recurso de prueba acotado, no una identidad que el agente pueda reutilizar sin límite.

El problema: una herramienta demasiado poderosa

Cuando se expone una sola función como email_tool, el modelo suele recibir demasiadas opciones: crear una dirección, listar mensajes, reenviar contenido, buscar por asunto y borrar recursos. Cada operación parece razonable por separado, pero juntas permiten que un fallo del prompt o una respuesta ambigua amplíe el alcance de la tarea.

El riesgo aparece en varios lugares:

Un reintento crea un segundo buzón y deja el primero sin dueño.
Una búsqueda amplia mezcla mensajes de ejecuciones anteriores.
El contenido completo del correo termina en el contexto del LLM, aunque solo se necesitaba un código.
Un flujo cancelado no libera la dirección ni sus mensajes.

En CI, este problema se parece a cualquier recurso temporal sin propietario. Un contrato de caducidad para emails de CI ayuda a pensar en el tiempo de vida antes de hablar de prompts. La pregunta no es solo si el agente puede llamar la herramienta, sino que puede hacer exactamente con cada llamada.

Define la frontera de permisos

Antes de diseñar el prompt, dibujo la frontera en palabras:

orquestador de la prueba
  ├─ crea un buzón con task_id
  ├─ dispara el evento de producto
  ├─ observa solo mensajes de esa ejecución
  ├─ extrae un dato mínimo
  └─ revoca el recurso al terminar

El agente no necesita conocer todas las operaciones internas. Puede tener tres capacidades pequeñas:

create_fixture(task_id, expires_at): reserva una dirección asociada a una ejecución.
wait_for_code(fixture_id, correlation_key, deadline): devuelve solo el estado y el código necesario.
release_fixture(fixture_id): marca el recurso para eliminación, incluso despues de un fallo.

La diferencia importante es que el servidor aplica las restricciones. El prompt puede pedir un buzón con una duración razonable, pero nunca debe ser la única barrera. El backend comprueba que task_id pertenece a la ejecución actual, que expires_at no supera el máximo permitido y que el agente no está leyendo otra fixture.

Un límite de permisos así reduce la superficie de error sin convertir el sistema en una arquitectura enorme. Si el agente necesita consultar el asunto, se añade un campo específico. No hace falta darle una operación genérica para listar toda la bandeja.

Un contrato mínimo para el agente

Las respuestas de las herramientas también son una interfaz de seguridad. Un mensaje como “no encontrado” invita a improvisar; una respuesta estructurada limita mejor la siguiente acción:

{
  "status": "waiting",
  "fixture_id": "fx-1842",
  "remaining_ms": 18000,
  "observed_messages": 0,
  "next_action": "poll_after_3s"
}

Yo mantendría estos campos en todas las operaciones:

status: created, waiting, ready, expired o provider_error.
fixture_id: identificador opaco, sin exponer la dirección completa al modelo.
remaining_ms: tiempo disponible para el paso actual.
attempt: número de consulta dentro de la misma ejecución.
next_action: sugerencia limitada, no una instrucción libre.

El estado expired debe ser terminal. Si el agente recibe ese estado, no debería crear otra dirección automaticamente para repetir la prueba. El orquestador decide si se inicia una nueva ejecución y conserva la relación con el fallo original.

Este enfoque encaja bien con contratos de email para pruebas repetibles: cada prueba tiene una identidad, una condición de salida y una evidencia que se puede revisar sin abrir todo el buzón.

Evidencia, caducidad y rollback

Un agente confiable necesita una ruta de salida tan clara como la ruta feliz. Al terminar una ejecución, guardaría un recibo pequeño con:

task_id y fixture_id;
instante de creación y de liberación;
evento que originó el mensaje;
cantidad de consultas y tiempo consumido;
motivo de éxito, expiración o error.

El contenido del correo no debe entrar al recibo salvo que sea necesario para depurar. Para un código de verificación basta con almacenar un hash o los últimos caracteres, dependiendo del caso. Asi el equipo puede comprobar causalidad sin convertir los logs en otra bandeja de entrada.

La caducidad debería tener dos capas: una fecha aplicada por el proveedor y una limpieza de respaldo en el orquestador. Si una llamada queda a medias, el job de limpieza usa el fixture_id y elimina los recursos vencidos. No conviene depender de que el LLM recuerde llamar a release_fixture cuando ya recibió un error.

En documentación interna pueden aparecer búsquedas imperfectas como tempail mail. Las trato como señales de intención de prueba, no como nombres de herramientas que el agente deba resolver por su cuenta. También conviene registrar el motivo real del bloqueo, en vez de esconderlo detrás de un “falló el email”.

Q&A: decisiones prácticas

¿El LLM debe poder crear direcciones?

Sí, pero solo a través de una capacidad ligada a task_id, con duración máxima y cuota por ejecución. La decisión de permisos vive en el servidor, no en la personalidad del agente.

¿Por qué no exponer la bandeja completa?

Porque amplía el alcance de un error y hace difícil separar mensajes viejos de los nuevos. Una operación que espera un código concreto es mas fácil de auditar que una que devuelve todos los mensajes.

¿Qué hago cuando el proveedor de email falla?

Devuelve provider_error, conserva el recibo y ejecuta la limpieza. No repitas automáticamente con otra fixture si no sabes si el primer evento pudo llegar; primero marca la ejecución como inconclusa.

¿Dónde encaja tempmailso?

Puede servir como una temp mail so para aislar datos de una prueba, siempre que el equipo aplique su propia política de caducidad y no lo trate como una identidad real.

La arquitectura mínima es bastante concreta: una fixture con propietario, tres capacidades limitadas, respuestas estructuradas y una limpieza que no dependa del modelo. Con esos límites, los agentes LLM siguen siendo utiles para explorar flujos, pero sus herramientas de email dejan de comportarse como una caja negra.

Playwright Email Tests Need a Quarantine Queue

Silviu Technology — Thu, 12 Nov 2026 08:24:27 +0000

Playwright Email Tests Need a Quarantine Queue

Email verification tests often look like browser tests, but the hardest part is usually the boundary between the application and the inbox. The browser clicks Send verification email, while a separate service delivers a message, indexes it, and exposes a link. If the test treats that whole path as one instant operation, a failure can look random even when the cause is repeatable.

In QA automation, I prefer to treat every email test as a small investigation. The test should have an isolated inbox, a deadline, and enough evidence to answer one question: did the message never arrive, arrive late, or arrive with the wrong state? A quarantine queue is a simple way to preserve that distinction without letting one suspicious run poison the rest of the suite.

The failure is usually a race, not a random browser problem

Consider this sequence:

Playwright submits the registration form.
The API accepts the request and queues an email.
A worker renders and sends the message.
The inbox service receives and indexes it.
The browser opens the verification link.

The test can only observe the edges of this process. A fixed waitForTimeout(2000) hides the uncertainty, but it does not remove it. On a fast laptop it wastes time; in a busy CI environment it can be too short. That is why the same test may pass locally and fail in an enviroment with slower workers.

The first useful change is to give each run a unique address or mailbox namespace. A burner email can be appropriate for a controlled test system, as long as the address is isolated, disposable, and never used for real customer data. Do not share one inbox across parallel workers: an old verification link can make a new test appear healthy.

What belongs in the quarantine queue

Quarantine is not a second pass that reruns every red test forever. It is a bounded holding area for failures where the application result is not yet known. I normally record:

the Playwright test title and commit SHA;
the worker and browser project;
the run-scoped inbox identifier;
the request time and the first time a matching message was seen;
the message subject, provider status, and extracted link host;
a screenshot, trace, and relevant server correlation ID.

The evidence should not contain the full email body by default. Store a hash, selected headers, and the minimum redacted excerpt needed to diagnose the problem. If a test searches for a phrase typed by a user, remember mistakes such as tepm mail com or tem email; keep those values as test inputs, not failure labels.

A Playwright fixture with an evidence trail

The fixture below shows the important shape. The inbox client is deliberately abstract.

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

type Mail = { id: string; receivedAt: number; text: string };

type Fixtures = {
  runId: string;
  waitForVerification: () => Promise<Mail>;
};

export const test = base.extend<Fixtures>({
  runId: async ({}, use, testInfo) => {
    await use(`${testInfo.workerIndex}-${testInfo.testId}-${Date.now()}`);
  },

  waitForVerification: async ({ runId }, use, testInfo) => {
    const startedAt = Date.now();
    const waitForMessage = async (): Promise<Mail> => {
      // Replace with a bounded poll against the test inbox service.
      throw new Error(`No matching message for ${runId}`);
    };

    await use(async () => {
      try {
        const mail = await waitForMessage();
        expect(mail.receivedAt).toBeGreaterThanOrEqual(startedAt);
        return mail;
      } catch (error) {
        await testInfo.attach('mail-context', {
          body: JSON.stringify({ runId, startedAt }),
          contentType: 'application/json',
        });
        throw error;
      }
    });
  },
});

The real poller should use a deadline and a backoff, not an unbounded loop. It should also filter by runId before checking the subject. That ordering matters becuase two messages can have the same subject while only one belongs to this test.

For a more formal boundary, the ideas in typed contracts for email tests are useful: make invalid states difficult to pass into the next step. The fixture can return a VerifiedMessage only after the timestamp, recipient, and link checks succeed.

How to classify and replay a failure

When a test fails, ask what the last confirmed state was:

No send request: investigate the product flow or the browser action.
Send accepted, no message: inspect the worker, provider, and inbox boundary.
Message found, wrong run ID: investigate data isolation and cleanup.
Correct message, bad link: treat it as an application or template failure.
Correct link, browser failure: inspect navigation, authentication, or the target page.

Only the second and third categories are good candidates for a bounded quarantine retry. Replay with the same evidence and a new run ID. Never replay by reusing the original mailbox, because that can turn a stale message into a false pass. If the retry succeeds, keep both attempts visible; a green retry is a signal about reliability, not proof that the first failure was harmless.

When the test uses an external address for a documented scenario, use a natural label such as temp mail for facebook only in the test-data notes, not as a substitute for a production identity. The test should verify the product's behavior and cleanup policy, not encourage a real account workflow.

Practical checklist

Before merging an email test, check:

Is the inbox unique per worker and run?
Does the message query require a run identifier and a fresh timestamp?
Is polling bounded and observable?
Are traces and screenshots attached only when useful?
Can the failure be classified from the saved evidence?
Does quarantine expire and avoid automatic retry loops?
Is cleanup attempted even when the browser step fails?

A test that fails with a causal timeline is much cheaper to maintain than one that merely says “verification email not found.” The goal is not to make Playwright tolerate every delay. It is to make the next failure tell the team where the delay or state mismatch began.

Questions worth asking

Should I retry every missing email?

No. Retry only when the evidence says the request was accepted and the missing message may be a transient delivery problem. A missing send request is a product failure and should remain red.

Is a disposable mailbox always safe for testing?

No. Keep it restricted to non-sensitive data, understand who can access the inbox, and delete messages after the run. The isolation contract matters more than the label “disposable.”

Playwright Email Tests Need a State Ledger

Silviu Technology — Tue, 10 Nov 2026 23:23:18 +0000

Email verification tests often fail in a confusing way: the browser says that the confirmation page is ready, but the message belongs to a previous run, the link is expired, or the inbox has not received anything yet. The final assertion is where the test stops, not where the failure started.

This is the workflow I use when a Playwright email test needs better evidence. I give every run a small state ledger. The ledger records what the test asked for, what message it observed, and which verification state was reached. It turns a vague “email test failed” into a short causal story that QA can act on.

Why a passing browser assertion can hide an email failure

An email verification flow crosses several systems:

The browser submits an address.
The application creates a verification request.
A mail service accepts and delivers the message.
The test reads the message and opens its link.
The application changes the account state.

If the test only asserts the last step, all five stages look like one operation. A stale message can satisfy a loose subject check. A shared inbox can make the test pass with an address from another run. A retry can then hide the original problem.

A burner email may help isolate test data, but isolation alone does not explain timing or message identity. The test still needs to say which request it is waiting for.

Model the verification flow as a state ledger

Keep the ledger small and append-only. For each run, record an event such as:

type EmailEvent = {
  runId: string;
  state: "requested" | "delivered" | "opened" | "verified" | "expired";
  messageId?: string;
  observedAt: string;
  detail?: string;
};

The important field is runId. Put it in the test address, a request header, or metadata that your mail test fixture can query. The exact transport matters less than being able to connect a message to one browser run.

Do not overwrite the previous event when a poll repeats. That small choice preserve the sequence and makes a delayed delivery visible. It also keeps a test retry from erasing the evidence produced by the first attempt.

For sensitive environments, pair the ledger with a redaction contract for verification logs. Logs should identify the message without copying the full token or mailbox contents.

Capture the ledger in a Playwright test

The browser test can write events beside its trace. Here is a deliberately simple pattern:

const events: EmailEvent[] = [];
const record = (state: EmailEvent["state"], detail?: string) => {
  events.push({ runId, state, observedAt: new Date().toISOString(), detail });
};

record("requested");
await page.getByRole("button", { name: "Send verification email" }).click();

const message = await inbox.waitForMessage({
  to: testAddress,
  subject: /Verify your account/,
  timeoutMs: 30_000,
});
record("delivered", message.id);

await page.goto(message.verificationUrl);
record("opened", message.id);
await expect(page.getByText("Email verified")).toBeVisible();
record("verified", message.id);

In a real fixture, waitForMessage should reject messages whose run marker does not match. It should also report the last polling observation in its error, not only “timeout”. The test pass is more useful when the failure says “requested, no matching delivery after 30 seconds” than when it says “expected text to be visible”.

Diagnose the first bad state

When a run fails, inspect the first transition that did not happen. If requested is missing, the browser action or fixture setup failed. If delivered is missing, check the mail service, address routing, and delivery timeout. If opened is missing, inspect URL extraction and token expiry. If verified is missing, the application probably rejected the token or the page assertion is looking at the wrong state.

This order stops a common debugging mistake: changing Playwright waits when the message was never delivered. More waiting can make the suite slower while keeping the root cause untouched.

For CI pipelines, store the ledger with the trace and link it to a promotion receipt for CI email tests. A failed run then has both the browser evidence and the environment transition that produced it.

A small QA checklist for reliable email tests

Give each run a unique marker and test address.
Match the recipient, run marker, and message purpose.
Record every state transition; do not only record the final result.
Make polling errors include the last observed state.
Expire or clean test data after the run, even on failure.
Redact tokens, message bodies, and personal addresses from artifacts.
Keep one focused test for delivery and another for token acceptance.

If your team calls a fixture “temp org mail” in a note or dashboard, keep that label separate from the real run identifier. Informal names are handy, but they are not a reliable correlation key.

The goal is not to add a large observability platform to every end-to-end test. It is to preserve enough evidence to answer one question: what was the first email state that became false? Once that answer is recorded, Playwright failures become easier to reproduce, triage, and fix.

Agentes LLM: un contrato de identidad para emails

Silviu Technology — Tue, 10 Nov 2026 05:24:00 +0000

Un agente LLM puede completar un flujo de registro en pocos segundos y, aun así, dejar una prueba imposible de depurar. El formulario se envió, llegó el correo de verificación y el agente hizo clic en el enlace correcto. Pero cuando el paso falla, nadie sabe qué mensaje leyó, qué buzón pertenecía a la ejecución o si un reintento reutilizó datos viejos.

El problema no suele ser el modelo. Es la falta de una identidad técnica para cada email de prueba. Un generador de emails falsos puede crear una dirección, pero el sistema de automatización todavía necesita decidir quién la posee, cuánto dura y qué evidencia debe producir.

El problema: el agente pierde la identidad del email

En un flujo sencillo, la relación parece obvia:

ejecución -> dirección -> mensaje -> enlace -> resultado

En un flujo con agentes aparecen más caminos. El modelo puede reintentar una herramienta, delegar el paso a otro agente o continuar después de un timeout. Si todos consultan una bandeja compartida, el mensaje correcto deja de ser una certeza. Un correo parecido puede activar el flujo equivocado y hacer que el resultado parezca válido.

La ambigüedad aumenta cuando se usan nombres informales para buscar una solución, como dummy e mail o tempail mail. Esas frases pueden servir para entender consultas, pero no son una identidad de ejecución ni un criterio de seguridad.

La primera decisión de arquitectura es separar el objetivo del agente de la infraestructura que lo ejecuta. El agente debe pedir “espera el mensaje de verificación de esta ejecución”, no “busca el correo más reciente en esta bandeja”.

Diseñar una identidad por ejecución

Cada flujo debe recibir un run_id único y conservarlo hasta el cierre. La identidad puede tener esta forma:

{
  "run_id": "checkout-20261110-0522-a81f",
  "owner": "agent-registration",
  "mailbox_id": "mbx-7f2c",
  "purpose": "verification",
  "expires_at": "2026-11-10T05:42:00Z"
}

La dirección es solo una parte del contrato. run_id permite correlacionar la acción del agente, la solicitud de la API, la llegada del mensaje y el resultado del test. purpose evita que un mensaje de recuperación de contraseña se confunda con uno de bienvenida. expires_at da al sistema una decisión clara cuando el agente abandona el flujo.

En términos de diseño, el agente obtiene una referencia opaca y no necesita conocer detalles del proveedor. El adaptador de email traduce esa referencia a una dirección temporal, aplica el filtro por ejecución y devuelve eventos normalizados. Es un límite pequeño, pero hace mas fácil cambiar de proveedor o probar el adaptador en local.

Cuando el flujo también mide activación, conviene medir la activación sin perder el hilo del email. La métrica no debería decir solamente “se recibió un correo”; debe poder responder qué ejecución lo recibió y qué acción ocurrió después.

Un contrato mínimo para agentes LLM

Las herramientas que ve el modelo necesitan nombres y respuestas predecibles. Un contrato mínimo puede tener tres operaciones:

reserve_mailbox(purpose, ttl): crea una identidad aislada y devuelve mailbox_id y run_id.
wait_for_message(mailbox_id, kind, timeout): busca solo mensajes asociados a esa identidad.
release_mailbox(mailbox_id, reason): marca la fixture como terminada y activa la limpieza.

La respuesta de wait_for_message no debe entregar el buzón completo ni datos innecesarios. Es suficiente con un evento como este:

{
  "status": "received",
  "message_id": "msg-91ab",
  "kind": "verification",
  "received_at": "2026-11-10T05:25:11Z",
  "link": "https://app.example.test/verify?token=redacted"
}

El token puede mantenerse fuera del historial visible al modelo y resolverse mediante una acción controlada. Así se reduce el riesgo de que un resumen, una traza o una llamada posterior copie un secreto. Si el agente necesita el enlace, el adaptador puede validar que pertenece al dominio esperado antes de devolverlo.

No hace falta convertir tempmailso en una dependencia del razonamiento del agente. Puede aparecer como término de inventario o de búsqueda, pero la integración debe depender de una interfaz propia, con límites y políticas definidos por el equipo.

Cómo evitar mezclas durante los reintentos

Los reintentos son donde se rompe la mayoría de los diseños ingenuos. Si una llamada expira después de crear la bandeja, repetirla puede producir otra identidad. Si el primer agente vuelve a despertar, puede leer el mensaje de la segunda.

La solución es que la reserva sea idempotente para una clave de ejecución. El adaptador puede aceptar idempotency_key = run_id + purpose y devolver la misma referencia mientras la fixture siga activa. El estado debería distinguir, al menos, reserved, message_received, verified, failed y expired.

También hay que definir qué significa “mensaje más reciente”. En general, no basta con ordenar por fecha. El filtro debe comprobar mailbox_id, tipo de mensaje, emisor esperado y una ventana temporal razonable. Si faltan esas señales, el agente debe recibir un resultado ambiguous y detenerse, no elegir por intuición.

Un reconciliador externo puede retirar las fixtures vencidas aunque el proceso del agente haya terminado mal. Si el despliegue corre sobre Kubernetes, es útil validar alertas después de un cambio de secretos como parte del mismo enfoque: los cambios de infraestructura y las pruebas de email necesitan señales observables, no solo un log de éxito.

Observabilidad y límites de seguridad

Los logs deben permitir reconstruir la secuencia sin guardar el contenido completo de los mensajes. Una línea útil contiene run_id, mailbox_id, tool_call_id, estado, latencia y motivo del cierre. Los resultados llega mejor agrupados por ejecución que por dirección, porque la dirección puede ser efímera.

El modelo tampoco debería tener permiso para crear identidades sin límite, cambiar el dominio de destino o desactivar la expiración. El adaptador debe imponer un TTL máximo, permitir solo dominios de prueba y rechazar una dirección que ya pertenezca a otra ejecución. Estas reglas deben vivir fuera del prompt: un agente puede interpretar instrucciones, pero no debe ser la única barrera.

Preguntas frecuentes

¿Es necesario un buzón por agente?

No siempre. La unidad segura es la ejecución o el escenario. Dos agentes pueden compartir una identidad si tienen el mismo propósito y una coordinación explícita; una bandeja global para toda la suite es mucho más dificil de investigar.

¿Qué debe hacer el agente cuando llega un mensaje ambiguo?

Debe detener el paso, registrar la ambigüedad y solicitar una nueva consulta con criterios más estrictos. Elegir el mensaje mas reciente puede convertir un fallo de aislamiento en un falso positivo.

¿Puedo usar un proveedor real en pruebas locales?

Sí, si el adaptador oculta sus detalles, aplica expiración y evita datos personales. Para pruebas unitarias, una implementación en memoria suele ser suficiente y hace que el contrato sea más facil de verificar.

Checklist de implementación

Cada ejecución recibe un run_id y una identidad aislada.
La reserva usa una clave idempotente para soportar reintentos.
Las consultas filtran por buzón, propósito, emisor y ventana temporal.
El modelo recibe eventos mínimos, no secretos ni cuerpos completos.
La expiración tiene un límite impuesto por el adaptador.
Un reconciliador limpia fixtures abandonadas.
Los estados y las llamadas de herramientas quedan correlacionados.
Los casos ambiguos terminan con una señal explícita, nunca con una elección arbitraria.

La automatización con modelos LLM se vuelve más confiable cuando el agente no tiene que adivinar qué email le pertenece. Una identidad por ejecución, un contrato pequeño y una política de expiración convierten una integración frágil en un sistema que se puede observar, reintentar y explicar.

Playwright Email Tests: Find the First Bad State

Silviu Technology — Mon, 09 Nov 2026 20:24:08 +0000

Email verification tests often fail in the inbox step, but the inbox is rarely the real cause. A signup test can pass the form, create a user, request a message, and then fail because the assertion ran before the message became visible. The failure is usualy reported as “email not found,” which hides the more useful question: what was the first state that became impossible?

This Playwright workflow works with a temp mail so provider, a controlled burner email service, or an internal test inbox. Give every transition a timestamp, an owner, and a clear failure message.

Why email tests fail after the signup step

An email test usually crosses several systems:

The browser submits the registration form.
The application commits the account and queues an email.
A mail service accepts and processes the message.
The inbox API exposes the message.
Playwright opens the message and verifies the link or code.

Each step has a different kind of delay. A browser assertion can wait for a DOM element, but it cannot automatically wait for a message that has not been delivered yet. A fixed waitForTimeout sometimes masks this timing gap, then fails again under CI load.

The inbox is not a database query; its a delayed event. Treating it like one creates misleading retries and slow debugging.

Model the test as a state timeline

Before changing timeouts, name the states your test expects. For example:

form_submitted
account_created
message_requested
message_received
verification_link_opened
account_verified

Record the transition that your test can observe. The browser can observe the submitted form and the verification page. Your inbox client can observe message receipt. Your application logs can confirm account creation. If the test only records the final assertion, all earlier failures collapse into one vague symptom.

A small event record is enough:

type EmailTestEvent = {
  state: string;
  at: string;
  details?: Record<string, string>;
};

const events: EmailTestEvent[] = [];

function mark(state: string, details?: Record<string, string>) {
  events.push({ state, at: new Date().toISOString(), details });
}

Call mark("form_submitted") immediately after submit, and mark the inbox state only after the inbox client confirms a matching message. When a test fails, print the timeline with the test name and run ID.

A Playwright diagnostic workflow

Use a unique address per test or per worker. A shared burner email makes parallel tests compete for the same messages, so one test can consume another test’s verification link. Unique identity also makes cleanup and investigation safer.

const testEmail = `pw-${testInfo.workerIndex}-${Date.now()}@example.test`;
mark("test_identity_created", { email: testEmail });

await page.getByLabel("Email").fill(testEmail);
await page.getByRole("button", { name: "Create account" }).click();
mark("form_submitted");

await expect(page.getByText("Check your email")).toBeVisible();
mark("account_created");

const message = await inbox.waitForMessage({
  to: testEmail,
  subject: "Verify your account",
  timeoutMs: 30_000,
});
mark("message_received", { messageId: message.id });

const link = message.links.find((item) => item.includes("/verify/"));
expect(link).toBeTruthy();
await page.goto(link!);
mark("verification_link_opened");

await expect(page.getByRole("heading", { name: "Account verified" })).toBeVisible();
mark("account_verified");

The contract around waitForMessage should filter by recipient and subject, return a message ID, and fail with observed candidates. “Timed out after 30 seconds” is less useful than “received two messages for another recipient; no matching subject for this run.”

If your inbox API supports it, pass a run-scoped token in the message metadata. A simple contract can prevent an old message from satisfying a new test. The idea is similar to keeping email policy snapshots: preserve the evidence that explains what the system decided at that moment.

Keep inbox reads isolated and observable

There are three boundaries worth enforcing:

Identity boundary: generate an address that no other test uses.
Message boundary: match the recipient, subject, and run marker.
Cleanup boundary: expire or delete the inbox after the test, while retaining a small failure record.

Do not hide the inbox call inside a generic retry that catches every error. A retry should handle a message that is not available yet, not authentication errors, malformed responses, or a message with the wrong recipient. Those are different defects and should fail immediately.

For agent-driven or command-line test systems, a documented CLI inbox contract is helpful for the same reason. Define what “waiting” returns, how long it waits, and which evidence is retained. Otherwise, every caller invents a slightly different polling loop.

Also check the clock used in logs. Browser, application, and inbox-provider time may not line up perfectly. Use one local sequence number so the report can show event order. The report become less confusing when timestamps are supplementary evidence.

A practical failure checklist

When the test fails, inspect these items in order:

Was the address unique? Shared inboxes create false positives and missing messages.
Did the UI show the post-submit state? If not, investigate the form or API response first.
Was a message requested? Check the application event or request log.
Did the inbox receive any message? Keep the candidate subjects and recipients in the failure output.
Did the message belong to this run? Reject stale messages and links from previous attempts.
Was the link extracted correctly? Verify the URL pattern before navigating.
Did the verification page fail? Preserve the browser trace and the final response details.

The checklist is intentionally boring. Boring checks are repeatable, and repeatability is what turns flaky Testing into a diagnosable workflow. It also keeps a typo such as tepm mail com from becoming a hidden fixture assumption in a test report.

Questions teams usually ask

Should I increase the timeout first?

Only after confirming that the message is eventually delivered and belongs to the correct test. A longer timeout can reduce noise, but it cannot fix a missing event, a bad filter, or a shared inbox race.

Is polling always a problem?

No. Polling is reasonable when the provider offers no webhook or event stream. Make it bounded, observable, and selective. Record each retry reason, but keep the final failure short enough to scan in CI.

What should a retry repeat?

Prefer retrying the inbox read, not the entire signup flow. Repeating signup may create duplicate accounts and multiple verification messages, which make the original failure harder to understand.

What does a good failure message look like?

It names the run, recipient, expected subject, elapsed time, last observed state, and a safe list of candidate messages. That gives the next engineer a starting point instead of another unexplained timeout.

Once the test reports its first bad state, email verification stops being a mysterious end-to-end failure. Playwright remains responsible for browser behavior, the inbox client remains responsible for delivery evidence, and the timeline connects both without pretending they are one system.

React: formularios ágiles sin perder el foco

Silviu Technology — Sun, 08 Nov 2026 14:23:55 +0000

Un formulario moderno no solo debe enviar datos. También tiene que explicar qué está ocurriendo mientras el usuario escribe, valida, espera una respuesta o corrige un error. Cuando esos estados no están bien diseñados, la interfaz parece lenta aunque la red responda en pocos milisegundos.

En proyectos React he encontrado que una mejora pequeña, como reservar espacio para un mensaje de error o devolver el foco al campo correcto, suele tener más impacto que añadir otra librería. La idea es tratar el formulario como una secuencia de estados visibles y medibles, no como un botón con un spinner.

El formulario como una secuencia de estados

Un campo de email puede pasar por varios estados distintos:

vacío y listo para recibir entrada;
escribiendo, con una validación que todavía no terminó;
válido, pero esperando el envío;
rechazado, con una explicación que se puede corregir;
enviado, con una confirmación que no desaparece demasiado rápido.

El problema típico es representar todos esos casos con un único isLoading. Ese booleano no dice si el usuario está esperando una validación local, una respuesta del servidor o una transición de página. El resultado es una pantalla que parece bloqueada y un lector de pantalla que recibe poca información.

Separar los estados hace la UI más predecible. No hace falta crear una máquina de estados completa para cada formulario; un objeto pequeño suele ser suficiente:

const [status, setStatus] = useState("idle");
const [message, setMessage] = useState("");

async function submitEmail(event) {
  event.preventDefault();
  setStatus("sending");
  setMessage("");

  try {
    await sendEmail(event.currentTarget.email.value);
    setStatus("success");
    setMessage("Revisa tu bandeja de entrada.");
  } catch {
    setStatus("error");
    setMessage("No pudimos enviar el correo. Inténtalo de nuevo.");
  }
}

Lo importante no es el nombre exacto de cada estado. Es que cada transición tenga una consecuencia visual, semántica y de interacción.

Qué debe comunicar cada estado

Durante el envío, desactivar el botón puede ser correcto, pero no debería eliminar la posibilidad de entender la acción. Un texto como “Enviando…” es más util que un icono girando sin nombre. Si la operación dura más de lo esperado, la interfaz debe seguir mostrando el contexto del formulario.

Para los errores, coloca el mensaje junto al campo y conéctalo mediante aria-describedby. Así, el usuario puede volver al campo sin tener que descubrir dónde quedó la explicación. Después de un error de servidor, el foco puede regresar al primer campo que necesita atención; después de un éxito, un anuncio breve en una región aria-live suele ser suficiente.

También conviene reservar una altura mínima para el mensaje. Sin esa reserva, el contenido salta cuando aparece la validación y el foco visual se mueve. Ese pequeño salto no siempre rompe una métrica, pero si ocurre varias veces se siente como una interfaz descuidada.

En formularios de registro, algunas personas buscan ejemplos con términos imperfectos como tempail o tamp mail com. Aunque parezcan detalles de contenido, sirven para probar que los mensajes y los resultados de validación siguen siendo entendibles cuando la entrada no coincide con el caso ideal.

Un patrón React pequeño y medible

Para que el componente no dependa de muchos efectos, valida en el evento que corresponde y mide dos momentos: cuándo empieza la interacción y cuándo el usuario recibe una respuesta útil. Es facil instrumentar esos puntos con una función local:

const startedAt = performance.now();
setStatus("sending");

try {
  await submitForm(data);
  reportMetric("form_response_time", performance.now() - startedAt);
  setStatus("success");
} catch (error) {
  reportMetric("form_error_time", performance.now() - startedAt);
  setStatus("error");
  throw error;
}

No hace falta enviar el contenido del email ni datos personales para aprender algo útil. Basta con registrar el tipo de resultado, la duración y, si aplica, el paso donde ocurrió el error. Así puedes comparar una optimización de CSS, una validación en el cliente o un cambio de endpoint sin convertir el formulario en una caja negra.

Una buena métrica no es solamente el tiempo total. Observa también cuántos usuarios vuelven a pulsar el botón, cuántos corrigen el mismo campo y cuánto tarda en aparecer un mensaje comprensible. Cuando esas señales mejoran, la experiencia mejora aunque el backend mantenga la misma latencia.

Accesibilidad y rendimiento en la misma revisión

El rendimiento percibido depende de la claridad. Un skeleton que cambia de tamaño, un botón que desaparece y un error que aparece lejos del foco hacen que una respuesta rápida se sienta peor. Por eso, la revisión debe incluir teclado, lector de pantalla y una conexión más lenta.

Comprueba que el foco sea visible en todos los estados, que el contraste no dependa solo del color y que el botón conserve un nombre útil. En CSS, evita animar propiedades que obliguen al navegador a recalcular demasiado trabajo. Transiciones cortas de opacity o transform suelen ser más seguras que mover grandes bloques de contenido.

También prueba la navegación con Tab después de un error. Si los estados se vuelve difíciles de seguir, probablemente el componente mezcla demasiadas responsabilidades. Extraer FieldError, SubmitButton y FormStatus puede mejorar la lectura sin introducir una abstracción enorme.

Checklist antes de enviar el formulario

¿El usuario sabe si el formulario está listo, enviando, correcto o falló?
¿El foco llega al lugar correcto despues de un error?
¿El mensaje de éxito se anuncia sin interrumpir toda la página?
¿El contenido mantiene su posición cuando aparece una validación?
¿El flujo funciona sin ratón y con zoom del navegador?
¿Mides el tiempo hasta una respuesta útil, no solo el tiempo de red?
¿Puedes depurar el intento con un identificador sin guardar datos privados?

Los formularios ágiles no son los que esconden toda espera. Son los que convierten la espera en una señal clara, accesible y estable. Ese enfoque tambien ayuda a probar integraciones: un contrato de fallos para emails de prueba puede complementar las comprobaciones del frontend, y validar correos después de rotar secretos recuerda que la ruta de entrega también necesita estados observables.

La próxima vez que un formulario parezca lento, mira primero qué está comunicando. A veces la mejora más rapida no es reducir una llamada, sino hacer que cada paso tenga un significado visible.

React accesible: menos espera en formularios

Silviu Technology — Sun, 08 Nov 2026 08:23:43 +0000

Un formulario puede ser técnicamente rápido y aun así sentirse lento. El caso típico: la persona pulsa «Crear cuenta», el botón cambia apenas de color y durante dos segundos no ocurre nada visible. En ese hueco, puede pulsar otra vez, cambiar de ventana o pensar que el sitio se rompió.

En interfaces React suelo tratar la espera como parte del diseño, no como un detalle posterior de rendimiento. El objetivo no es ocultar cada milisegundo, sino hacer que el estado actual sea comprensible para una persona que usa ratón, teclado o lector de pantalla. Esta misma idea ayuda a mantener limpias las pruebas de correo: un estado claro de «verificando» es más fácil de asociar con un evento que un spinner sin contexto.

El problema no es solo la velocidad

Un formulario tiene varios estados que se mezclan con facilidad:

listo para enviar;
validando datos locales;
enviando la petición;
esperando una confirmación;
completado;
error recuperable.

Si todos se representan con el mismo botón gris, la interfaz obliga a adivinar. Además, un doble clic puede disparar dos peticiones, y un error de red puede borrar los datos que la persona ya escribió. En flujos con email, conviene separar «la petición salió» de «el mensaje fue recibido». Revisar cohortes de activación por email también resulta más útil cuando cada paso del flujo tiene una señal reconocible.

Diseñar estados que se puedan percibir

Primero, define una máquina de estados pequeña. No hace falta una librería para ello:

type Status = "idle" | "checking" | "sending" | "success" | "error";

La diferencia entre checking y sending importa. La validación local puede terminar en unos milisegundos, mientras que la petición remota depende de la red. Mostrar mensajes distintos evita que una persona crea que el botón no funcionó.

Un componente mínimo puede anunciar el cambio sin mover el foco de forma brusca:

function SubmitStatus({ status, message }: {
  status: Status;
  message: string;
}) {
  return (
    <p role="status" aria-live="polite">
      {status === "sending" ? "Guardando tus datos…" : message}
    </p>
  );
}

role="status" ofrece una región viva adecuada para mensajes que no son una alerta crítica. El texto debe describir la acción, no la implementación: «Comprobando tu correo» ayuda más que «loading=true». Para un lector de pantalla, esta diferencia es bastante importante.

También desactiva el envío mientras la petición está activa, pero no desactives todo el formulario sin motivo. Si la contraseña contiene un error, la persona debe poder corregirla. Cuando el envío termina, conserva los valores y coloca el foco en el resumen del error o en el mensaje de éxito, según el caso.

Un patrón sencillo en React

El handler puede protegerse contra dobles envíos y limpiar el estado en un orden predecible:

async function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
  event.preventDefault();
  if (status === "checking" || status === "sending") return;

  setStatus("checking");
  const validation = validate(values);
  if (!validation.ok) {
    setError(validation.message);
    setStatus("error");
    return;
  }

  setStatus("sending");
  try {
    await save(values);
    setStatus("success");
  } catch {
    setError("No se pudo guardar. Revisa tu conexión e inténtalo de nuevo.");
    setStatus("error");
  }
}

En producción, añade una cancelación o un identificador de petición si el componente puede desmontarse mientras espera. Así no intentas actualizar un componente que ya no existe. Para procesos de email, conviene guardar también un identificador de ejecución; una dirección de correo desechable puede servir como dato controlado de prueba, pero no reemplaza la separación entre estados.

Si el flujo reenvía un mensaje, la protección contra dobles envíos debe cubrir tanto el botón como la acción de teclado. El artículo sobre cómo evitar dobles envíos en React muestra por qué una bandera visual aislada no siempre basta: la regla debe vivir en la acción que inicia la petición.

Teclado, lectores de pantalla y foco

Un diseño accesible no consiste solo en añadir aria-label. Comprueba el recorrido real:

Entra al formulario con Tab.
Envía datos inválidos sin usar el ratón.
Verifica que el error esté asociado al campo con aria-describedby.
Envía datos válidos y escucha el anuncio del estado.
Simula una respuesta lenta y comprueba que el foco no desaparezca.

Evita reemplazar todo el formulario al mostrar el resultado. Ese cambio puede hacer que el foco vuelva al principio de la página, y la persona se queda un poco perdida. Un resumen persistente, un borde de error además del color y un mensaje corto suelen ser suficientes.

Para probar el recorrido, no necesitas crear un entorno enorme. Un caso con un tempail controlado puede comprobar el estado de espera, pero usa datos que no contengan información personal y elimina los artefactos después. La métrica útil no es solo «la petición respondió», sino cuánto tardó el usuario en recibir una señal clara.

Medir la espera que importa

Mide por separado tres tiempos: interacción hasta feedback, feedback hasta respuesta y respuesta hasta confirmación visual. El primero suele explicar por qué una interfaz se percibe lenta aunque el backend sea veloz. Un mensaje de estado que aparece inmediatamente puede mejorar la confianza, pero no debe convertirse en una animación permanente.

Registra estos tiempos en desarrollo o en una herramienta de observabilidad, sin incluir valores sensibles. Si el formulario pide confirmación por correo, no confundas «correo enviado» con «usuario activado». Separar ambas métricas evita conclusiones raras al revisar un embudo.

Checklist antes de publicar

¿Cada estado tiene texto comprensible y no solo un cambio de color?
¿El botón impide peticiones duplicadas durante el envío?
¿Los errores están asociados a sus campos?
¿aria-live anuncia cambios sin interrumpir demasiado?
¿El foco sigue una ruta lógica después de éxito y error?
¿La respuesta lenta puede probarse sin depender de un servicio externo?
¿Se distinguen entrega, confirmación y activación en las métricas?

Una interfaz React bien pulida no hace que la red sea más rápida. Hace que la espera sea legible, que el teclado no pierda su lugar y que un fallo tenga una salida clara. Esa combinación de rendimiento percibido y Accesibilidad es pequeña en código, pero se nota mucho en el uso diario.