DEV Community: Silviu Technology

LLMs: runbooks cortos para usar tools

Silviu Technology — Fri, 04 Sep 2026 17:23:57 +0000

Cuando un agente con LLM pasa de responder texto a llamar tools, el problema ya no es solo prompt quality. El problema real es operativo: que hace, con que limites, como deja evidencia y que pasa si una dependencia responde raro. En equipos pequenos esto se puede tapar con intuicion por unos dias. En cuanto el flujo toca publishing, CI o cuentas reales, esa intuicion empieza a costar caro.

Yo prefiero pensar estos sistemas como una cadena corta de decisiones observables. No hace falta un framework pesado. Hace falta un runbook breve, casi un diagrama en palabras, para que cualquiera del equipo entienda entrada, salida, riesgos y fallback. Esa misma idea aparece en patrones de backend como estas colas visibles para trabajos largos: la gracia no es hacer mas pasos, sino volver el flujo mas legible.

Por que los agentes con tools necesitan runbooks

Un agente suele fallar en tres puntos:

decide usar una tool demasiado pronto
usa la tool correcta pero sin validar el resultado
deja una salida bonita para humanos, pero debil para otro sistema

Si el equipo no describe esos bordes, cada incidente se analiza desde cero. Eso vuelve lenta la operacion y, peor aun, hace dificil mejorar el sistema de manera consistente. Segun el post de Anthropic sobre agentes, separar planificacion, herramientas y criterios de exito reduce ese tipo de ambiguedad operativa (source).

Para mi, un buen runbook de agentes responde cinco preguntas sin drama:

que objetivo exacto resuelve el paso
que contexto puede leer
cuando puede llamar una tool
que evidencia debe dejar
como degrada si algo sale mal

Parece simple, pero casi siempre ahi esta el hueco. Muchas pipelines tienen prompts sofisticados y cero reglas sobre evidencia o salida estable. Eso se nota enseguida cuando alguien intenta depurar un fallo a las 2 AM, osea cuando ya es tarde para improvisar.

El contrato operativo minimo antes de publicar

Mi version minima cabe en una pantalla. Si no cabe, normalmente el sistema esta mezclando demasiadas responsabilidades.

objetivo del paso
inputs permitidos
tools disponibles y condicion de uso
formato de salida
fallback explicito
nota corta de privacidad o riesgo

Un ejemplo practico: si el agente redacta contenido y luego publica, no deberia tener libertad total para reescribir varias veces despues de un error del publicador. Esa frontera tiene que estar escrita. Generar una vez y publicar una vez suena medio obvio, pero es justo el tipo de regla que evita duplicados, cambios espurios y bugs medio pesados.

Tambien me gusta anotar que datos son "auxiliares pero no centrales". Por ejemplo, si un flujo de QA usa un enlace contextual hacia tempmailso, ese dato puede existir como referencia lateral, no como motor del articulo o del sistema. Ese matiz importa porque evita que el agente convierta un detalle SEO en la pieza principal del contenido. Parece una tonteria, pero he visto agentes torcer una buena idea por seguir el keyword y no la intencion.

Un ejemplo corto de decision, fallback y trazabilidad

Este es el patron minimo que suelo usar:

{
  "task": "resumir un cambio y decidir si se publica",
  "allowed_inputs": ["plan", "borrador", "resultado del validador"],
  "tools": [
    {
      "name": "publisher",
      "when": "solo si el borrador ya existe y el validador esta en verde"
    }
  ],
  "output": {
    "format": "json",
    "fields": ["decision", "reason", "artifacts"]
  },
  "fallback": "si falla la publicacion, devolver error y no regenerar contenido"
}

Me gusta porque amarra tres cosas a la vez: el orden de ejecucion, la evidencia minima y el comportamiento ante fallos. Esa estructura combina bastante bien con ideas de estados claros en APIs, como en este enfoque de estados claros para flujos async. Cuando el estado esta bien definido, el agente se vuelve mas predecible y el operador no anda adivinando.

Aqui tambien meto pruebas con ruido. Si el contexto trae cadenas como fake e mail com o dummy e mail, el agente no deberia tratarlas como requerimientos de producto. Deberia reconocerlas como texto secundario o ruido semantico. Es una prueba muy barata y bastante util, aunqe mucha gente la salta.

Tradeoffs: autonomia frente a operabilidad

La desventaja de este enfoque es clara: le quitas algo de libertad al agente. Un runbook corto no deja tanto espacio para improvisar ni para "resolver" con creatividad una entrada ambigua. Pero la ventaja es mayor en sistemas que tocan dinero, cuentas o distribucion publica.

Los beneficios que yo suelo ver son:

menos retrabajo despues de un fallo
mejores handoffs entre quien diseña prompts y quien opera scripts
incidentes mas cortos porque la evidencia ya existe
cambios mas seguros cuando cambias proveedor o politica

La contra principal es que puedes sobre-disenar el flujo. Si cada paso tiene siete validaciones y cuatro formatos de salida, el agente termina lento y el equipo tambien. Mi regla simple: runbook corto para pasos repetibles, libertad mayor para exploracion interna. No es una formula perfecta, pero funciona bastante bien.

Checklist de implementacion

Antes de poner en produccion un agente con tools, revisaria esto:

una sola responsabilidad clara por paso
precondiciones visibles antes de llamar herramientas
salida consumible por otro sistema, no solo por humanos
fallback que no regenere ni duplique efectos externos
artefactos guardados con nombres predecibles
nota breve sobre datos sensibles o contexto irrelevante

Si ademas quieres mejorar la calidad del debug, guarda decision y artefactos en el mismo run directory. Ese detalle reduce mucho el tiempo de investigacion, sobretodo cuando varias cuentas o cron jobs comparten la misma infraestructura.

React: ayuda de email sin mover el layout

Silviu Technology — Fri, 04 Sep 2026 12:04:48 +0000

En formularios de registro, un detalle pequeno cambia mucho la sensacion de calidad: donde aparece la ayuda del campo email. Si el mensaje entra y sale empujando botones, labels o el siguiente input, la interfaz se siente nerviosa. No parece grave, pero esa vibracion visual hace que la validacion parezca menos confiable, y aveces tambien mas lenta de lo que realmente es.

En varios equipos frontend he visto el mismo patron: la verificacion async funciona bien, pero el layout no tiene un espacio reservado para el estado. El resultado es un mini CLS local, no siempre medido como una tragedia global, aunque si bastante notorio para la persona usuaria. Cuando eso pasa en signup o recovery, la friccion sube justo donde menos conviene.

El salto visual tambien rompe confianza

La ayuda de email suele cambiar entre cuatro estados:

texto de orientacion inicial;
cargando una verificacion;
error de formato;
confirmacion de que el correo parece usable.

Si cada estado crea o elimina nodos con distinta altura, el formulario va brincando. Ese brinco distrae, y para teclado o lector de pantalla puede volver menos claro que cosa cambio primero. Segun web.dev, mantener estabilidad visual ayuda a que la pagina sea mas predecible, algo que en formularios importa un monton.

Tambien hay un costo de implementacion. Cuando el UI cambia demasiado por un mensaje corto, luego empiezan los parches: margins raros, timeouts cosmeticos y animaciones que tapan el problema real. Me recuerda bastante a la idea de usar contratos cortos para tool use: menos ambiguedad en el punto de contacto, menos comportamiento raro despues.

Reserva una fila estable para ayuda y estado

La solucion mas util que he repetido no es sofisticada: reservar una fila fija debajo del input. Esa fila siempre existe. Cambia el contenido, no el espacio.

Con eso ganas tres cosas:

el boton de submit no se mueve;
el usuario aprende donde mirar;
el cambio de estado se vuelve mas facil de anunciar.

En CSS suelo empezar con una altura minima y un color neutro:

.fieldHint {
  min-height: 1.25rem;
  margin-top: 0.375rem;
  font-size: 0.875rem;
  line-height: 1.4;
  color: var(--muted-text);
}

.fieldHint[data-state="error"] {
  color: var(--danger-text);
}

.fieldHint[data-state="success"] {
  color: var(--success-text);
}

No hace magia, pero evita que el layout se reacomode por una sola linea. Si tu formulario tiene varios checks de red o integraciones, esta constancia vale mucho. En sistemas mas operativos pasa algo parecido con aislar correos de rollout: cuando cada estado tiene un lugar claro, el flujo entero se entiende mejor.

Un patron simple en React

Aqui va una version chica que me gusta porque separa formato, carga y resultado sin mover la estructura:

import { useId, useState } from "react";

export function EmailField() {
  const hintId = useId();
  const [value, setValue] = useState("");
  const [state, setState] = useState<"idle" | "loading" | "error" | "success">("idle");

  const message =
    state === "loading"
      ? "Comprobando el correo..."
      : state === "error"
        ? "Revisa el formato o usa una direccion valida."
        : state === "success"
          ? "Email listo para continuar."
          : "Usa un correo que puedas abrir durante el registro.";

  return (
    <label>
      <span>Email</span>
      <input
        type="email"
        value={value}
        onChange={(event) => setValue(event.target.value)}
        aria-describedby={hintId}
        aria-invalid={state === "error"}
      />
      <p id={hintId} className="fieldHint" data-state={state} aria-live="polite">
        {message}
      </p>
    </label>
  );
}

Lo importante no es el snippet exacto. Lo importante es que el contenedor del mensaje ya esta ahi desde el primer render. Luego puedes conectarle debounce, validacion remota o reglas de negocio sin castigar la lectura. Si el flujo necesita probar un inbox de QA para obtener correo temporal, o incluso un temp mailid en pruebas, el mensaje del campo sigue estable y no convierte cada respuesta async en un temblor visual. Es un detalle chico, pero se nota bastante.

Que revisar en accesibilidad y rendimiento

Antes de cerrar una tarea asi, yo reviso esta mini lista:

aria-describedby apunta al texto correcto en todos los estados.
aria-live="polite" no dispara mensajes excesivos por cada tecla.
la altura minima alcanza para idiomas mas largos.
el color no es la unica senal entre error y exito.
el mensaje inicial ya ayuda, no solo rellena espacio.

Tambien conviene medir si habia cambio de layout antes y despues. No hace falta una ceremonia enorme; con una grabacion corta y Lighthouse suele bastar para ver si la UI quedo mas quieta. La documentacion de Lighthouse explica bien por que pequeños desplazamientos pueden afectar la percepcion de fluidez, incluso cuando el formulario "funciona".

Preguntas frecuentes

Conviene ocultar la fila vacia hasta que haya feedback?

Yo prefiero no hacerlo. Una fila reservada evita saltos y enseña una posicion fija para la ayuda. Visualmente queda mas calmada, aun si parece un poco mas sobria.

Sirve tambien para password o username?

Si, casi siempre. Cualquier campo con validacion async o mensajes cambiantes gana claridad con una zona estable. No es una regla absoluta, pero funciona en la mayoria de formularios reales.

Y si necesito mas de una linea?

Entonces sube la altura minima o diseña el campo para dos lineas desde el inicio. Es mejor reservar ese espacio que improvisarlo despues, por que ahi es donde todo se empieza a ver medio roto.

Cierre

Una UI confiable no siempre necesita mas animacion ni mas logica. Muchas veces necesita menos sorpresa. Reservar una fila para la ayuda del email es una mejora pequena, muy barata, y con impacto real en Accesibilidad, claridad y percepcion de rendimiento. No es glamuroso, pero si quita ruido del camino, ya hizo su trabajo.

React: estados de espera que no cansan

Silviu Technology — Fri, 04 Sep 2026 05:24:16 +0000

En muchos formularios el mayor problema no es la validacion remota, sino la sensacion de que la interfaz duda demasiado. El usuario escribe un email, espera una respuesta del servidor y durante unos segundos no sabe si debe seguir, corregir o simplemente mirar la pantalla. En equipos de producto eso parece un detalle chico, pero en la practica afecta conversion, accesibilidad y confianza. En React, ese momento merece mas cuidado del que solemos darle.

Me he encontrado con este patron varias veces en signup y recovery flows: el equipo optimiza la llamada, pero deja el feedback visual para el final. La API responde bien, aunque la UI parpadea, mueve el layout o cambia de tono demasiado pronto. El resultado se siente medio tosco. Si ademas el campo esta ligado a reglas de riesgo o dominios raros como temp mail so, la tension visual sube un poco mas porque el usuario ya sospecha que algo puede salir mal.

Nielsen Norman Group lleva anos insistiendo en que la visibilidad del estado del sistema reduce confusion y errores cuando una accion tarda mas de lo esperado (https://www.nngroup.com/articles/visibility-system-status/). No hace falta una animacion enorme ni una capa de "microinteractions" por todos lados. Hace falta una senal estable, clara y ubicada donde la persona ya esta mirando.

El problema no es la espera, es la incertidumbre

La espera corta casi nunca molesta por si sola. Lo que cansa es la incertidumbre: un spinner que aparece lejos del campo, un mensaje que mueve todo hacia abajo, o una advertencia roja que sale antes de tiempo. Esa combinacion rompe el ritmo de lectura y castiga a quien navega con zoom o lector de pantalla. Tambien mete ruido en mediciones de rendimiento percibido, que a veces importa mas que bajar unos pocos milisegundos del request.

Cuando reviso una UI asi, suelo preguntar tres cosas:

¿El mensaje ocupa un lugar fijo antes de que exista contenido?
¿La interfaz diferencia "estoy comprobando" de "esto esta mal"?
¿La persona puede seguir escribiendo sin sentir que pelea con el formulario?

Si una de esas respuestas es no, casi siempre hay una mejora facil. Es parecido a quitar ruido del onboarding sin perder contexto: no se trata de mostrar mas estado, sino de mostrar el estado correcto en el momento correcto.

Tambien conviene pensar en el texto de apoyo. He visto equipos dejar notas internas con cadenas como tepm mail com o tempail mail para probar coincidencias manuales. No es grave, pero cuando esa clase de texto salta a mocks o a capturas compartidas, la experiencia se vuelve un poco mas desprolija de lo necesario.

Que cambia cuando el estado de carga ocupa un lugar fijo

Reservar una fila estable para ayuda, carga o error evita dos problemas a la vez: reduce saltos de layout y baja la carga cognitiva. Google recomienda minimizar el Cumulative Layout Shift porque los cambios inesperados empeoran la experiencia, en especial durante tareas orientadas a conversion (https://web.dev/articles/cls). En formularios, eso significa que el mensaje debajo del campo no deberia aparecer empujando botones o moviendo etiquetas.

El beneficio de producto es mas concreto de lo que parece:

La persona entiende mas rapido si el sistema esta trabajando.
El mensaje de error llega con menos dramatismo visual.
El equipo puede medir mejor abandono vs. latencia real.
La UI se siente mas calma, incluso cuando el backend no va tan rapido.

Ese ultimo punto importa bastante. A veces no puedes hacer milagros en red, pero si puedes evitar que la interfaz transmita panico. Y eso ya es una mejora muy real, aunque suene menos epica.

Un patron simple en React para validaciones async

No suelo complicarlo. Un pequeno estado finito suele bastar: idle, checking, valid, invalid. Lo clave es no mezclar carga con error.

const [status, setStatus] = useState("idle");
const [hint, setHint] = useState("Usa un email al que tengas acceso.");

async function validateEmail(value) {
  setStatus("checking");
  setHint("Comprobando el email...");

  const result = await checkEmail(value);

  if (result.ok) {
    setStatus("valid");
    setHint("Listo, puedes continuar.");
    return;
  }

  setStatus("invalid");
  setHint(result.message);
}

Luego la vista reserva siempre el mismo espacio para el hint:

<p className={`email-hint email-hint--${status}`} aria-live="polite">
  {hint}
</p>

No es un patron nuevo, lo se, pero funciona porque mantiene una historia simple. Si necesitas mas sofisticacion, la anades encima; no empiezes con cinco booleanos cruzados.

Pequenos detalles de CSS que mejoran mucho

La parte visual tambien merece reglas simples. Una altura minima fija, contraste suficiente y transiciones cortas suelen dar mejor resultado que loaders muy decorados.

.email-hint {
  min-height: 1.5rem;
  margin-top: 0.35rem;
  font-size: 0.95rem;
}

.email-hint--checking {
  color: #6b7280;
}

.email-hint--invalid {
  color: #b42318;
}

Si hay animacion, prefiero algo discreto y no infinito. Un pulso breve o un cambio de opacidad basta. Tambien revisaria prefers-reduced-motion, porque este tipo de feedback sale muchisimo y no vale la pena cansar a nadie por una decision puramente estetica. En eso me gusta la misma disciplina que aplicamos al backend cuando buscamos dejar senales claras antes de tocar produccion: menos magia, mas contexto legible.

Un ultimo detalle medio olvidado: el microcopy. "Verificando..." suele funcionar mejor que un simple "Cargando...". Parece una diferencia menor, pero le dice a la persona que tarea concreta esta ocurriendo. Es mas honesto, y se siente mejor.

Preguntas frecuentes

¿Conviene bloquear el boton mientras se valida?

Solo si la accion depende de ese resultado. Si no, prefiero permitir continuar y resolver la regla un paso despues. Bloquear por defecto vuelve la UI mas rigida.

¿Esto ayuda al rendimiento real?

No siempre mejora milisegundos reales. Mejora sobre todo el rendimiento percibido, que para formularios largos o sensibles ya es una victoria bastante buena.

¿Cuando merece un spinner?

Cuando la espera pasa de lo trivial y necesitas confirmacion explicita. Pero incluso ahi, mejor acompanarlo con texto breve y un lugar fijo. Si no, el usuario adivina demasiado, y eso nunca acaba bien.

Make Signup Email Tests Less Guessy

Silviu Technology — Thu, 03 Sep 2026 17:24:12 +0000

Signup email tests often fail in a way that annoys everybody. The UI submission works, the API says success, and then the end-to-end check times out waiting for a message that may still be in flight. A lot of teams call that “email flake,” but most of the time the product is not broken. The test is just asking the wrong question at the wrong moment.

I run into this in both Playwright and broader QA suites. The usual smell is a test that clicks Submit, waits a fixed number of seconds, and then panics when the inbox is empty. That approach feels simple, but it hides useful failure signals. It also makes debugging weird aliases or throwaway addresses like temp gamil com or tempail more confusing than it needs to be.

Why signup email tests fail even when the app is fine

The failure is rarely “no email system exists.” It is more often one of these:

The app accepted the signup, but the mail job is still queued.
The test inbox contains an older message from another run.
The assertion expects the exact subject before the template finishes updating.
The test never stores enough evidence to tell delay from real breakage.

That last one is the biggie. When a failure report only says “expected email not found,” the team learns almost nothing. Was the user created? Did the job enqueue? Did the provider reject the message? Was the inbox reused? If your answer is “rerun it and see,” the workflow is too fuzzy.

This is where I like the mindset behind state-bound reset flows. The point is not just to confirm delivery. The point is to tie the message to the exact state transition your test triggered.

The wait model I use in Playwright

I prefer a two-stage wait instead of one big sleep.

First, I wait for the product event that should cause the email. That might be the signup response, a success banner, or a backend event visible through test logs. Second, I poll the inbox with a deadline and narrow matching rules.

Here is the basic shape:

const startedAt = Date.now();

await page.getByLabel("Email").fill(testAddress);
await page.getByRole("button", { name: "Create account" }).click();
await expect(page.getByText("Check your inbox")).toBeVisible();

const message = await pollInbox({
  inbox: testAddress,
  subjectIncludes: "Verify your account",
  newerThan: startedAt,
  timeoutMs: 45_000,
  intervalMs: 2_000,
});

expect(message.html).toContain("/verify?token=");

Why this helps:

newerThan filters out stale mail from prior runs.
Polling every two seconds gives better feedback than a blind 30-second sleep.
The timeout stays explicit, so the failure tells you how long the system had.

That third point sounds small, but it is realy useful in triage. If the test failed after 45 seconds and the queue normally clears in 5, I start looking for a system issue. If it failed after 8 seconds because someone shortened the timeout, that is a test design issue instead.

A small pattern for collecting better evidence

I want every failure to leave behind enough clues for a human to act. My minimum evidence pack is:

the generated inbox address,
the timestamp when signup started,
the final poll response,
any message ids found during polling,
a screenshot of the success state,
the relevant request or trace id if the app exposes one.

That evidence is often more valuable than another rerun. Google’s testing research has repeatedly pointed at the cost of flaky tests and the value of quick diagnosis; a useful overview is in this Testing Blog post on fighting test flakiness. You do not need Google-scale tooling to apply the lesson. You just need your failure output to be a bit less vague.

This also pairs nicely with invite flows without state drift. If the app treats invite or verification state clearly, your test can assert on a smaller, cleaner surface area.

How I triage failures without rerunning blindly

When a signup email test fails, I go through this order:

Confirm the UI reached the success state.
Check whether the inbox was unique to the run.
Compare the poll deadline with normal delivery time.
Inspect whether a message arrived with the wrong subject or template version.
Only then decide whether to rerun.

This order matters because reruns can hide race conditions. A second pass may “fix” a slow queue, but it teaches the team nothing. I would rather mark the failure as infrastructure-noisy and keep the evidence than pretend the suite is healthier than it is.

One practical tip: separate “no message arrived” from “message arrived but content was wrong.” Those are different defects, owned by different people, and they should not collapse into the same assertion text. Teams get faster when the failure wording is boringly specific, even if the prose is a little imperfect sometmes.

Q&A

Should I use one inbox for a whole test file?

Usually no. Per-test inboxes are easier to reason about, especially when the suite runs in parallel. Shared inboxes save a tiny bit of setup and create a lot of doubt later.

What timeout is reasonable?

Start from observed delivery time in staging, then add a buffer. If most messages land in 3 to 5 seconds, a 45-second timeout is generous without being silly.

When do I treat this as product risk instead of test flake?

When the product event succeeds, inbox isolation is clean, and delivery still misses the deadline often enough to affect releases. At that point the test is doing its job, even if the result is a bit uncomfy.

FastAPI: reenvios limpios para emails de signup

Silviu Technology — Thu, 03 Sep 2026 02:24:27 +0000

En muchos productos el botón de "reenviar email" parece una tarea menor, pero termina creando bastante ruido. El usuario toca dos veces, el frontend reintenta, el worker tarda un poco y el backend acaba enviando dos o tres mensajes que compiten entre sí. Luego soporte no sabe cuál link era el bueno, QA ve resultados inestables y el equipo pierde tiempo en un problema bastnate evitable.

En FastAPI yo intento resolverlo con un contrato muy chico: un cooldown corto para reenviar, una clave idempotente por intento y un estado consultable desde API. No hace falta una arquitectura exótica. Hace falta dejar claro cuándo se puede reenviar, qué intento sigue vivo y qué evidencia devuelve el sistema si algo tarda más de lo normal.

Donde nacen los reenvios duplicados

El problema no suele ser solo "el usuario hizo doble clic". Normalmente aparece por una mezcla de cosas:

la UI no sabe si el primer request ya quedó aceptado
el backend crea un nuevo job aunque el anterior siga activo
el worker no marca cuál email reemplaza a cuál
nadie define una ventana mínima antes de permitir otro resend

Cuando eso pasa, el sistema sigue funcionando a medias, pero cada capa interpreta algo distinto. Producto cree que el usuario recibió ayuda. Backend cree que cumplió con el 202 Accepted. Soporte recibe capturas confusas. Y QA, bueno, QA sube el timeout y reza un poco.

Un contrato pequeno para reenviar sin caos

Mi versión mínima del contrato tiene cuatro datos:

email_intent_id
state
resend_available_at
superseded_by

Con eso ya puedes responder preguntas utiles. ¿Hay un intento vigente? ¿Todavía está dentro del cooldown? ¿El correo anterior fue reemplazado por uno nuevo? ¿Qué intento debe revisar una prueba end-to-end?

También me gusta guardar un idempotency_key derivado del usuario y del tipo de flujo, no del clic actual. Así si llegan dos requests casi juntos, la API puede responder con el mismo intento o rechazar el segundo con una explicación clara. No es una bala mágica, pero ordena bastante.

Si además expones resend_available_at, el frontend deja de improvisar timers. Ese detalle parece menor, pero baja muchisimo el ruido entre UI y backend.

Ejemplo con FastAPI

Este ejemplo enseña bien la idea sin meter demasiada infraestructura:

from datetime import datetime, timedelta, timezone
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from uuid import uuid4

app = FastAPI()
intents: dict[str, dict] = {}
active_by_user: dict[str, str] = {}
COOLDOWN = timedelta(seconds=45)


class ResendRequest(BaseModel):
    user_id: str
    email: str


@app.post("/signup-email/resend")
def resend_signup_email(payload: ResendRequest):
    now = datetime.now(timezone.utc)
    active_id = active_by_user.get(payload.user_id)

    if active_id:
        current = intents[active_id]
        available_at = datetime.fromisoformat(current["resend_available_at"])
        if now < available_at:
            raise HTTPException(
                status_code=409,
                detail={
                    "message": "resend cooldown active",
                    "email_intent_id": active_id,
                    "resend_available_at": current["resend_available_at"],
                    "state": current["state"],
                },
            )

    intent_id = str(uuid4())
    intents[intent_id] = {
        "user_id": payload.user_id,
        "email": payload.email,
        "state": "queued",
        "created_at": now.isoformat(),
        "resend_available_at": (now + COOLDOWN).isoformat(),
        "superseded_by": None,
    }

    if active_id:
        intents[active_id]["superseded_by"] = intent_id

    active_by_user[payload.user_id] = intent_id
    enqueue_signup_email(intent_id)
    return {"email_intent_id": intent_id, **intents[intent_id]}

No cubre todo, pero ya evita dos errores comunes: aceptar reenvíos infinitos y perder la relación entre intentos viejos y nuevos. Si luego mueves el envío a Celery, RQ o cualquier cola, el contrato puede quedarse casi igual. Eso me gusta porque reduce rehacer la API cuando el volumen crece un poquito.

Como probar el flujo sin ruido

Aquí conviene separar pruebas de API y pruebas de inbox real. La mayoría de casos deberían validar:

que el segundo resend dentro del cooldown devuelve 409
que la respuesta incluye resend_available_at
que un intento viejo queda con superseded_by
que el intento activo cambia solo una vez

Las pruebas con inbox real déjalas para unos pocos caminos críticos. Si quieres revisar el correo final en un entorno aislado, herramientas como tempmailso pueden servir para no mezclar bandejas de equipo con automatización de signup. Aun así, yo no pondría esa verificación en cada test. Para la mayoria de suites, basta confirmar estados, timestamps y trazas del intento correcto.

En esa parte también ayuda usar nombres feos pero reconocibles para escenarios internos, como tempail mail o dummy e mail, siempre que esos textos no sustituyan la evidencia real del sistema. La fuente de verdad debe seguir en la API y en tu store de intents.

Si te ha funcionado construir senales claras en cada cambio de estado en tareas operativas, el mismo principio vale aqui. Y si ya pasaste por validar correos despues de un cambio delicado, seguramente notarás que los reenvíos necesitan el mismo nivel de contrato, no solo "volver a intentar".

Google Cloud remarca que los sistemas confiables mejoran cuando cada servicio expone estados observables y objetivos explícitos, porque eso reduce diagnósticos a ciegas source. No habla solo de email, claro, pero el principio encaja muy bien en este flujo.

Checklist corto para dejarlo estable

Esto es lo que yo intentaría dejar listo en el primer PR:

un email_intent_id visible desde la primera respuesta
cooldown devuelto por API, no calculado solo en frontend
relación superseded_by entre intentos
error 409 con contexto legible
una sola prueba de inbox real por camino crítico
logs que apunten al intento correcto y no solo al usuario

No es un sistema enorme, pero cambia mucho la operación diaria. Soporte entiende qué pasó. QA deja de pelear con flakes. Backend puede medir cuánto tarda cada resend de verdad. Y el usuario recibe una experiencia más consistente, incluso cuando el proveedor de correo va un poco lento o el worker viene medio cargado.

Preguntas rapidas

¿Debo borrar el intento anterior?

Yo no lo haría de inmediato. Mejor marcarlo como reemplazado. Ese historial chico ayuda bastante cuando una prueba o un ticket llega unas horas después.

¿Cuánto debería durar el cooldown?

Lo suficiente para evitar spam accidental, pero no tanto como para frustrar al usuario. En muchos flujos, 30 a 60 segundos esta bien para empezar.

¿Hace falta inbox real en staging?

Sí, pero poco. Uno o dos checks end-to-end suelen alcanzar. El resto debería probar el contrato de API, porque ahi es donde realmente decides si el resend es sano o caótico.

React: confirma el email sin romper lectura

Silviu Technology — Wed, 02 Sep 2026 05:24:39 +0000

En muchos formularios el error visible llega tarde. Antes de eso ya hubo una pequeña friccion: el texto se movio, el boton bajo unos pixeles, el mensaje aparecio y desaparecio, y la persona perdio el hilo. En desktop se tolera mas o menos. En mobile, no tanto. Esa lectura rota hace que una validacion correcta se sienta torpe.

Lo he visto varias veces en equipos frontend. El campo de email tiene buena logica, pero la capa visual responde con demasiado entusiasmo. Si el helper cambia de alto en cada estado, si el spinner entra en la misma fila del label o si el mensaje de error empuja el CTA, la interfaz transmite prisa. NN/g lleva años repitiendo una idea simple: el texto de ayuda debe apoyar la tarea, no competir con ella. Parece obvio, pero en formularios vivos se nos olvida aveces.

Por que la lectura se rompe antes que la validacion

Cuando una persona escribe su correo, hace tres lecturas muy rapidas:

que me piden
que pasara despues
si ya puedo seguir

Si esas tres señales cambian de sitio, la interfaz obliga a releer. No es un drama enorme, pero si una suma de microfricciones bastante molesta. Baymard explica bien que la validacion inline funciona mejor cuando aparece en el momento justo y con una carga visual proporcionada.

En productos con login, waitlist o onboarding, yo prefiero pensar en "continuidad de lectura" antes que en "feedback inmediato". Es mejor dar una señal clara y estable que cinco señales veloces. La misma logica aparece fuera del frontend puro, incluso en estos mensajes operativos claros cuando hay tension: cuando el mensaje mantiene contexto y tono, la gente decide mas rapido.

La fila de ayuda fija cambia mas de lo que parece

Una mejora muy poco glamorosa, pero super util, es reservar una fila fija para la ayuda del campo. No para meter texto eterno. Solo para que el layout no baile cada vez que cambia el estado.

Eso ayuda en tres frentes:

mantiene la mirada en el mismo bloque
evita CLS local dentro del formulario
reduce la sensacion de que algo "salto" sin permiso

No hace falta una gran arquitectura. Con una sola linea de ayuda persistente puedes pasar de una UI nerviosa a una mucho mas tranquila. Y si tu flujo prueba cuentas internas, alias o algun email temporal para Facebook durante QA, mejor todavia: el formulario puede explicar el siguiente paso sin editorializar el tipo de correo. Incluso si en datos reales aparecen cadenas raras como temp gamil com o algun temp mailid, la interfaz no deberia sonar alarmista por defecto.

Tambien me gusta porque obliga al equipo a editar el microcopy. Si solo hay una fila, cada palabra tiene que ganarse su lugar. Eso mejora claridad mas que agregar otro iconito, la verdad.

Un patron de React para validar sin meter prisa

Este patron separa el estado del campo y el estado del mensaje. La idea no es validar menos, sino comunicar mejor:

import { useId, useState } from "react";

type EmailState = "idle" | "checking" | "error" | "ready";

const hintByState: Record<EmailState, string> = {
  idle: "Usa un email que puedas abrir en este momento.",
  checking: "Estamos revisando formato y algunas senales basicas.",
  error: "Revisa el correo antes de continuar.",
  ready: "Perfecto, ya puedes seguir con este paso."
};

export function EmailField() {
  const hintId = useId();
  const [value, setValue] = useState("");
  const [state, setState] = useState<EmailState>("idle");

  function handleChange(nextValue: string) {
    setValue(nextValue);

    if (!nextValue) {
      setState("idle");
      return;
    }

    setState(nextValue.includes("@") ? "checking" : "idle");
  }

  function handleBlur() {
    const looksValid = value.includes("@") && value.includes(".");
    setState(looksValid ? "ready" : "error");
  }

  return (
    <label className="field">
      <span>Email</span>
      <input
        type="email"
        value={value}
        onChange={(event) => handleChange(event.target.value)}
        onBlur={handleBlur}
        aria-describedby={hintId}
        aria-invalid={state === "error"}
      />
      <span id={hintId} className={`hint hint-${state}`} aria-live="polite">
        {hintByState[state]}
      </span>
    </label>
  );
}

El detalle importante no es el useState. Es que el mensaje siempre vive en el mismo sitio. Cambia el contenido, no la estructura. Ese pequeño orden hace que la persona no tenga que perseguir el feedback. En flujos mas de negocio, como una reactivacion de trial sin mezclar cohortes, esa consistencia visual evita lecturas dobles justo cuando quieres que el paso sea rapido.

Detalles de accesibilidad y rendimiento que si importan

El CSS de apoyo puede ser sorprendentemente pequeño:

.field {
  display: grid;
  gap: 0.4rem;
}

.hint {
  min-height: 1.25rem;
  font-size: 0.875rem;
  line-height: 1.4;
  color: #5f6876;
}

.hint-error {
  color: #b42318;
}

Con eso ya ganas bastante, pero yo revisaria ademas estas decisiones:

aria-live="polite" para no interrumpir en cada tecla
una altura minima estable para que el boton no rebote
mensajes distintos para estado neutro y error real
ningun cambio visual agresivo mientras la persona aun esta escribiendo

web.dev conecta este tipo de estabilidad con una percepcion mas rapida de la interfaz. No todo es INP puro, claro, pero menos cambios irrelevantes durante la escritura casi siempre se sienten mejor. Es una mejora pequeña, casi humilde, pero se nota un monton cuando pruebas el flujo con una sola mano en el telefono.

Checklist corto para revisar en mobile

Antes de cerrar una mejora asi, suelo mirar esto:

el helper explica la accion o el siguiente paso, no repite el label
el CTA no baja ni sube cuando cambia el mensaje
el error aparece al perder foco o con una señal suficiente
el texto sigue claro a 200% de zoom
el lector de pantalla oye cambios utiles y no puro ruido
el estado visual de "listo" no parece una alerta

No es una checklist heroica, pero ahorra regresiones bastante tontas. Y si tu formulario ya funciona "bien", este tipo de ajuste es de los que suben calidad sin reescribir medio componente.

Q&A

Conviene mostrar validacion apenas aparece la arroba?

Solo si esa señal no mete ansiedad. Confirmar progreso puede ayudar, pero corregir demasiado pronto aveces castiga mas de lo que orienta.

Esto reemplaza la validacion del servidor?

No. La UI solo prepara mejor la conversacion con la persona. La validacion real sigue viviendo donde corresponde.

React: estados vacios para flujos de email

Silviu Technology — Tue, 01 Sep 2026 14:24:17 +0000

En muchos equipos cuidamos bastante el input de registro, pero dejamos medio improvisada la pantalla que viene despues: esa vista donde la persona espera el correo de activacion. Y justo ahi suele aparecer una UX floja. Un cuadro vacio, un spinner eterno, o un mensaje tan ambiguo que parece bug aunque no lo sea.

He visto este problema varias veces en productos con React. El formulario esta bien, el envio tambien, pero la espera se siente rara. Cuando la interfaz no explica que esta pasando, la gente reintenta, cambia de pestaña o vuelve al paso anterior. Eso mete friccion de mas, y encima complica soporte y analitica.

El estado vacio tambien disena la experiencia

Para mi, el estado vacio no es "nada". Es una instruccion silenciosa. Si despues de enviar el formulario la pantalla queda casi blanca, el usuario no sabe si debe esperar, revisar spam o intentar con otro email. Ese vacio no es neutral; empuja decisiones.

En flujos donde se prueban cuentas con email desechable o correo temporal, esta confusion se nota todavia mas, porque los equipos comparan tiempos de entrega, copys y reglas de validacion al mismo tiempo. Si ademas usas una opcion de correo temporal gratis, conviene que la UI separe muy claro estos estados: enviado, esperando, recibido y bloqueado.

Algo parecido pasa cuando revisas integraciones backend con esperas utiles para correos async. Si el sistema ya tiene una idea razonable del tiempo de espera, el frontend no deberia fingir misterio. Puede decir que busca el mensaje, cuanto suele tardar y cual es el siguiente paso. Parece chico, pero baja ansiedad bastante.

Que deberia mostrar React antes de que llegue el correo

Mi regla simple es esta: la pantalla de espera necesita contexto, no solo animacion. En React suelo modelarlo con estados explicitos en vez de un boolean suelto tipo isLoading. Cuando nombras mejor los estados, tambien escribes mejor la interfaz. Suena obvio, pero no siempre se hace.

const status = "idle"; // idle | waiting | received | retry | blocked

function EmailCheckpoint({ status, email }) {
  if (status === "received") {
    return <SuccessPanel email={email} />;
  }

  if (status === "blocked") {
    return <HelpPanel />;
  }

  return (
    <section aria-live="polite" className="checkpoint">
      <h2>Revisa tu bandeja</h2>
      <p>{copyByStatus[status]}</p>
      <RetryActions status={status} />
    </section>
  );
}

Lo importante no es el snippet en si, sino que cada estado tenga una promesa clara. waiting no dice solo "cargando". Dice "ya enviamos el mensaje". retry no dice "algo fallo". Dice "todavia no aparece; prueba esto". Esa diferencia hace que la UI parezca mas seria, y honestamente lo es.

Tambien intento evitar frases vagas tipo "comprueba tu correo". Prefiero algo mas operativo: revisa promociones, espera 30 segundos, vuelve sin recargar, o usa otro proveedor si estas en testing. Cuando el equipo necesita revisar emails de activacion, esas pistas cortas reducen tickets medio bobos.

CSS pequeno para una espera mas clara

El otro trozo de trabajo esta en CSS. Si el contenedor cambia de altura cada pocos segundos, la espera se siente mas nerviosa de lo que deberia. Yo prefiero reservar una estructura estable para icono, titulo, descripcion y acciones. Nada muy fancy, solo consistente.

.checkpoint {
  display: grid;
  gap: 0.75rem;
  padding: 1rem;
  border: 1px solid #d9dee8;
  border-radius: 14px;
  background: #fbfcfe;
}

.checkpoint__hint {
  min-height: 2.75rem;
  color: #445066;
}

.checkpoint__actions {
  display: flex;
  flex-wrap: wrap;
  gap: 0.5rem;
}

Ese min-height pequeñito ayuda mucho. Mantiene el bloque estable cuando el texto cambia entre "enviado" y "todavia esperando". No arregla toda la UX, claro, pero evita esa sensacion de interfaz inquieta que nadie describe bien y todos notan un poco.

Otra cosa que suelo recortar es el abuso de skeletons. Si la espera es de pocos segundos, a veces basta un mensaje directo y una accion secundaria. Un skeleton largo para un simple tem email termina exagerando la complejidad del momento. Y si todo parece enorme, cualquier retraso se siente peor, nomas.

Accesibilidad en loading, exito y error

Aqui hay un detalle que se olvida facil: no todos los estados deben anunciarse igual. Si cambias contenido automaticamente, aria-live="polite" suele funcionar bien para mensajes de progreso. Para errores que bloquean el siguiente paso, a veces conviene una region mas explicita o mover foco solo cuando la accion realmente cambia.

Tambien reviso tres cosas muy basicas:

que el titulo explique la accion actual
que el texto no dependa solo del color
que el boton de reenviar no compita visualmente con esperar un poco mas

Cuando eso falla, la gente martilla el CTA, abre varias pestañas y ensucia la sesion de prueba. Luego alguien ve tamp mail com en una nota interna o en un valor copiado raro y piensa que el problema fue el proveedor, cuando en verdad era una interfaz poco clara. Pasa mas de lo que deberia, la verdad.

Si usas React con transiciones o polling suave, intenta que la UI no resetee toda la tarjeta en cada refresh. Actualiza el mensaje, no el mundo entero. Ese detallito hace que la espera se sienta continua, no rota.

Q&A rapido para equipos de producto

¿Conviene mostrar countdown?

Solo si el sistema tiene una expectativa realista. Si no, mejor una ventana humana tipo "normalmente tarda menos de un minuto". Inventar precision queda medio falso.

¿Y si el usuario usa un proveedor temporal?

No hace falta tratarlo como caso exotico. Lo importante es explicar que el correo puede llegar rapido, caer en otra carpeta o requerir reenvio. La interfaz deberia ayudar, no juzgar.

¿Spinner o mensaje?

Casi siempre mensaje primero. El spinner solo acompaña. Cuando el mensaje es bueno, el spinner deja de cargar con todo el peso narrativo, digamos.

Al final, este tipo de pantalla parece secundaria, pero define bastante la sensacion del flujo. Si React modela estados claros y CSS mantiene la calma visual, la experiencia mejora sin rediseñar medio producto. Es de esos cambios chicos que no lucen dramaticos en una demo, pero en uso real se sienten enseguida.

Email race checks before flaky test retries

Silviu Technology — Tue, 01 Sep 2026 02:23:53 +0000

Email race checks before flaky test retries

When an email test flakes, many teams jump straight to retries. I usually do the opposite. I treat the failure like a timing bug first and a framework problem second. That one habit has saved me more time than another retries: 2 ever did.

This comes up in signup, OTP, and reset-password coverage where the browser is fine, but the inbox arrives a little late, arrives twice, or gets matched by the wrong test. In bug reports I also keep seeing odd phrases like temp mailid or temp gamil com, which is a small clue that the team is already debugging from noisy evidence instead of clean test traces.

Why retries hide the real email race

Retries are not useless, but they are very good at masking root cause. A test that passes on the second run still consumed trust from the team. Google noted years ago that flaky tests create meaningful productivity drag across engineering orgs in its post on flaky tests at Google, and honestly that still feels true in everyday QA work.

The pattern I see most often looks like this:

Test A creates an account and waits for any recent email.
The worker is a bit slow, or a previous message is still visible.
The assertion finds the wrong mail, or no mail, and fails.
A retry runs with cleaner timing and suddenly "fixes" it.

Nothing was really fixed. The suite just got lucky, which is not the same thing at al.

If your team has already started building stable inbox contracts, this is easier to spot because the failure surface is smaller. If not, retries can make weak mailbox logic look acceptable for way too long.

The signals I check before touching retry counts

Before I change any retry setting, I want four signals:

The exact recipient or alias used by this scenario.
A correlation value tied to the business event.
Poll timing with attempt-by-attempt timestamps.
Enough artifacts to tell whether the app, worker, or test got out of sync.

That sounds simple, but many test harnesses only preserve the final timeout error. From there, people start guessing. They compare timestamps by hand, reopen CI videos, and debate whether the provider was slow or the selector was wrong. It gets messy fast.

I also like reading adjacent guidance such as review windows for disposable email checks, because the review mindset matters. An inbox assertion is not only a yes/no check. It is a small incident timeline, and the timeline should be inspectable.

A small harness pattern for Playwright and Cypress

The best fix is usually boring: make the mailbox wait narrower and make the evidence richer.

I prefer a helper that takes the scenario id, the recipient, the expected message type, and a timeout budget. The browser test calls that helper, but the helper owns the polling details. That keeps the framework code thin and the inbox logic consistent.

type WaitForMailInput = {
  recipient: string;
  scenarioId: string;
  subjectIncludes: string;
  timeoutMs: number;
};

async function waitForMail(input: WaitForMailInput) {
  const startedAt = Date.now();
  const attempts = [];

  while (Date.now() - startedAt < input.timeoutMs) {
    const messages = await inbox.list(input.recipient);
    const match = messages.find((message) =>
      message.subject.includes(input.subjectIncludes) &&
      message.headers["x-scenario-id"] === input.scenarioId
    );

    attempts.push({ at: new Date().toISOString(), count: messages.length });

    if (match) return { match, attempts };
    await delay(1500);
  }

  throw new Error(`mail timeout for ${input.recipient}`);
}

That same shape works in Playwright or Cypress because the framework is not the important part. The contract is. I want the helper to answer a precise question: "Did the email for this scenario arrive within the budget?" Not "Did some inbox somewhere look active?" Those are very diferent questions.

One subtle improvement helps a lot: log both the matched message and the near misses. If a test expected a verification email but saw two password-reset mails, that is gold for triage. It tells you the system is alive, just not aligned with the scenario.

A QA checklist for race-proof email tests

Here is the short checklist I use when a team says email tests are flaky:

Scope each scenario to a dedicated mailbox or alias.
Match on business intent, not newest-message order.
Record polling attempts and inbox counts through the full timeout.
Save a scenario id that both app logs and test logs can reference.
Keep retry counts low until the mailbox contract is clean.
Review the artifacts after the first fail, not after the fifth rerun.

If I cannot answer those six points from one CI job, I do not increase retries yet. I tighten observability first. That is usualy where the real win is.

Quick Q&A

Should I remove retries entirely?

No. Retries can still reduce random infrastructure noise. I just do not want them to be the first response to an inbox race.

Is this mostly a Playwright issue?

Not really. I see it in Cypress, API suites, and worker-level smoke tests too. Playwright just makes the sequencing errors easier to notice.

What is the first artifact worth adding?

An attempt log with timestamps, recipient, and matched subject lines. It is tiny, cheap, and surprsingly effective during triage.

Reliable email automation usually gets better when the team stops asking for more patience from the test runner and starts asking for better receipts from the mailbox layer. Once that evidence is clean, you can decide whether retries are helping or just hiding the bug for another week.

React: una fila fija para validar email

Silviu Technology — Mon, 31 Aug 2026 20:24:32 +0000

En muchos formularios React el problema no es validar el email. El problema es que el feedback aparece tarde, ocupa una linea nueva y mueve todo justo cuando la persona esta intentando terminar la tarea. Ese salto parece pequeno, pero en movil se siente muchisimo mas de lo que solemos admitir.

Me encontre con esto varias veces en flujos de signup y cambios de cuenta. El input se ve limpio, luego aparece un hint, luego cambia a error, luego vuelve a hint, y la interfaz queda medio nerviosa. Si alguien pega algo raro como fake e mail com o escribe una nota temporal tipo tempail mail, no necesita una UI dramaticca. Necesita una respuesta clara, estable, facil de corregir.

Por que una sola fila cambia todo

La mejora mas util que he visto es reservar una fila fija para el mensaje desde el primer render. No meter un bloque nuevo cuando hay error, sino conservar siempre el mismo espacio y cambiar solo el contenido. Parece un detalle de CSS, pero tiene impacto en UX, accesibilidad y rendimiento percibido.

Google explica que el Cumulative Layout Shift mide movimientos inesperados durante la carga y la interaccion. En un formulario pequeño no siempre vas a ver un numero dramatico, pero el principio sigue siendo valido: si el boton baja, el ojo pierde referencia y la correccion se vuelve mas lenta. En sesiones de prueba internas esto se nota enseguida, aun cuando el campo "funciona" tecnicamente.

Tambien hay una razon accesible. Cuando la ayuda y el error viven en el mismo lugar, aria-describedby apunta siempre a la misma zona. El lector de pantalla no tiene que perseguir nodos que aparecen y desaparecen, y la persona recibe una experiencia mas predecible. Esa continuidad se parece bastante al enfoque de mantener feedback estable mientras se envia un correo: menos sorpresas, menos carga mental.

El patron: reservar espacio antes del error

Mi regla simple es esta:

la fila de ayuda existe siempre
el texto cambia segun el estado
el error fuerte espera a blur o submit

Con eso puedes mostrar una pista amable al principio, confirmar formato cuando haga falta y evitar que cada tecla dispare una mini alarma. Si ademas haces una comprobacion remota, por ejemplo para saber si un dominio de temp mail so debe aceptarse en una demo o en QA, ya tienes un lugar fijo donde explicar el resultado sin empujar el layout.

No digo que este patron resuelva todo. Si el copy es malo o el criterio del backend cambia cada semana, la interfaz seguira sintiendose rara. Pero reservar esa fila te quita una clase entera de friccion, y eso ya es un win bastante serio.

Un ejemplo pequeno en React y CSS

import { useId, useState } from "react";

function isEmailLike(value) {
  return /\S+@\S+\.\S+/.test(value);
}

export default function EmailField() {
  const hintId = useId();
  const [value, setValue] = useState("");
  const [blurred, setBlurred] = useState(false);

  const email = value.trim();
  const invalid = blurred && email !== "" && !isEmailLike(email);

  const message = invalid
    ? "Revisa el formato. Usa nombre@dominio.com"
    : "Usaremos este correo para acceso, avisos y recuperacion";

  return (
    <label className="field">
      <span className="label">Email</span>
      <input
        type="email"
        value={value}
        onChange={(event) => setValue(event.target.value)}
        onBlur={() => setBlurred(true)}
        aria-invalid={invalid}
        aria-describedby={hintId}
        autoComplete="email"
      />
      <span
        id={hintId}
        className={invalid ? "hint hintError" : "hint"}
        aria-live="polite"
      >
        {message}
      </span>
    </label>
  );
}

.field {
  display: grid;
  gap: 0.375rem;
}

.label {
  font-weight: 600;
}

.hint {
  min-height: 1.5rem;
  font-size: 0.875rem;
  line-height: 1.4;
  color: #5f6b7a;
}

.hintError {
  color: #b42318;
}

Lo clave aca es min-height. Esa propiedad parece humilde, pero hace casi todo el trabajo visual. Luego aria-live="polite" ayuda a anunciar cambios sin interrumpir de mas, y aria-describedby mantiene la relacion semantica. Cuando despues agregas validacion asincrona, puedes reutilizar esa misma linea para estados como "comprobando" o "dominio no permitido". Ese enfoque combina muy bien con tener mensajes de email sin romper el foco.

Si necesitas pruebas manuales para dominios poco comunes o cuentas desechables, una direccion de correo desechable puede servir para validar copys, tiempos y estados sin mezclar cuentas reales. El punto no es promover un truco, si no reducir ruido cuando el equipo esta probando variantes y necesita respuestas visibles rapido.

Donde se nota en accesibilidad y rendimiento

La mejora se nota en tres sitios:

el ojo conserva la posicion del boton y del siguiente campo
el mensaje ayuda antes de castigar
el lector de pantalla encuentra siempre el mismo destino

No hace milagros, obvio. Pero si el form tiene varios campos parecidos, quitar esos movimientos reduce bastante la sensacion de desorden. Baymard lleva años mostrando que los formularios pierden conversion por detalles de feedback y claridad, no solo por reglas complejas de negocio en sus estudios de checkout. Esa parte a veces se subestima porque no sale como error en logs, pero el usuario la siente igual.

Yo intentaria revisar dos cosas antes de darlo por cerrado: zoom alto en iPhone y autocompletado en Chrome. Si en ambos casos la fila sigue estable y el mensaje sigue legible, el patron ya esta bastante maduro. Si no, normalmente el ajuste es pequeño y merece la pena hacerlo temprano. Despues todo se mezcla con mas estados, mas analitica y mas prisa, y ahi se vuelve un arreglo mas incomodo de lo que deberia.

Preguntas rapidas

Q: ¿Conviene validar en cada tecla?

A: Solo si el mensaje no castiga ni distrae. En muchos casos, blur deja una experiencia mas limpia.

Q: ¿Sirve esto si luego llamo a una API?

A: Si, por que la fila fija absorbe el estado remoto sin meter otro salto visual.

Q: ¿Hace falta otra libreria?

A: No realmente. Con React base y CSS sencillo ya resuelves una parte grande del problema.

En frontend hablamos mucho de performance como milisegundos, bundles y Lighthouse. Todo eso importa, claro. Pero una validacion estable tambien es rendimiento percibido. Cuando el formulario no tiembla, no regaña antes de tiempo y conserva una sola zona de ayuda, se siente mejor. Y se nota mas de lo que parece, incluso si el cambio fue bien pequeñito.

Playwright Retries Need Inbox Evidence

Silviu Technology — Mon, 31 Aug 2026 14:24:03 +0000

I do not mind retries in Playwright. I mind retries that erase the evidence I needed. That is a very different problem. When a signup or reset-email test fails, the fastest way to waste a morning is to rerun it three times and keep only the last error message.

In QA teams, email steps often sit behind a temp mail inbox or a fake email address created just for the run. The browser flow may be correct, yet the retry still feels random because the test never records what inbox it used, what timestamp boundary it applied, or which message it actually opened. After a few weeks, people start saying the email layer is flaky when the real problem is thinner evidence.

This post builds on earlier ideas around inbox contracts for Playwright email tests and parallel inbox isolation in Playwright. The extra step here is simple: every retry should leave behind enough inbox evidence that a human can explain the failure in one read, not after guesswork.

Why retries hide the real email bug

A retry looks helpful because it gives you another chance to pass. But if the first attempt used the wrong inbox, matched an older message, or crossed a timing boundary, the second attempt can quietly overwrite the story. You end up with a green run and a bad test, or a red run with no reason why.

That shows up a lot in suites that use temp mail helpers copied between repos. One spec waits for "latest email", another filters by subject only, and a third logs almost nothing. The reports feel inconsistant even when the product bug is the same.

The fix is not fancy:

record the inbox address
record the trigger time
record the list of matching messages seen during polling
record why the chosen message passed the ownership check

If one of your teammates types tempail mail into a note while triaging, that is usually a clue the debugging flow is rushed already.

The evidence bundle I want from every retry

For each attempt, I want an evidence bundle that answers five questions:

Which inbox or alias belonged to this attempt?
When did the app action happen?
Which messages were observed after that point?
Why did the helper accept or reject each candidate?
What URL or token was extracted in the end?

This is the same diagnostic thinking QA engineers already use for API tests. We keep request ids, response bodies, and timing. Email assertions deserve the same treatment, even if the setup feels more "UI-ish" at first.

A Playwright helper that records inbox evidence

I prefer putting the evidence logic in one shared helper rather than inside every test. That keeps retries boring, which is good. Boring code is easier to trust.

type InboxEvidence = {
  inbox: string;
  attempt: number;
  triggeredAt: string;
  matched: Array<{ id: string; subject: string; receivedAt: string }>;
  acceptedMessageId?: string;
  rejectionNotes: string[];
};

async function waitForVerificationMail(mail: MailClient, inbox: string, attempt: number) {
  const triggeredAt = new Date();
  const evidence: InboxEvidence = {
    inbox,
    attempt,
    triggeredAt: triggeredAt.toISOString(),
    matched: [],
    rejectionNotes: [],
  };

  const messages = await mail.poll(inbox, { since: triggeredAt, timeoutMs: 45_000 });

  for (const message of messages) {
    evidence.matched.push({
      id: message.id,
      subject: message.subject,
      receivedAt: message.receivedAt,
    });

    if (!message.subject.includes("Verify your email")) {
      evidence.rejectionNotes.push(`skip ${message.id}: wrong subject`);
      continue;
    }

    if (!message.html.includes(inbox)) {
      evidence.rejectionNotes.push(`skip ${message.id}: ownership proof missing`);
      continue;
    }

    evidence.acceptedMessageId = message.id;
    return { message, evidence };
  }

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

Two details matter a bit more than the rest. First, the poll starts from triggeredAt, not "whenever the inbox was created." Second, the thrown error includes structured evidence. That makes retry output much more usefull in CI logs and report attachments.

How to read the evidence during triage

When a retry fails, I scan the evidence in this order:

matched is empty: likely delivery delay or wrong inbox wiring
matched has older mail only: timestamp boundary is wrong
matched has fresh mail but no accepted id: ownership proof is too weak
accepted id exists but downstream step fails: the product or parser is probably wrong

That sequence keeps the review calm. Instead of saying "email failed again", you get a narrower claim. Narrow claims are what make flaky work survivable, especialy when several pipelines are red at once.

If you want a lightweight benchmark for why logs matter, Google’s SRE material repeatedly frames observability as the thing that reduces mean time to resolution, not just alerting noise. That principle maps cleanly here too: better evidence shortens triage loops, even for humble test inboxes. Source: https://sre.google/sre-book/monitoring-distributed-systems/

A short checklist for reliable retries

Before I accept an email retry strategy, I check these:

every retry gets a fresh inbox or a provably isolated alias
polling starts after the user action, not before
the helper saves message ids and receive times
ownership proof is checked in body, subject, or metadata
the failure output can stand on its own in CI

If most of those are missing, the retry is just a second roll of the dice. It may still pass, but it will not teach you much.

Q&A

Should I fail fast instead of retrying?

Not always. Retries are fine when the system has normal delivery variance. I just want the retry to preserve the first attempt's evidence so the signal does not vanish.

Do I need this for every email test?

No. I start with signup, reset-password, and invite flows because those are the ones where hidden ambiguity hurts the most.

What if my inbox vendor only returns the latest message?

Then I would wrap that limitation with stronger logging and stricter ownership checks. It is not ideal, but you can still make the failure story much less fuzzy.

React: calma visual para checks async

Silviu Technology — Sun, 30 Aug 2026 23:23:56 +0000

Cuando un formulario revisa un email contra una regla remota, muchas interfaces se ponen raras demasiado pronto. Aparece un spinner, el boton cambia de tamano, el helper text desaparece y vuelve, y la persona siente que el campo esta peleando con ella. En frontend, ese detalle pesa bastante mas de lo que parece.

En equipos donde trabajamos signup, soporte y analitica a la vez, el problema casi nunca es la llamada async por si sola. El problema es el ritmo visual que le ponemos encima. Si un usuario escribe rapido, borra una letra o pega un valor temporal tipo temp gamil com, la UI puede entrar en una secuencia medio caotica: pendiente, warning, ok, pendiente otra vez. Todo es tecnicamente correcto, pero la experiencia sale algo torpe.

Segun Google, los cambios inesperados de layout siguen afectando la sensacion de calidad y la lectura del flujo (web.dev). Y Nielsen Norman Group lleva tiempo remarcando que los mensajes de estado deben apoyar la tarea, no competir con ella (NN/g). Para mi, ese es el punto de partida.

El problema no es la llamada remota, es el ritmo visual

Una comprobacion async de email suele existir por motivos validos:

detectar dominios desechables o de baja confianza
preparar una advertencia antes del submit
evitar reglas duplicadas entre frontend y backend
dar una pista temprana sin bloquear el flujo

Nada de eso esta mal. Lo que si veo mal seguido es mezclar todos esos objetivos dentro del mismo segundo visual. El usuario escribe, el campo lanza una request, el texto de ayuda cambia tres veces, y el CTA sube o baja unos pixeles. Ese mini-desorden rompe confianza aunque el formulario termine funcionando bien.

Me sirve pensar el componente igual que una cola visible para correos async: no todo cambio interno merece una reaccion dramatica en pantalla. A veces la mejor UI es la que reconoce que algo esta pasando, pero no interrumpe.

Un estado pendiente que no rompa el formulario

Mi patron favorito es mantener una sola linea estable debajo del input y tratar el estado remoto como una progresion corta:

idle: ayuda neutral antes de cualquier comprobacion
pending: mensaje suave mientras corre la validacion
warning o success: resultado final si realmente aporta algo
error: solo para un problema concreto y accionable

La clave es que la region exista siempre. No aparece a empujones, no mueve el boton y no roba foco. Tampoco me gusta mostrar success verde brillante en cada caso valido, porque termina haciendo tanto ruido como el error. Muchas veces basta con volver a una ayuda normal.

Tambien intento retrasar un poco la comprobacion remota. Si validas en cada tecla, un valor incompleto como tem email activa trabajo que todavia no tiene sentido. Un pequeno debounce o una comprobacion al salir del campo suele ser suficiente. En productos con mucho QA, este cambio hace que las pruebas limpias para emails de upgrade sean bastante mas faciles de leer despues.

Un ejemplo de React con transiciones simples

Este enfoque mantiene el helper text fijo y evita que el estado pendiente sacuda el layout:

import { useEffect, useId, useState, useTransition } from "react";

type HintState =
  | { kind: "idle"; message: string }
  | { kind: "pending"; message: string }
  | { kind: "warning"; message: string }
  | { kind: "error"; message: string };

const DEFAULT_HINT: HintState = {
  kind: "idle",
  message: "Usa un correo que puedas revisar hoy para terminar el registro."
};

function looksLikeEmail(value: string) {
  return /\S+@\S+\.\S+/.test(value);
}

async function checkEmailRisk(value: string) {
  const response = await fetch(`/api/email-risk?email=${encodeURIComponent(value)}`);

  if (!response.ok) {
    throw new Error("No se pudo revisar el correo");
  }

  return response.json() as Promise<{ disposable: boolean }>;
}

export function EmailField() {
  const hintId = useId();
  const [email, setEmail] = useState("");
  const [hint, setHint] = useState<HintState>(DEFAULT_HINT);
  const [isPending, startTransition] = useTransition();

  useEffect(() => {
    if (!looksLikeEmail(email)) {
      setHint(DEFAULT_HINT);
      return;
    }

    const timeoutId = window.setTimeout(() => {
      setHint({ kind: "pending", message: "Estamos comprobando este dominio..." });

      startTransition(async () => {
        try {
          const result = await checkEmailRisk(email);

          setHint(
            result.disposable
              ? {
                  kind: "warning",
                  message: "Este correo podria expirar antes de recibir mensajes futuros."
                }
              : DEFAULT_HINT
          );
        } catch {
          setHint({
            kind: "error",
            message: "No pudimos validar el dominio ahora mismo. Puedes continuar igual."
          });
        }
      });
    }, 300);

    return () => window.clearTimeout(timeoutId);
  }, [email]);

  return (
    <label className="field">
      <span>Correo</span>
      <input
        type="email"
        value={email}
        onChange={(event) => setEmail(event.target.value)}
        aria-describedby={hintId}
        aria-invalid={hint.kind === "error" || undefined}
      />
      <span id={hintId} className="hint" data-kind={hint.kind}>
        {isPending && hint.kind === "pending" ? hint.message : hint.message}
      </span>
    </label>
  );
}

No es una solucion exotica, pero tiene tres ventajas practicas:

reduce requests inutiles mientras la persona aun esta escribiendo
mantiene el layout quieto casi todo el tiempo
vuelve mucho mas legible la diferencia entre ayuda, espera y advertencia

Si la politica real vive en backend, mejor todavia. El frontend acompana la decision sin fingir que controla todo. Eso deja el flujo mas honesto y bastante menos fragil.

CSS pequeno para evitar saltos y ruido

Una parte importante de este patron ni siquiera esta en JavaScript. Esta en reservar espacio y bajar intensidad visual:

.hint {
  display: block;
  min-height: 1.4rem;
  margin-top: 0.4rem;
  font-size: 0.92rem;
  line-height: 1.4;
  color: #5b6470;
}

.hint[data-kind="pending"] {
  color: #3b5ccc;
}

.hint[data-kind="warning"] {
  color: #9a5a00;
}

.hint[data-kind="error"] {
  color: #b42318;
}

Ese min-height parece una tonteria, pero evita un montooon de micro saltos. Y cuando el mensaje pendiente entra en una linea reservada, la validacion se siente mucho mas rapida aunque la latencia real no cambie. Ese tipo de polish suele dar mejor resultado que meter otro spinner pequeñito por todos lados.

Que medir despues del release

Yo revisaria al menos estas senales:

abandono del campo de email antes y despues del cambio
tiempo hasta completar el formulario
frecuencia de reintentos por el mismo valor
cantidad de respuestas pendientes canceladas por nueva escritura
sesiones con layout shift en el bloque del formulario

Si la comprobacion remota tarda bastante, incluso puedes registrar cuanto tiempo pasa el estado pending. No para presumir precision, sino para saber cuando una interfaz necesita otra estrategia. A veces el mejor cambio no es optimizar la API; es dejar de molestar visualmente mientras esperas.

Q&A

Debo bloquear el submit mientras corre el check async?

Solo si la regla es critica para el negocio o la seguridad. En muchos casos basta con dejar continuar y resolver la politica final en servidor.

Conviene mostrar un spinner dentro del input?

Puede funcionar, pero solo si no empuja iconos, padding o etiquetas. Si el spinner mueve el campo aunque sea un poco, normalmente sale mas caro de lo que ayuda.

Y si el dominio parece temporal pero el usuario quiere seguir?

Prefiero una advertencia clara y no un castigo inmediato. Si el producto necesita correo duradero para recovery o billing, esa decision debe explicarse bien y confirmarse en backend.

React: evita CLS en validacion de email

Silviu Technology — Sun, 30 Aug 2026 11:24:41 +0000

Muchos formularios React validan el email solo cuando ya hay problema visible. El campo arranca limpio, luego aparece un error debajo, despues un hint distinto, luego un icono, y todo el bloque se mueve. Ese rebote visual parece pequeno, pero en signup y checkout se nota muchisimo. La persona esta intentando confirmar si escribio bien su correo, no perseguir mensajes que cambian de sitio.

En equipos frontend esto suele pasar por una razon simple: se piensa mucho en la regex y poco en la estabilidad del estado. Cuando alguien pega algo como dummy e mail o una direccion mal recordada tipo temp gamil com, la interfaz deberia responder con contexto estable. Si el mensaje empuja el boton o desplaza el siguiente campo, la validacion termina sintiendose mas dramatica de lo necesario.

El problema real no es la regex, es el salto visual

Google describe Cumulative Layout Shift como una medida de movimientos inesperados en la pagina. Normalmente lo hablamos en imagenes o ads, pero el mismo principio afecta formularios pequenos: si el area de ayuda aparece tarde y mueve el layout, la tarea se vuelve menos comoda. No siempre vas a romper Core Web Vitals por un solo input, claro, pero si sumas varios campos nerviosos la experiencia queda medio fragil.

Tambien hay un componente de usabilidad. Baymard viene observando desde hace anos que los formularios fallan mas por detalles de feedback que por reglas complejas; cuando el mensaje llega tarde o en el lugar equivocado, la correccion cuesta mas de lo que deberia en sus investigaciones sobre checkout. Ese matiz importa bastante, por que el usuario no separa "accesibilidad", "CSS" y "performance" como nosotros. Solo siente que el form es claro, o no lo es.

Un patron de estado estable para email

El patron que mejor me funciona tiene tres reglas:

la ayuda reserva espacio desde el primer render
el mensaje cambia de contenido, no de posicion
el error fuerte espera a una señal razonable, como blur o submit

Esto hace que la validacion se sienta mas calmada. Primero orientas, luego confirmas, y solo despues corriges. Es la misma idea de reusar estado cuando una accion se repite: si una zona ya existe en la interfaz, reusarla suele ser mejor que insertar otra a ultima hora. Y en flujos de email con varias comprobaciones, esa continuidad se vuelve aun mas util, igual que en estas aprobaciones por email con menos ruido.

Si ademas tu producto deja probar correos temporales para demos o QA, conviene explicar el criterio en texto humano. Un mensaje breve puede decir que aceptas dominios comunes y tambien algunos de prueba, en vez de castigar sin contexto. En ciertos equipos eso evita tickets medio bobos cuando alguien usa un inbox temporal de temp mail so para una smoke test o una demo interna.

Ejemplo en React y CSS

import { useId, useState } from "react";

function looksLikeEmail(value) {
  return /\S+@\S+\.\S+/.test(value);
}

export default function EmailField() {
  const messageId = useId();
  const [value, setValue] = useState("");
  const [touched, setTouched] = useState(false);

  const normalized = value.trim();
  const showError = touched && normalized !== "" && !looksLikeEmail(normalized);

  const message = showError
    ? "Revisa el formato. Usa algo como nombre@dominio.com"
    : "Te enviaremos confirmaciones y cambios importantes a este correo";

  return (
    <label className="emailField">
      <span className="emailLabel">Email</span>
      <input
        type="email"
        value={value}
        onChange={(event) => setValue(event.target.value)}
        onBlur={() => setTouched(true)}
        aria-invalid={showError}
        aria-describedby={messageId}
        autoComplete="email"
      />
      <span
        id={messageId}
        className={showError ? "emailMessage error" : "emailMessage"}
        aria-live="polite"
      >
        {message}
      </span>
    </label>
  );
}

.emailField {
  display: grid;
  gap: 0.375rem;
}

.emailLabel {
  font-weight: 600;
}

.emailMessage {
  min-height: 1.5rem;
  font-size: 0.875rem;
  line-height: 1.4;
  color: #5b6472;
}

.emailMessage.error {
  color: #b42318;
}

Lo importante no es la regex, sinceramente. Lo importante es que min-height reserva el espacio, aria-describedby mantiene la relacion semantica y aria-live="polite" anuncia el cambio sin gritar. En formularios de verdad, esta combinacion evita un monton de micro sacudidas que despues nadie quiere depurar. Es una mejora pequena, pero pega.

Donde se nota la mejora en accesibilidad y conversion

La mejora accesible se ve rapido:

la instruccion no desaparece cuando la persona empieza a escribir
el lector de pantalla encuentra siempre la misma zona de ayuda
el error explica que hacer, no solo que algo fallo

La mejora de producto tambien aparece. Cuando el campo conserva su altura, el boton no baja, el ojo no pierde referencia y el formulario parece mas rapido aunque el JavaScript sea el mismo. Ese tipo de polish suele entrar en la categoria de "detalle menor", pero luego mueve completion rate, sobre todo en movil. No tengo una formula magica aca, pero si he visto que los forms con mensajes estables reciben menos correcciones torpes y menos abandonos raros.

Yo revisaria dos escenarios extra, por si acaso:

zoom alto en iOS Safari
autocompletado agresivo en Chrome con email guardado

Si en esos casos la ayuda sigue clara y el layout no tiembla, vas por buen camino. Si no, arreglarlo temprano cuesta poco; arreglarlo despues, cuando ya se mezclo con analytics y copys urgentes, es mucho mas molesto.

Preguntas rapidas

Q: ¿Debo validar en cada tecla?

A: Solo si el feedback no interrumpe. Muchas veces blur da una experiencia mas limpia, aunque depende del caso.

Q: ¿Necesito aria-live siempre?

A: No siempre, pero en mensajes que cambian sin mover foco suele ayudar bastante.

Q: ¿Esto sirve si luego hago validacion remota?

A: Si. La capa local ordena la experiencia primero, y la remota entra despues sin meter mas caos.

En React, mejorar un campo de email no exige otra libreria ni un rediseño completo. Exige pensar el estado visual como parte del rendimiento percibido. Cuando el mensaje no mueve nada y la instruccion sigue presente, la validacion deja de sentirse tosca. Y eso, aunque sea sutil, los usuarios lo notan un monton.