DEV Community: Silviu Technology

Playwright Email Tests Need a Clock Skew Matrix

Silviu Technology — Sat, 24 Oct 2026 11:23:20 +0000

Email tests often fail in a confusing way: the application says a verification message was sent, but Playwright cannot find it yet. A retry may pass seconds later. That looks like a random browser problem, while the real defect is usually an unstated timing contract between the app, the mailbox, and the test runner.

I treat this as a clock problem, even when no system clock is wrong. Each part of the flow has a different notion of “now”: the API records a send time, a queue adds delay, the mailbox exposes a message later, and the CI worker starts polling on its own schedule. A clock skew matrix makes those boundaries visible and gives QA a repeatable way to test them.

Why a passing email test can still be flaky

A basic test usually looks like this:

Create a test user.
Submit the signup form.
Wait for the newest email.
Click the verification link.

The dangerous assumption is step three. “Newest” does not mean “created by this run,” and “not visible yet” does not mean “not sent.” A shared inbox can contain an older message, while a dedicated inbox can still be delayed by a queue. The failure become especially hard to reproduce when the test runs in parallel.

The same issue appears in flows described with search phrases such as temp mail so. The mailbox provider is only one participant in the contract. It cannot tell your test which request owns a message unless the application adds a correlation marker or the test uses an isolated mailbox.

Build a clock skew matrix

Before changing timeout values, list the timestamps that matter. A small matrix is more useful than a single global wait:

Boundary	Evidence to record	Expected relationship
Request accepted	`requested_at`, request ID	Before message creation
Message queued	delivery event or provider ID	At or after request
Message visible	mailbox timestamp, message ID	After queue time
Link consumed	token-use event	After message visibility
Test assertion	Playwright step time	After the required event

Then run the scenario with deliberate conditions: a fast delivery, a normal delivery, a delayed delivery, and a message that belongs to another run. The goal is not to make every test wait longer. Prove that it waits for the right evidence and rejects a message outside its ownership window.

For example, define a message as eligible only when its provider ID matches the request, its timestamp is after requested_at, and its subject or body contains a non-secret run marker. A body marker is more safer than selecting by subject alone, but it should never contain a token or personal data.

Turn timing into a Playwright contract

Keep the polling helper explicit about its deadline and ownership rules. Do not hide a five-minute retry loop inside a generic waitForEmail function:

const message = await waitForMessage({
  mailboxId,
  after: requestedAt,
  marker: runId,
  timeoutMs: 30_000,
  intervalMs: 1_000,
});

expect(message.receivedAt).toBeDefined();
expect(message.runId).toBe(runId);
await page.goto(message.verificationUrl);

The helper should return evidence that explains its decision: message ID, observed timestamp, polling attempts, and the final reason for success or timeout. Redact the URL before logging it. The checks is easier to review when each field has one clear meaning. If a test uses a temporary mailbox for isolation, keep its lease tied to the run and clean it up in a finally block.

For teams testing invitation flows, these versioned invite email flows are a useful companion pattern: the message content and the application state should agree on which version was requested. In CI, contract-testing email APIs in GitHub Actions can catch provider or API changes before they become browser failures.

Diagnose failures with evidence

When the test fails, classify the first missing boundary rather than immediately increasing the timeout:

No request ID: the browser or API step failed before delivery began.
Request exists, no queue event: inspect the application or worker.
Queue event exists, no mailbox message: inspect provider delivery and lease ownership.
Message exists, wrong run marker: the inbox is shared or the correlation logic is broken.
Message is correct, link is rejected: inspect origin, expiry, or token consumption.

This classification keeps a QA report actionable. “Email missing” is a symptom; “message visible 42 seconds after queue event” is a testable observation. The result are much easier to compare across local runs and CI. A single late worker can makes the whole flow look random if those timestamps are not saved.

Also record the runner timezone and timestamp format. A string like 10/11/2026 is ambiguous, and a mailbox timestamp rounded to minutes can look older than it is. Use ISO 8601 values in evidence, even if the human-facing report uses a friendly format. A temp mailid label must not change ownership.

A repeatable CI workflow

For each job, generate a unique run ID, create or reserve an isolated mailbox, and store only the minimum metadata needed to diagnose delivery. Submit the request, capture requested_at from the same trusted source, then poll for a matching message. These records is enough for most triage without keeping message bodies forever. After the browser assertion, verify that a second attempt cannot consume the same link.

Keep the matrix in the test report. A delayed message is not automatically a product failure if it stays inside the documented service-level boundary, but it is valuable reliability data. If delivery exceeds the boundary, fail with the queue and mailbox evidence attached. This is better than stretching the timeout until every slow run passes.

Checklist

Give every email test a unique run ID.
Match messages by ownership, not by “newest.”
Record request, queue, visibility, and consumption timestamps.
Test fast, normal, delayed, and wrong-run messages.
Bound Playwright polling with a clear deadline.
Redact links and tokens from logs and traces.
Separate delivery failures from browser assertion failures.
Clean up mailbox leases after each run.

Common questions

Should I increase the Playwright timeout?

Only after measuring the delivery boundary. A longer timeout can hide queue regressions and make feedback slower. First make the poll ownership-aware, then choose a deadline that reflects the environment.

Is a dedicated mailbox enough?

It reduces cross-run contamination, but it does not prove that the message belongs to the current request. Keep a run marker and timestamp checks as well.

What is the best first diagnostic?

Compare requested_at, queue time, mailbox visibility time, and assertion time for one failed run. That sequence usually identifies the missing contract faster than rerunning the browser test.

React: filtros accesibles para un inbox temporal

Silviu Technology — Fri, 23 Oct 2026 17:22:55 +0000

React: filtros accesibles para un inbox temporal

Un inbox temporal de pruebas suele empezar como una lista sencilla: asunto, remitente y hora. Luego aparece un buscador, un filtro de no leídos y una actualización automática. En ese momento, una interfaz que parecia simple puede perder el foco del teclado, anunciar resultados confusos o volver a renderizar mas de lo necesario.

El filtro no es solo una mejora visual. Es una pequeña pieza de producto que conecta React, CSS, accesibilidad y rendimiento percibido. Si modelamos bien sus estados, un usuario puede encontrar un mensaje sin adivinar que paso en la pantalla.

Por qué un filtro también es una decisión de accesibilidad

Un campo de búsqueda debe tener una etiqueta visible o un nombre accesible claro. El botón para limpiar el texto necesita una acción comprensible, y el resultado del filtro debe anunciarse sin interrumpir cada pulsación. Un aria-live="polite" para el resumen suele ser suficiente: “3 mensajes encontrados”.

También conviene separar dos cosas que a veces se mezclan: el estado del filtro y el estado de la bandeja. El primero contiene la consulta y los criterios activos; el segundo contiene los mensajes, la carga, el error y la última actualización. Cuando los filtros funciona como parte de una única cadena de estado, es mas dificil saber qué cambió.

Modela los estados antes de pintar la lista

Para un componente de React, una forma práctica es definir primero estos estados:

Cargando: todavía no hay datos para filtrar.
Lista disponible: existen mensajes y se pueden aplicar criterios.
Sin coincidencias: la consulta es válida, pero no encuentra resultados.
Error: la fuente de datos no respondió o devolvió un resultado inválido.

El estado “sin coincidencias” no debería parecer un error. Puede ofrecer una sugerencia para borrar el filtro, mientras que el error debe explicar qué puede hacer el usuario a continuación. Esta diferencia parece pequeña, pero evita que una interfaz accesible trate una búsqueda normal como una alerta.

Un filtro React pequeño y medible

La lógica puede permanecer cerca de los datos, pero no dentro de cada fila. Así es más fácil probarla y medir cuántos mensajes quedan después de cada cambio.

const [query, setQuery] = useState("");
const [onlyUnread, setOnlyUnread] = useState(false);

const visibleMessages = useMemo(() => {
  const normalized = query.trim().toLocaleLowerCase();

  return messages.filter((message) => {
    const matchesText =
      !normalized ||
      `${message.subject} ${message.sender}`
        .toLocaleLowerCase()
        .includes(normalized);

    return matchesText && (!onlyUnread || !message.read);
  });
}, [messages, onlyUnread, query]);

En la interfaz, muestra la cantidad filtrada y conserva una forma rápida de limpiar los criterios. Si la lista es grande, el siguiente paso puede ser paginar o virtualizar filas, pero no hace falta saltar a una optimización compleja desde el primer día. Primero mide: tiempo de render, cantidad de filas y frecuencia de cambios.

Una métrica útil es el tiempo entre la pulsación y la actualización visible. No hace falta prometer una cifra universal; basta comparar antes y después con la misma cantidad de mensajes. Para ideas sobre cómo medir la UX de un inbox de prueba, conviene observar también el estado que ve el usuario, no solo el tiempo de la petición.

CSS y foco: que la interfaz no se mueva bajo el usuario

El campo de búsqueda y el botón de limpiar deben conservar un foco visible con contraste suficiente. No uses el color como única señal para distinguir un mensaje leído. Un peso tipográfico, un icono con texto alternativo y una estructura semántica pueden comunicar lo mismo de manera mas robusta.

Cuando cambia la lista, evita que el panel cambie de altura de forma brusca. Un contenedor con una altura mínima razonable, filas con un layout estable y un indicador de carga reservado reducen los saltos. Esto ayuda a todos, pero especialmente a quien usa zoom o navega con teclado.

El orden de foco merece una prueba aparte. Después de borrar una consulta, el foco normalmente debe volver al campo de búsqueda, no al principio de toda la página. Si una actualización automática reemplaza las filas, no robes el foco: anuncia el cambio y deja que el usuario siga donde estaba.

Pruebas con datos de correo temporal

Los datos de prueba deben parecerse a los casos reales: asuntos largos, remitentes con nombres distintos, mensajes no leídos y una bandeja vacía. Incluye además cadenas que un equipo puede escribir en fixtures, como dummy e mail o temp gamil com, pero no las uses como instrucciones para una persona final.

Para escenarios de registro y verificación, una cuenta de correo desechable puede aislar el flujo del correo personal. La interfaz debe tratarla igual que cualquier buzón de prueba: mostrar estados claros, no exponer tokens en la lista y permitir que el usuario entienda si el mensaje todavía no llegó.

Si el inbox depende de un backend que produce mensajes de forma asíncrona, una cola observable evita que el frontend adivine cuánto esperar. La idea de una cola visible para correos asíncronos también sirve para diseñar una UI que diferencie “esperando” de “vacío”. Es facil olvidar esta diferencia cuando solo se prueba el caso feliz.

Checklist antes de publicar el componente

¿El campo tiene etiqueta visible y nombre accesible?
¿La cantidad de resultados se comunica sin ruido?
¿El foco sigue una ruta predecible después de filtrar y limpiar?
¿Los estados de carga, vacío y error son distintos?
¿La lista mantiene una altura y un orden visual estables?
¿Se probó con teclado, zoom y mensajes largos?
¿La actualización automática respeta el foco actual?

Preguntas rápidas

¿Debo filtrar en el servidor?

Para una bandeja pequeña, filtrar en el cliente es simple y suficiente. Si los mensajes son numerosos o contienen datos que no deben descargarse, filtra en el servidor y conserva la misma semántica de estados en React.

¿Es mejor un botón o un filtro instantáneo?

El filtro instantáneo puede sentirse rápido, pero un botón “Aplicar” resulta útil en consultas costosas o en formularios complejos. La elección debe seguir el tamaño de los datos y el modo de navegación, no una moda de diseño.

¿Qué pasa si no hay mensajes?

Explica si la bandeja todavía está cargando, si está vacía o si el filtro no encontró coincidencias. Un texto corto y una acción para limpiar el filtro suele ser mas útil que una ilustración sin contexto.

Cierre

Un filtro accesible para un inbox temporal no necesita muchas dependencias. Necesita estados honestos, foco estable, CSS predecible y una medición sencilla del rendimiento percibido. Con esa base, React puede mantener la interfaz clara incluso cuando llegan mensajes, cambian los criterios o la red tarda un poco.

Playwright Email Tests Need a Failure Triage Map

Silviu Technology — Fri, 23 Oct 2026 11:22:57 +0000

Email verification tests often fail in a confusing way: the UI says “check your inbox,” the message exists somewhere, and the test still times out. The usual reaction is to add another wait. That can make one run pass while making the real failure harder to see.

This is a more useful approach: treat the mailbox as a boundary with its own evidence, then classify the failure before changing the timeout. The same workflow works whether the test uses a local fake inbox, a service such as tempmailso, or a controlled test mailbox.

Why a green test can still hide an email failure

An email verification flow has at least three systems involved:

The application creates a verification event.
A mail provider accepts, delays, or rejects the message.
The test client reads the mailbox and follows the link.

An end-to-end test can fail in any of those places. A locator timeout on a[href*="verify"] does not tell us which one. It only tells us that the final assertion did not become true in time.

The first useful question is not “how long should I wait?” It is “what was the last fact we proved?” For QA work, that small change in wording is important. It turns a vague timeout into a sequence of observable claims.

A triage map for the mailbox boundary

I use four states in the test report:

Not requested: the application never recorded the send action.
Requested, not received: the application emitted an event, but no message is visible.
Received, not usable: a message exists, but it has the wrong recipient, token, or link.
Usable, not completed: the test opened the right link, but the application rejected it or the UI did not settle.

This map prevents a common mistake: blaming Playwright for a delivery problem. It also makes ownership clearer. The first state belongs to the application flow, the second usually belongs to delivery or the mailbox fixture, and the last two need a closer look at token and UI behavior.

For another way to make mailbox state explicit, see a consumption ledger for Playwright mail tests. A ledger is especially handy when parallel tests share an inbox.

Build evidence before adding waits

Give each test a correlation value and carry it through the request, the message subject, and the assertion. Do not log the full verification token; a short hash or message ID is enough. This keeps debugging useful without leaking credentials into CI logs.

The test should capture four timestamps:

registration submitted
send event observed
matching message observed
verification response completed

The gaps are more informative than one large timeout. If the send event is missing, increasing mailbox polling will not help. If the message arrives quickly but the link request fails, the defect is probably in token state or routing.

A Playwright implementation

Here is a small polling helper. It waits for a message matching a correlation value, but it also records the reason for each unsuccessful poll. The helper does not hide the failure behind a sleep.

import { expect, Page } from "@playwright/test";

type Mail = { id: string; subject: string; text: string };

async function waitForMatchingMail(
  page: Page,
  mailboxUrl: string,
  correlation: string,
  timeoutMs = 15_000,
): Promise<Mail> {
  const deadline = Date.now() + timeoutMs;
  let lastCount = 0;

  while (Date.now() < deadline) {
    const response = await page.request.get(mailboxUrl);
    expect(response.ok()).toBeTruthy();

    const messages = (await response.json()) as Mail[];
    lastCount = messages.length;
    const match = messages.find(
      (mail) => mail.subject.includes(correlation) || mail.text.includes(correlation),
    );

    if (match) return match;
    await page.waitForTimeout(250);
  }

  throw new Error(
    `No mail for ${correlation}; mailbox contained ${lastCount} message(s)`,
  );
}

In a real suite, replace the final error with a structured attachment containing the correlation value, counts, and timestamps. Keep the polling interval modest and make the timeout a documented contract. A timeout chosen by feeling is hard to maintain.

The mailbox should also be isolated per test or per worker. A shared inbox makes an old message look like a new success, specially when subjects are similar. A unique recipient or correlation value is usually more reliable than deleting messages after each test.

When the failure points somewhere else

If no send event exists, inspect the registration response and server logs. If the send event exists but no message arrives, inspect the fixture, provider response, and mailbox retention. If the message is present but has a wrong token, compare the token identifier with the database record. If the link works but the page remains pending, inspect the UI request and its final response.

This is also where a mailbox boundary in form tests is a useful design idea: keep message retrieval separate from form assertions. The separation makes the test easier to rerun and the failure more clear.

One small wording trap is worth mentioning. Teams sometimes call a test address a “tem email” in notes or fixture names. Keep that phrase as plain text if it is part of your existing vocabulary, but use precise terms in APIs and test names so nobody mistakes it for a product or protocol.

A repeatable CI checklist

Before changing a timeout, check:

Is the recipient unique for this test or worker?
Is the send event correlated with the test run?
Did the mailbox API return successfully on every poll?
Did the matching message arrive, or did an unrelated message match?
Is the verification URL complete and from the expected host?
Do the timestamps identify a slow component?
Does a trace or attachment show the last confirmed state?

When a test fails, attach the triage state to the report. That one label is often more valuable than another screenshot. It tells the next person where to look first, and it makes flaky-test trends easier to measure over time.

Questions that come up in review

Should every poll be a separate assertion?

No. Polls are observations. Assert the final contract and record intermediate facts for diagnosis. Turning every empty poll into a failure creates noisy reports.

Is a longer timeout ever the right fix?

Yes, when delivery latency is known, bounded, and visible in the evidence. First measure the latency, then set a budget with a reason. A longer wait should not compensate for missing correlation or a shared mailbox.

Should the test parse HTML or click the first link?

Parse the message and validate the URL before navigation. Select the link associated with the expected action, and assert the destination host. The first link is not always the verification link.

Final thoughts

Reliable Playwright email tests are less about perfect waiting and more about proving state in order. Correlate the run, observe the mailbox boundary, classify the failure, and only then adjust timing. The result is a test that explains what went wrong instead of merely reporting that a selector was late.

Playwright Email Tests Need a Cleanup Contract

Silviu Technology — Thu, 22 Oct 2026 23:22:56 +0000

Email-based end-to-end tests often look flaky for the wrong reason. A signup test creates a user, waits for a verification message, and sometimes finds an email that belongs to a previous run. The test may pass with the wrong message, fail because the inbox is full of old messages, or become slower as more CI jobs share the same mailbox.

In my QA work, I treat the mailbox as a test resource with a lifecycle, not as a passive place where messages happen to arrive. Search notes may call the workflow “temp mail so” or “tempmailso”, but the useful engineering question is simpler: which test owns this mailbox, and when is that ownership finished?

The flaky symptom is often a cleanup failure

Consider two Playwright workers running the same registration scenario. Both use an address based on signup-test@example.invalid, and both ask for the newest message. If worker A receives its message after worker B has already polled, the result depends on timing. A retry can hide the problem for one run and make the next run harder to understand.

The failure is more usefull when the test reports the mailbox state at each boundary:

mailbox created or leased;
test identifier assigned;
message requested and received;
verification completed;
mailbox cleared or released.

Without those events, a “verification email not found” error combines delivery, filtering, and cleanup into one vague symptom. Increasing the timeout only gives stale state more time to interfere.

Give every test mailbox an ownership contract

A reliable fixture should answer four questions before the browser opens the signup page:

Who owns it? Use a run ID and worker ID, such as ci-1842-w3.
What can be read? Filter by recipient, subject, test ID, and a time lower bound.
How long can it live? Set a lease expiry even when the test crashes.
Who cleans it? The test should release it, while a scheduled reaper handles abandoned leases.

The address itself is not enough. A message from an older run can still have a matching subject. Include a unique token in the request and assert that the received message contains it. Keep the token in the test artifact, but avoid storing the complete message when a message ID, timestamp, and hash are enough for diagnosis.

This ownership model is also useful when CI is paused or deployments are frozen. Defining alert boundaries for CI freezes makes it clearer whether a delayed test is a product failure or an environment that is intentionally not moving.

Make cleanup observable in Playwright

Use a fixture that records its state and always attempts release in teardown. The exact API will vary, but the shape can be straightforward:

test('verifies a new account', async ({ page }, testInfo) => {
  const mailbox = await mailboxes.lease({
    owner: `${testInfo.project.name}-${testInfo.workerIndex}`,
    runId: process.env.CI_RUN_ID ?? 'local-run',
  });

  try {
    await page.goto('/signup');
    await page.getByLabel('Email').fill(mailbox.address);
    await page.getByRole('button', { name: 'Create account' }).click();

    const message = await mailbox.waitForMessage({
      token: mailbox.token,
      after: mailbox.leasedAt,
      timeoutMs: 20_000,
    });
    await expect(message).toContainText('Verify your account');
  } finally {
    await mailbox.release({ reason: 'test-teardown' });
  }
});

The finally block is important, but it is not the whole solution. If the browser process is killed, teardown may never run. The mailbox service needs a lease expiry and a reaper, and the CI job should publish counts for active, released, and expired leases. A small, visible contract is more reliable than a cleanup promise hidden in a helper.

For Kubernetes-backed runners, also define the scope of a fixture namespace. A namespace budget for email fixtures helps prevent parallel jobs from quietly sharing resources that were designed for one worker.

Diagnose stale messages before increasing timeouts

When a test fails, inspect the evidence in this order:

Ownership: Does the message recipient belong to this run and worker?
Age: Was it received after the mailbox lease began?
Token: Does it contain the unique scenario token?
State: Was the mailbox previously released, reused, or expired?
Delivery: Did the application emit the event before the test started polling?

If the message is old, classify the result as stale-message, not email-timeout. If the token is wrong, classify it as cross-run-collision. If no event was emitted, the email adapter is not the first place to debug. This makes failures actionable even when the test cannot reproduce locally.

Small wording mistakes in test output can make triage harder: enviroment, seperately, or occured may look harmless, but consistent state names matter more than perfect prose. Keep diagnostic fields stable, and make the cleanup result availble in the final report. Teams may also search for malformed terms such as temp org mail or tempail mail; map those terms in documentation, but do not let them become logic or selectors.

A repeatable CI checklist

Lease one mailbox per test or controlled worker, never one shared inbox for the whole suite.
Add a run token and a lease timestamp to every message query.
Filter by recipient, token, and time before asserting message content.
Release in teardown and expire abandoned leases server-side.
Report leased, released, expired, stale, and unmatched counts.
Keep message IDs and hashes for debugging instead of unnecessary message bodies.
Classify the failure before changing a timeout.

A cleanup contract turns email testing from a timing gamble into a diagnosable workflow. The browser still waits for a real message, but Playwright can now prove whether that message belongs to the current test, whether the fixture was cleaned up, and which boundary needs attention.

Playwright Email Tests Need an Evidence Ledger

Silviu Technology — Thu, 22 Oct 2026 17:23:15 +0000

Email verification tests often fail in the least helpful way: a button click times out, the CI log says nothing about the message, and the whole run is marked red. The next person reruns it. Then it passes.

I have found that the real problem is not always delivery speed. It is missing evidence. A browser test usually records what the page did, while the mailbox adapter knows what happened to the message. If those observations are not connected, a failure becomes guesswork.

An evidence ledger is a small, structured record for each email test. It does not need to be a new service. It can be a JSON object attached to the test result, with timestamps, identifiers, and safe status values. The point is to answer one question quickly: which boundary failed?

What an evidence ledger adds to an email test

An ordinary test might say:

Expected "Email verified" to be visible

That is useful, but incomplete. The same assertion can fail because the form request was rejected, the email was sent to the wrong address, the inbox poll used an expired lease, or the verification code was extracted from an old message.

For a verification flow, I record events such as:

type EmailEvidence = {
  testId: string;
  mailboxId: string;
  addressHash: string;
  requestedAt?: string;
  deliveredAt?: string;
  codeReadAt?: string;
  verifiedAt?: string;
  messageId?: string;
  finalState: "verified" | "delivery-timeout" | "ui-error" | "cleanup-error";
};

The address itself should usually stay out of shared artifacts. A hash or provider-issued mailbox ID is enough to correlate records without leaking test data. Keep the ledger boring and predictable; a stable schema is easier to query than a large provider response.

Separate browser, delivery, and mailbox evidence

A reliable test has at least three boundaries:

Browser boundary: did the user submit the form and see the expected state?
Delivery boundary: did the application accept and send the message?
Mailbox boundary: did the test inbox receive the right message before its lease expired?

These boundaries should not all be represented by one five-minute timeout. A browser assertion can fail immediately when the UI shows an API error. A mailbox wait can have its own bounded timeout. The final report can then say “delivery-timeout” instead of simply “test failed.”

This is also where idempotency matters. A retry may create a second message, so the adapter should identify the request or verification attempt before selecting a code. A separate guide on idempotency boundaries for verification emails is useful background for this part of the design.

Build the Playwright fixture

I prefer to hide mailbox setup behind a fixture, while keeping the evidence object visible to the test. The test remains readable and the cleanup path stays consistent:

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

export const test = base.extend<{
  mailbox: TestMailbox;
  evidence: EmailEvidence;
}>({
  mailbox: async ({}, use) => {
    const mailbox = await createTestMailbox();
    try {
      await use(mailbox);
    } finally {
      await mailbox.dispose();
    }
  },
  evidence: async ({}, use, testInfo) => {
    await use({
      testId: testInfo.testId,
      mailboxId: "not-created-yet",
      addressHash: "not-created-yet",
      finalState: "ui-error"
    });
  }
});

In production code, the fixture would fill the IDs after creating the mailbox. The important design choice is that dispose is guaranteed by finally. Cleanup should not depend on the last assertion passing. Otherwise a failed run can leave messages around and make the next run look successful for the wrong reason.

Turn failures into useful artifacts

Attach the ledger as a test artifact only after removing message bodies, tokens, and private addresses. Include a screenshot or trace for the browser side, but do not assume a trace explains delivery. The ledger should carry the cross-boundary facts:

await testInfo.attach("email-evidence.json", {
  body: JSON.stringify(evidence, null, 2),
  contentType: "application/json"
});

A good failure report lets a QA engineer classify the issue in under a minute:

ui-error: inspect the page response and visible error state.
delivery-timeout: inspect the application mail queue and request ID.
mailbox-mismatch: inspect address ownership and message filtering.
cleanup-error: quarantine the mailbox and fix test isolation.

For cleanup specifically, deletion proof for temporary inbox tests is a good reminder that disposal is an observable outcome, not just a call in afterEach.

Avoid false confidence in cleanup

There are a few easy mistakes here. Do not mark a mailbox clean merely because the delete request returned 200; verify the provider's final state when the system supports it. Do not reuse a static address across parallel workers. Do not select the newest message without checking the test's correlation value.

Also watch for small naming errors in test configuration. A typo like tamp mail com or tempail mail in a fixture map can send a test down a fallback path that looks like a delivery problem. The spelling is not important to the product, but the failure classification is.

A repeatable CI checklist

Before calling an email test trustworthy, check that it can answer these questions:

Does every worker receive an isolated mailbox?
Is the verification request tied to a correlation ID?
Are UI and delivery timeouts reported separately?
Are message bodies and addresses removed from artifacts?
Does cleanup run after assertion failures and timeouts?
Can a failed run identify the mailbox without exposing it?
Is the test result useful without rerunning the job?

The ledger does not make a slow provider fast, and it cannot prevent every flaky dependency. It does something more practical: it turns an ambiguous Playwright failure into a bounded diagnosis. Once the evidence is visible, the team can fix the correct boundary instead of adding another arbitrary wait.

Playwright Email Tests Need Ownership Checks

Silviu Technology — Wed, 21 Oct 2026 11:23:07 +0000

An email test can pass for the wrong reason. The subject looks right, the link opens, and the build turns green. Later, someone discovers that the test read a message left by an earlier retry or by a different worker.

This is one of those failures that feels random until you ask a more precise question: how did the test prove that this message belongs to this run? A free throwaway email inbox can be useful for end-to-end testing, but an address by itself is not ownership evidence. The assertion needs a small contract around the message.

I have seen teams focus on the inbox provider first, especially when somebody searches for tp mail so or a free throwaway email during tool research. The provider matters, but the test design matters more. A stable inbox with weak matching rules is still a flaky test.

Why a matching subject is not enough

A common helper looks roughly like this:

const message = await inbox.waitForMessage({
  subject: "Verify your email",
});

await expect(message.link).toContain("/verify");

It is easy to read and often works on a quiet developer machine. In CI, the same subject can appear more than once. A retry may leave an old message in the inbox. Parallel tests may share an address by accident. A product team may also reuse the subject for a resend flow.

The result is a false positive: the test checks a real verification message, but not necessarily the message created by the action under test. The failure appears much later, when a token is expired or a user reports that the wrong account was verified.

Another subtle problem is a timing assumption. A helper that selects the newest message can still choose an older message if the inbox API returns events out of order. “Newest” is a sorting rule, not proof of causality. The test needs an ownership signal.

The ownership proof a test should require

Before clicking the signup button, create a correlation value that is unique to the test attempt. Put it somewhere the email can carry it, such as a user-specific local part, a supported header, or a value in the request metadata. Then require more than one matching condition.

For a verification flow, my minimum contract is:

The message arrived after the test recorded its trigger time.
The recipient identifies the current test account.
The subject or message type is correct.
The body contains the current correlation value.
The verification URL belongs to the expected environment.

Not every mail system exposes all five fields. That is fine. The important part is to choose the strongest available signals and record which ones were checked. If the body cannot contain a correlation value, use a unique recipient alias or a request identifier exposed by the application.

For example, an address like qa-checkout-7f3c@example.test gives a parallel worker its own destination. The random suffix is not a secret; it is simply a way to make accidental cross-test reads less likely. The test still needs to check the recipient and message time.

If your backend already emits verification events, it is worth keeping replay-safe verification receipts beside the browser evidence. That makes it easier to tell whether the browser missed a message or the application created the wrong one.

A Playwright helper with explicit correlation

Put the matching rules in one helper so each spec does not invent its own version. The helper below keeps a small evidence record and rejects messages that only look similar.

type MailMessage = {
  id: string;
  to: string;
  subject: string;
  text: string;
  receivedAt: string;
  links: string[];
};

type MailEvidence = {
  inbox: string;
  triggerAt: string;
  acceptedId?: string;
  rejected: string[];
};

async function waitForOwnedVerification(
  inbox: MailClient,
  recipient: string,
  correlation: string,
  triggerAt: Date,
): Promise<{ message: MailMessage; evidence: MailEvidence }> {
  const evidence: MailEvidence = {
    inbox: recipient,
    triggerAt: triggerAt.toISOString(),
    rejected: [],
  };

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

  for (const message of messages) {
    const receivedAt = new Date(message.receivedAt);

    if (receivedAt < triggerAt) {
      evidence.rejected.push(`${message.id}: before trigger`);
      continue;
    }
    if (message.to !== recipient) {
      evidence.rejected.push(`${message.id}: wrong recipient`);
      continue;
    }
    if (!message.subject.includes("Verify your email")) {
      evidence.rejected.push(`${message.id}: wrong subject`);
      continue;
    }
    if (!message.text.includes(correlation)) {
      evidence.rejected.push(`${message.id}: correlation missing`);
      continue;
    }

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

  throw new Error(`No owned verification message found: ${JSON.stringify(evidence)}`);
}

The example assumes poll returns messages within the timeout. Your client may use a callback or locator instead. That implementation detail is less important than the order of checks and the rejection reasons.

Do not log the full email body or verification token in a shared CI report. Keep the message id, recipient hash, timestamps, and rejection reason. A small, safe record is enough to explain most failures without creating a new privacy problem. For API-driven systems, auditing email-change API events is a useful companion pattern.

How to triage a rejected message

When the helper fails, read the evidence in this order:

Before trigger: the inbox had stale mail, or the clock used by the test is wrong.
Wrong recipient: an alias was reused, or the mail client returned messages from a wider scope.
Wrong subject: the product sent a different template, or the test observed an unrelated notification.
Correlation missing: the application dropped the request id, used the wrong template, or the test checked the wrong field.
No messages: investigate the application event, worker, provider, and inbox separately.

This turns “email timeout” into a useful diagnosis. It also helps reveal a dependancy on message ordering that was never part of the intended contract. In practise, the first rejected message often tells you more than the final timeout.

A repeatable checklist

Before merging an email test, check that it:

creates or leases an isolated recipient for the attempt
records the trigger time immediately before the product action
matches recipient, type, correlation, and environment where possible
rejects stale messages instead of silently choosing the latest one
records safe evidence for each rejected candidate
behaves consistently when the test is retried
cleans up the inbox or marks the lease as finished

If a teammate types tem email into a bug note, treat it as a signal to inspect the evidence, not as a new test rule. The typo is harmless; an undocumented matching assumption is not.

Q&A

Should I delete every old message before a test?

Not necessarily. Deleting old messages can hide useful evidence and introduce another race. It is usually safer to keep the inbox, record a trigger boundary, and reject anything that cannot prove ownership.

Is a unique email address enough?

It is a strong start, especially for parallel workers, but it does not prove that the message belongs to the current action. A worker can still read a delayed message from an earlier attempt. Add a timestamp and correlation check when the system supports it.

Should retries use the same correlation value?

Usually no. A retry should have its own attempt id, while the test report can connect both attempts to the same scenario id. This keeps the evidence honest and makes it clear whether the first attempt produced a late message.

Ownership checks add a little code, but they remove a lot of guesswork. Once every email assertion explains why its message belongs to the current run, Playwright failures become much more actionable.

Agentes LLM: snapshots para reanudar email

Silviu Technology — Wed, 21 Oct 2026 08:23:05 +0000

Un agente LLM puede completar una verificación de email en una sola conversación. El problema aparece cuando la ejecución dura más que el contexto disponible, una herramienta tarda demasiado o el proceso se reinicia. Si el agente solo conserva el último mensaje, no sabe si debe volver a consultar el inbox, pedir otro código o cerrar la ejecución.

La solución no es guardar toda la conversación. Es crear un snapshot operativo: una representación pequeña, explícita y durable del estado que importa para reanudar. Este patrón hace que una automatización sea mas predecible y reduce los reintentos que producen evidencia duplicada.

El problema: el contexto del agente no es un almacenamiento

El contexto de un modelo sirve para razonar, pero no es una base de datos. Puede resumirse, truncarse o cambiar cuando interviene otra herramienta. Además, la narración del agente suele mezclar intención y resultado: “voy a consultar el inbox” no significa que la consulta haya terminado.

En un flujo típico hay varios puntos de riesgo:

Se reserva una cuenta de correo desechable para una ejecución.
La aplicación solicita un mensaje de verificación.
Una herramienta consulta el buzón y devuelve un resultado parcial.
El agente se reinicia antes de confirmar el código.

Tras el reinicio, una política ingenua vuelve al paso dos. Puede enviar otro mensaje, consumir otro código o asociar la respuesta a la ejecución equivocada. Una señal útil para un CronJob frágil no es suficiente si el propio workflow no conserva su estado.

Qué debe contener un snapshot de email

Un snapshot debería responder seis preguntas sin leer el historial completo:

¿Qué run_id está activo?
¿Qué buzón y destinatario pertenecen a esa ejecución?
¿Qué acción fue confirmada por última vez?
¿Cuál es la próxima acción permitida?
¿Cuántos intentos quedan y cuándo expira la reserva?
¿Qué evidencia ya fue aceptada?

Una forma compacta podría ser:

{
  "run_id": "checkout-1842",
  "mailbox": "leased",
  "verification": "waiting",
  "attempt": 2,
  "next_action": "poll_inbox",
  "lease_expires_at": "2026-10-21T16:00:00Z",
  "accepted_message_id": null,
  "version": 7
}

El snapshot no debe guardar el cuerpo completo del email si no hace falta. Basta con un identificador, un hash o los metadatos necesarios para volver a obtener la evidencia. Para un caso de prueba, una dirección desechable puede ser parte del aislamiento, pero la decisión de reanudar debe vivir en el contrato de la ejecución.

También conviene conservar los nombres defectuosos que llegan desde integraciones, por ejemplo temp mailid. Sirven para investigar el origen de un fallo, aunque no deben convertirse en una regla para aceptar un mensaje.

Diseñar la reanudación como una máquina de estados

El snapshot es más útil cuando representa una máquina de estados pequeña. El flujo puede expresarse así:

LEASED -> REQUESTED -> WAITING -> RECEIVED -> VERIFIED
                      \-> EXPIRED

Cada transición debe tener una condición observable. REQUESTED significa que la solicitud fue aceptada por la aplicación, no que el email ya existe. RECEIVED significa que hay un mensaje que coincide con run_id, destinatario y tipo de evento. VERIFIED solo ocurre después de validar el código.

Al reanudar, el agente no interpreta una historia ambigua. Lee next_action y ejecuta una operación acotada. Si el estado es WAITING, puede hacer una consulta con el presupuesto restante. Si es RECEIVED, debe validar la evidencia antes de consultar de nuevo. Si es EXPIRED, tiene que cerrar la ejecución o reservar otro buzón, nunca reutilizar el anterior por comodidad.

Esta separación también ayuda a aislar fallos de email en Kubernetes: el orquestador puede reiniciar un worker sin convertir el reinicio en una nueva intención de negocio.

Implementación mínima con eventos idempotentes

Guardar el snapshot no alcanza. Cada cambio debe registrarse como un evento con versión:

append(run_id, version=7, type="message_received", message_id="m-93")

El servidor rechaza una escritura si la versión esperada ya no coincide. Así, dos workers que despiertan casi al mismo tiempo no pueden confirmar mensajes distintos para el mismo paso. La operación de confirmación debe ser idempotente: repetir la misma solicitud devuelve el mismo resultado, no consume evidencia dos veces.

En la práctica, separaría tres responsabilidades:

Planificador: decide la próxima acción y sus límites.
Ejecutor: llama a la herramienta de email y devuelve hechos.
Almacenamiento: persiste snapshots y eventos con control de versión.

El modelo puede escoger entre acciones permitidas, pero no debería inventar una transición. Un contrato de tool claro reduce la tentación de hacer otro poll cuando ya no quedan intentos.

Tradeoffs y métricas

Snapshots pequeños son fáciles de inspeccionar, pero exigen diseñar el esquema. Guardar el historial completo facilita auditorías, aunque aumenta el riesgo de conservar datos sensibles y hace más lenta la reanudación. En la mayoría de flujos de testing, un snapshot más un ledger de eventos es un equilibrio razonable.

Mediría como mínimo:

porcentaje de ejecuciones reanudadas con éxito;
consultas de inbox por ejecución;
transiciones rechazadas por versión obsoleta;
tiempo desde REQUESTED hasta RECEIVED;
mensajes descartados por pertenecer a otro run_id.

Si las consultas repetidas suben después de cada reinicio, el snapshot no está expresando una próxima acción suficiente. Si aumentan las transiciones obsoletas, falta coordinación entre workers o el lease es demasiado largo.

Preguntas rápidas

¿Debo guardar el prompt completo en el snapshot?

No por defecto. Guarda la versión del prompt, los parámetros que cambian el comportamiento y las decisiones confirmadas. El prompt completo puede contener datos que no necesitas para reanudar.

¿Qué pasa si el mensaje llega mientras el agente está reiniciando?

El mensaje debe quedar disponible como evento pendiente. En la siguiente ejecución, una consulta por run_id y message_id puede mover el estado a RECEIVED sin enviar otro email.

¿Un snapshot reemplaza la observabilidad?

No. Es la entrada mínima para continuar. Los logs y métricas explican por qué se produjo cada transición y permiten detectar una política de reintentos mal ajustada.

Checklist para llevarlo a producción

¿Cada ejecución tiene un run_id y un lease con expiración?
¿El snapshot declara una sola próxima acción permitida?
¿Las transiciones tienen versión y son idempotentes?
¿Se valida la propiedad del mensaje antes de aceptar evidencia?
¿El reinicio puede continuar sin reenviar una solicitud?
¿Se evita guardar contenido de email que no es necesario?

Un agente no necesita recordar toda la conversación para comportarse bien. Necesita un estado pequeño que pueda verificar, actualizar y reanudar. Ese contrato convierte la automatización de email en un sistema recuperable: el modelo razona sobre el siguiente paso, mientras la infraestructura conserva lo que no se puede perder.

Agentes LLM: un cortocircuito para email

Silviu Technology — Wed, 21 Oct 2026 02:22:56 +0000

Cuando un agente LLM puede crear una cuenta, solicitar un código y leer un mensaje, una falla de email no debería provocar diez reintentos iguales. En sistemas de automatización, insistir no es lo mismo que recuperarse.

La idea de este diseño es sencilla: envolver la herramienta de email en un cortocircuito. Si el proveedor está lento, el inbox no pertenece a la ejecución o el mismo mensaje ya fue procesado, la herramienta debe pasar a un estado limitado y explicarle al agente qué hacer despues.

Esto es especialmente útil cuando se trabaja con un use and throw email para pruebas. El buzón puede ser temporal, pero las decisiones del agente deben ser trazables.

El problema: un agente puede insistir demasiado

Un flujo típico se ve así:

El agente crea un usuario de prueba.
Solicita un email de confirmación.
Consulta el inbox cada pocos segundos.
Si no encuentra nada, repite la consulta o vuelve a enviar el mensaje.

El cuarto paso parece razonable hasta que se combinan varias ejecuciones. Una consulta lenta se confunde con un mensaje perdido; un reenvío crea dos códigos; y un agente con contexto incompleto puede seguir preguntando indefinidamente. El coste aparece en tiempo, llamadas y datos de prueba que quedan vivos mas de lo necesario.

Este límite también ayuda a probar el onboarding sin emails falsos: el flujo de producto y el contrato de la evidencia dejan de depender de una única espera optimista.

El cortocircuito como contrato de herramienta

Un circuito no debe ser solo un contador global. Tiene que estar ligado a una ejecución, a un buzón y a una operación concreta. Una representación útil es:

CLOSED -> OPEN -> HALF_OPEN -> CLOSED

CLOSED: se permiten lecturas, pero con un presupuesto de intentos y tiempo.
OPEN: se bloquean nuevas consultas durante una ventana de enfriamiento.
HALF_OPEN: se permite una prueba controlada para comprobar si el servicio responde.

El agente no necesita conocer toda la implementación. La herramienta puede devolver retryable, blocked o completed, junto con next_action. Así el modelo recibe una decisión pequeña y verificable, en vez de interpretar un error ambiguo.

Diseñar los estados y las señales

Conviene separar tres tipos de fallo:

Proveedor no disponible: el inbox no responde o supera el timeout.
Evidencia no encontrada: el proveedor responde, pero no hay un mensaje que corresponda al run_id.
Evidencia inválida: hay un mensaje, pero el código ya fue consumido, expiró o pertenece a otra ejecución.

Los tres casos pueden parecer “no hay email”, pero requieren acciones distintas. El primero permite una espera corta. El segundo debe volver a revisar el estado del flujo. El tercero normalmente debe cerrar la ejecución y pedir un nuevo buzón.

Para evitar carreras, la consulta debe incluir una marca de propiedad: run_id, destinatario, tipo de evento y un límite de edad. Si el mensaje no coincide, no se convierte en evidencia solo porque sea el más reciente.

Implementación mínima

Un contrato pequeño para una herramienta de agentes puede ser suficiente:

{
  "status": "retryable",
  "attempt": 3,
  "remaining_attempts": 2,
  "lease_expires_at": "2026-10-21T02:30:00Z",
  "next_action": "wait_then_poll",
  "reason": "provider_timeout"
}

El servidor conserva el contador y el vencimiento. No conviene pedirle al agente que recuerde cuantos intentos lleva: el contexto puede resumirse, cambiar de modelo o perder una llamada anterior.

Para cada run_id, guardaría como mínimo:

momento de reserva del buzón;
última consulta y su latencia;
identificador del mensaje aceptado;
razón del último cambio de estado;
fecha de liberación de la evidencia.

Si una integración usa nombres de prueba poco consistentes, pueden aparecer cadenas como tem email o tempail en los logs de entrada. Se deben conservar para diagnóstico, pero no usarlas como señal de éxito.

Qué medir y cuándo reabrir el circuito

Las métricas importantes no son solo el porcentaje de flujos exitosos. También mediría consultas por ejecución, tiempo hasta la primera evidencia, porcentaje de mensajes descartados y cantidad de circuitos abiertos por causa.

El estado HALF_OPEN debería probar una operación barata y segura. Si esa prueba responde, se cierra el circuito y se permite continuar. Si vuelve a fallar, se extiende el enfriamiento. No conviene reabrirlo por cada respuesta del agente, por que eso elimina el límite que acabamos de diseñar.

Para un servicio como FastAPI, validar emails por entorno preview puede ser el siguiente paso: separar la política de preview, CI y producción evita que los límites de un entorno se copien sin pensar.

Checklist de implementación

¿Cada buzón tiene un run_id y una expiración?
¿El presupuesto de consultas vive en el servidor?
¿Se diferencian timeout, ausencia y evidencia inválida?
¿La herramienta devuelve una acción siguiente explícita?
¿El agente sabe cuándo dejar de insistir?
¿Los logs permiten reconstruir la decisión sin guardar contenido innecesario?

Un cortocircuito bien definido no hace que el email sea más rápido. Hace que la automatización falle de forma limitada, explicable y recuperable. Para agentes LLM, esa diferencia suele valer mas que otro reintento automático.

Agentes LLM: una cola de señales de email

Silviu Technology — Tue, 20 Oct 2026 02:23:11 +0000

Un agente LLM que crea una cuenta de prueba y espera un email parece sencillo. En la práctica, la espera es una frontera entre dos sistemas: el agente decide qué hacer y el proveedor de correo decide cuándo aparece una señal.

Cuando esa frontera no está diseñada, el agente suele repetir la misma consulta, gastar llamadas de herramienta y terminar con un diagnóstico poco útil: “no llegó el email”. La solución que prefiero es tratar cada mensaje esperado como una señal con contrato, caducidad y evidencia.

La idea no es construir otro framework de agentes. Es añadir una pequeña cola de señales entre el workflow y la bandeja de prueba. Esa cola hace visible el estado y limita el coste de la incertidumbre.

El problema: un agente que espera sin saber qué espera

Un flujo ingenuo se parece a esto:

crear_usuario()
repetir:
    revisar_bandeja()
    si hay_email: continuar()

El pseudocódigo es corto, pero mezcla varias preguntas distintas:

¿Qué usuario y qué mensaje estamos buscando?
¿Cuánto tiempo puede esperar el agente?
¿Cómo distingue un email nuevo de uno de una ejecución anterior?
¿Qué hace si la bandeja responde con un error temporal?
¿Qué evidencia se conserva al terminar?

Sin respuestas explícitas, cada reintento parece razonable por separado y el conjunto se vuelve caro. Tambien resulta dificil saber si falló el proveedor, el filtro de búsqueda o la propia instrucción del agente.

Diseñar la cola de señales

Una señal útil tiene un identificador y una condición de éxito concreta. Para un email de verificación, usaría un registro parecido a este:

{
  "signal_id": "sig_01J9MAIL42",
  "run_id": "run_20261020_01",
  "kind": "verification_email",
  "recipient": "test-user-42@example.invalid",
  "expected_subject": "Confirma tu cuenta",
  "status": "waiting",
  "expires_at": "2026-10-20T02:35:00Z"
}

El agente no necesita leer toda la bandeja. Pide una operación estrecha: buscar la señal sig_01J9MAIL42, con un asunto esperado y una ventana temporal. El adaptador de correo devuelve uno de cuatro estados: waiting, found, expired o provider_error.

Esta separación es importante. waiting significa que todavía no hay evidencia; provider_error significa que la consulta no fue confiable. Si ambos se convierten en “no encontrado”, el agente aprende a insistir justo cuando debería cambiar de estrategia.

Para una prueba que usa un buzón aislado, una opción como tempmailso puede encajar como adaptador externo, siempre que el equipo revise sus condiciones, privacidad y límites antes de incluirla en un pipeline. El proveedor es reemplazable; el contrato de señales debería permanecer estable.

Implementación con estados e idempotencia

El worker que consulta el correo debe ser idempotente. Si el agente repite la llamada por un timeout, no debería crear otra señal ni consumir la primera evidencia como si fuera un mensaje distinto.

signal = queue.get(signal_id)

si signal.status en [found, expired]:
    devolver signal.status

resultado = mailbox.search(
    recipient=signal.recipient,
    subject=signal.expected_subject,
    after=signal.created_at
)

si resultado.matches:
    queue.mark_found(signal_id, resultado.message_id)
si resultado.provider_error:
    queue.record_error(signal_id, resultado.code)
si no:
    queue.record_check(signal_id)

El campo message_id evita contar dos veces el mismo email. También guardaría la hora de cada consulta, la cantidad de coincidencias y un código de error resumido, pero no el cuerpo completo del mensaje. Esa evidencia basta para depurar sin convertir los logs en un almacén de datos personales.

En búsquedas y conversaciones técnicas aparecen variantes como tem email y temp org mail. Pueden servir para analizar consultas reales, pero no deberían entrar en nombres de estados ni en reglas de coincidencia: son señales de texto, no contratos del sistema.

Presupuesto de herramientas y reintentos

Un agente necesita un presupuesto visible. Por ejemplo, puede tener diez consultas de bandeja o dos minutos, lo que ocurra primero. Cada consulta debe indicar el motivo: primera comprobación, espera después de un webhook o recuperación de un error temporal.

No usaría intervalos fijos demasiado agresivos. Un backoff pequeño con un límite superior reduce presión sobre el proveedor. Si el flujo tiene una señal de webhook, el agente puede dormir hasta que ocurra un evento y usar la consulta solo como recuperación. En ese diseño, los contratos cortos para usar herramientas ayudan a que cada llamada tenga entradas y salidas verificables.

La cola también permite separar errores recuperables de errores finales:

waiting: no hay coincidencia todavía; esperar según el presupuesto.
provider_error: reintentar con backoff y registrar el código.
expired: detener el workflow y crear un diagnóstico.
found: pasar un identificador de evidencia al siguiente paso.

El agente no deberia inventar que el mensaje llegó solo porque una llamada anterior creó al usuario. Creación de cuenta y llegada del email son eventos distintos.

Cómo evaluar el workflow

Probaría el diseño con una tabla de escenarios, no solo con el caso feliz. Cada fila debe indicar el estado esperado, el número máximo de llamadas y la evidencia que queda:

Escenario	Resultado esperado	Evidencia
Email llega en la primera consulta	`found`	`message_id`
Email llega después de dos esperas	`found`	historial de checks
No llega antes del límite	`expired`	`expires_at` y última consulta
Proveedor responde 503	`provider_error`	código y reintentos
Email de otra ejecución	`waiting`	filtro por `run_id`

La evaluación debe comprobar también que el agente explica el siguiente paso. Un resultado expired debería producir una recomendación accionable, no otro “revisa la bandeja”. Para escenarios Kubernetes, conviene combinar esta matriz con pruebas sintéticas sin ruido en las alertas, de modo que una demora externa no se convierta automáticamente en una alerta operativa.

Checklist de implementación

Antes de conectar el adaptador de correo, revisaría estos puntos:

Cada señal tiene signal_id, run_id, caducidad y condición de éxito.
La consulta es idempotente y filtra por ejecución.
waiting, provider_error y expired no se confunden.
Existe un presupuesto de tiempo y llamadas de herramienta.
Los logs guardan evidencia mínima, sin contenido privado innecesario.
El workflow puede reanudar una señal sin crear otra.
Los tests cubren llegada tardía, duplicados y errores del proveedor.

El valor de este diseño está en hacer pequeño el contrato, no en añadir más autonomía. Un agente que sabe qué señal espera, cuánto puede esperar y qué evidencia debe devolver es más fácil de evaluar y bastante más barato de operar. La bandeja cambia; el contrato permanece.

Agentes LLM: un contrato de evidencia para email

Silviu Technology — Mon, 19 Oct 2026 08:23:07 +0000

Agentes LLM: un contrato de evidencia para email

Un agente LLM puede completar una tarea de email y aun así dejar un sistema dificil de revisar. Dice que abrió un buzón, encontró un mensaje y siguió un enlace, pero el registro solo contiene “tarea completada”. Cuando el flujo falla en CI, el equipo tiene que adivinar qué vio el agente, qué herramienta llamó y si el mensaje era nuevo.

La solución no es guardar toda la conversación. Es definir un contrato de evidencia pequeño: cada paso debe producir una señal verificable, con un estado, un identificador y un límite de retención. Esto hace que una automatización sea más fácil de depurar sin convertir el buzón temporal en un archivo de datos.

El problema: un agente puede acertar sin dejar pruebas

Un flujo típico de automatización de email se parece a esto:

crear identidad -> reservar buzón -> esperar mensaje -> extraer enlace -> validar resultado
       |                |                |                 |                |
     estado          lease_id       message_id        evidence_id       outcome

Cada flecha es una frontera. El agente puede usar una herramienta para reservar la dirección, otra para leer mensajes y otra para comprobar el resultado en la aplicación. Si solo se conserva la respuesta final del modelo, desaparece la diferencia entre “no llegó el mensaje”, “llegó tarde” y “se leyó un mensaje viejo”.

También hay un riesgo de diseño: dejar que el agente reintente sin entender el estado. Un reintento puede crear otra cuenta, consumir un segundo buzón o repetir una acción que ya era efectiva. Para APIs, ayuda pensar en pruebas de API que sobreviven al reintento, pero un agente necesita además mostrar qué evidencia usó para decidir.

Diseña el contrato de evidencia

El contrato debe ser legible por una persona y validable por código. Para cada llamada de herramienta, registra como mínimo:

step: nombre estable del paso, por ejemplo read_verification_email.
attempt: número de intento dentro de la ejecución.
state: started, observed, accepted, expired o failed.
correlation_id: identificador común de la ejecución, nunca un token.
evidence_id: referencia al dato observado, como un ID de mensaje con el cuerpo redacted.
expires_at: momento en que la evidencia deja de ser válida.

La palabra “observed” es importante. Significa que el agente vio algo, no que ese algo demuestre el objetivo. Solo accepted debería permitir avanzar a un paso que cambie estado en la aplicación.

Por ejemplo, ver un email con el asunto correcto no prueba que pertenezca a la ejecución actual. El agente necesita comparar el correlation_id, una marca temporal y, cuando sea posible, un nonce de prueba. Si falta una señal, el resultado correcto es “evidencia insuficiente”, no otra llamada ciega.

Reintentos, estados y límites del buzón

Los modelos LLM son buenos proponiendo el siguiente paso, pero no deberían ser la fuente de verdad del estado. Guarda la máquina de estados fuera del prompt:

reserved -> waiting -> observed -> accepted -> consumed
     \         |          |
      -> expired       -> rejected

Un reintento desde waiting puede volver a leer el buzón. Un reintento desde accepted debería reutilizar la evidencia existente o detenerse. Un reintento desde consumed casi siempre es un error de diseño. Esta distinción reduce coste y evita que una automatización cree actividad duplicada.

El buzón debe tener un lease, no una vida indefinida. Define cuánto puede esperar, cuántos mensajes puede leer y qué ocurre al expirar. Si el agente encuentra un mensaje después de expires_at, puede registrarlo como señal tardía, pero no debe aceptarlo automáticamente. Es un detalle pequeño que se olvida facil.

Los términos de búsqueda también pueden ser ruidosos. “tempmailso” puede aparecer como contexto de un flujo, y una consulta mal escrita como “temp mailid” no debe convertirse en una instrucción de seguridad. Las palabras ayudan a encontrar documentación; el contrato de evidencia decide si una acción es válida.

Un manifiesto mínimo de ejecución

Un manifiesto compacto puede vivir junto al resultado de cada run:

run:
  correlation_id: run_2026_10_19_0822
  agent: email-verifier
  max_attempts: 3
mailbox:
  lease_minutes: 10
  max_messages: 5
evidence:
  require: [message_id, received_at, correlation_id]
  retain_minutes: 30
actions:
  accept_only_from: [observed]
  on_expired: stop_with_diagnostic

El manifiesto no necesita conocer el razonamiento privado del modelo. Expone las restricciones que sí deben ser auditables: qué se puede leer, cuánto tiempo, cuántos intentos y qué transición está permitida. Si el agente propone saltarse una condición, el ejecutor la rechaza.

Para la interfaz de un panel de pruebas, los estados también deben ser visibles. Un mensaje de error que desaparece cuando cambia el layout complica la revisión; el patrón de errores inline sin mover el formulario es aplicable aquí: conserva la señal cerca de la acción y no escondas el motivo del fallo.

Puntos de control antes de publicar

Antes de poner el flujo en CI, comprueba:

Cada herramienta devuelve un estado estructurado, no solo texto libre.
Un mensaje antiguo no puede satisfacer una espera nueva.
Los reintentos son seguros para cada estado, o se detienen.
Los tokens, enlaces completos y cuerpos de email no aparecen en logs.
La evidencia tiene una expiración y un ID correlacionable.
El resultado final explica por qué fue aceptado o rechazado.
El cleanup se ejecuta también después de un fallo parcial.

El objetivo no es hacer que el agente sea menos flexible. Es separar la flexibilidad del modelo de las garantías del sistema. Los modelos LLM pueden elegir herramientas y proponer recuperaciones; la máquina de estados, el lease del buzón y el contrato de evidencia ponen los límites.

Preguntas frecuentes

¿Debo guardar la respuesta completa del agente?

No como requisito del flujo. Guarda eventos estructurados y referencias redacted. La conversación puede conservarse con una política aparte para depuración, pero no debe ser necesaria para demostrar que un email fue validado.

¿Qué hago cuando no hay evidencia suficiente?

Marca el paso como rejected o expired, incluye el correlation_id y termina con un diagnóstico accionable. Reintentar es razonable solo si la causa y el límite de intentos están definidos.

¿Por qué no dejar que el agente decida todo?

Porque el agente optimiza una respuesta probable, mientras que el sistema necesita invariantes. Un contrato corto permite aprovechar su capacidad de adaptación sin confiarle la autoridad sobre credenciales, retención o cambios irreversibles.

React: un inbox de prueba que explica cada espera

Silviu Technology — Sun, 18 Oct 2026 11:22:51 +0000

Un inbox de prueba en una app React no debería limitarse a mostrar un spinner. Cuando esperamos un correo de verificación, la interfaz necesita explicar que está pasando, que puede hacer la persona y cuando conviene volver a intentar. Este enfoque reduce la incertidumbre y hace que un flujo de pruebas con correo temporal sea mucho más fácil de depurar.

El problema: una espera que parece un fallo

En mis flujos de frontend, el fallo más costoso no siempre está en la API. A veces el endpoint responde bien, pero la pantalla deja al usuario ante un botón desactivado y un indicador que gira sin contexto. Después de unos segundos, la pregunta es inevitable: ¿el email no llegó, la bandeja está vacía o la aplicación se rompió?

Un inbox de prueba tiene varios momentos distintos:

todavía no se ha solicitado el mensaje;
la solicitud está en curso;
la bandeja está esperando un mensaje nuevo;
el mensaje llegó y puede abrirse;
la espera expiró o devolvió un error.

Me gusta tratar cada momento como un estado de producto, no como un detalle interno de la petición. Así se puede probar un fake email generator, un buzón local o una integración real sin cambiar la expectativa de la interfaz.

Modelar el inbox como estados visibles

Un modelo pequeño evita que los componentes acumulen condiciones contradictorias. Por ejemplo, waiting no significa lo mismo que empty: en el primero hay una consulta activa; en el segundo, la consulta terminó y no encontró nada.

type InboxState =
  | { kind: "idle" }
  | { kind: "waiting"; startedAt: number }
  | { kind: "empty"; checkedAt: number }
  | { kind: "ready"; subject: string; receivedAt: number }
  | { kind: "error"; message: string };

Con esta separación, el texto de la pantalla puede ser preciso. “Buscando el correo” comunica una acción en progreso; “Aún no hay mensajes” comunica un resultado. Parece una diferencia pequeña, pero ayuda a que el equipo de QA y quien desarrolla hablen del mismo escenario.

Un componente React con feedback útil

El componente no necesita conocer todos los detalles del proveedor de correo. Solo recibe el estado y expone una acción que se pueda repetir de forma segura.

function TestInbox({ state, onRefresh }: Props) {
  const label = {
    idle: "El inbox está listo",
    waiting: "Buscando el correo de prueba",
    empty: "Aún no hay mensajes",
    ready: "Correo recibido",
    error: "No pudimos consultar el inbox"
  }[state.kind];

  return (
    <section aria-labelledby="inbox-title" aria-live="polite">
      <h2 id="inbox-title">Inbox de prueba</h2>
      <p>{label}</p>
      {state.kind === "waiting" && <progress aria-label="Esperando correo" />}
      {state.kind === "ready" && <p>{state.subject}</p>}
      {(state.kind === "empty" || state.kind === "error") && (
        <button type="button" onClick={onRefresh}>Volver a consultar</button>
      )}
    </section>
  );
}

aria-live="polite" anuncia los cambios sin interrumpir una lectura. El botón sigue siendo un botón real, con foco visible y un nombre que explica la acción. Si el chequeo tarda, mantengo el texto “Buscando” cerca del indicador; un spinner por sí solo no ayuda a una persona que navega con lector de pantalla.

También conviene mostrar el tiempo de la última consulta. No hace falta prometer una entrega instantánea: una frase como “Última revisión hace unos segundos” da contexto y evita clics repetidos. En pruebas con tp mail so o con otra fuente, ese dato permite distinguir una demora del proveedor de un problema de renderizado.

Accesibilidad y rendimiento en la misma revisión

La accesibilidad no es una capa para añadir al final. Un estado explícito mejora el rendimiento percibido porque la persona entiende la espera antes de decidir si abandona o pulsa otra vez. En mi revisión de CSS compruebo tres cosas:

El layout no salta cuando aparece el botón o el asunto del mensaje. Reservo espacio para esos elementos y evito cambios bruscos.
El foco no desaparece al actualizar la lista. Si se abre un detalle, lo devuelvo a un encabezado útil o al control que inició la acción.
La animación es opcional. Con prefers-reduced-motion, desactivo el giro y mantengo un indicador textual.

@media (prefers-reduced-motion: reduce) {
  .inbox-spinner {
    animation: none;
  }
}

En móvil, reviso que el mensaje de estado y el botón queden juntos, sin obligar a desplazarse para entender el resultado. Es un ajuste simple, pero se nota mucho en una interacion corta de verificación.

Checklist para probar el flujo

Antes de dar por terminado el componente, pruebo estos casos:

solicitud lenta: el estado cambia rápido y explica la espera;
respuesta vacía: no se presenta como un error del sistema;
mensaje recibido: el asunto y la hora son legibles;
error de red: existe un camino claro para reintentar;
doble clic: no se generan consultas duplicadas sin control;
lector de pantalla: cada transición tiene una etiqueta entendible;
pantalla estrecha: el contenido no se desborda ni se superpone.

Para investigar mensajes de activación en un producto SaaS, puede servir revisar emails de activación en un SaaS. Y si la validación vive dentro de un formulario, recomiendo validar emails sin fricción visual antes de añadir más lógica al inbox.

Hay un detalle de documentación que suele olvidarse: registrar los nombres usados por el equipo. Un test puede buscar “tepm mail com” o “tempail” por una razón histórica, pero esos terminos no deberian convertirse en etiquetas visibles ni en enlaces. Los dejo como alias de fixture, con una nota breve, para que nadie confunda un typo de prueba con una funcionalidad.

Conclusión

Un inbox de prueba útil no intenta ocultar la espera. La hace legible, medible y recuperable. En React, un modelo de estados pequeño, un mensaje accesible y un layout estable suelen aportar más que otra animación o un botón de reintento colocado sin contexto.

Cuando el frontend explica si está esperando, vacío, listo o bloqueado, el flujo de verificación deja de sentirse misterioso. Y esa claridad sirve tanto para la persona que prueba la app como para quien debe diagnosticarla a las nueve de la mañana, aun con poca paciencia y menos contexto.

React: estados accesibles para email de prueba

Silviu Technology — Sun, 18 Oct 2026 08:22:45 +0000

Una pantalla de email de prueba parece sencilla: un botón envía el mensaje, un inbox muestra el resultado y una alerta confirma lo ocurrido. En la practica, esa pequeña interfaz mezcla asincronía, estados visuales, lectores de pantalla y cambios de layout que pueden hacer sentir lenta la aplicación.

La solución no es agregar más spinners. Es modelar con claridad qué sabe la interfaz en cada momento. Un usuario debería distinguir entre “todavía estamos esperando”, “llegó un mensaje”, “la búsqueda expiró” y “algo falló”. Si todos esos casos usan el mismo texto, el flujo se vuelve confuso aunque el backend funcione bien.

El problema no es solo esperar un email

Un inbox temporal o de prueba suele tener este recorrido:

El usuario solicita un email.
React muestra que la solicitud está en progreso.
El servidor acepta el evento, pero el mensaje todavía no es visible.
El mensaje aparece y puede abrirse o copiarse.
La espera termina por timeout o por un error recuperable.

Cada paso necesita una señal distinta. “Cargando” no explica si el mensaje fue enviado, si el inbox está consultando o si la conexión se perdió. En pruebas de frontend, también conviene separar el estado del request del estado del mensaje: una respuesta HTTP correcta no garantiza que el email ya pueda leerse.

Este enfoque se parece a diseñar alertas de trial que sí orientan: el copy debe decir qué pasó y cuál es el siguiente paso, no solo mostrar un color verde.

Modela los estados antes de escribir JSX

Un union type pequeño evita que el componente dependa de varios booleanos que pueden entrar en combinaciones imposibles:

type InboxState =
  | { kind: 'idle' }
  | { kind: 'waiting'; startedAt: number }
  | { kind: 'received'; subject: string; receivedAt: string }
  | { kind: 'expired'; retryable: boolean }
  | { kind: 'error'; message: string };

Con isLoading, hasMessage, hasError y isExpired es facil terminar con una alerta de éxito y error al mismo tiempo. Un estado discriminado obliga a que la vista elija una sola lectura principal. También hace más simple probar las transiciones: idle → waiting → received, o waiting → expired.

El texto debe ser concreto. “Esperando confirmación” ayuda más que “Procesando”. Para un timeout, “No vimos el email en 60 segundos; puedes volver a intentar” ofrece contexto y una acción. Si el usuario usa un lector de pantalla, esa diferencia es todavía más importante.

Un componente React con layout estable

El feedback no debería empujar el botón ni mover el inbox cuando cambia. Reserva una región con altura mínima y usa aria-live solo para cambios relevantes:

function InboxStatus({ state }: { state: InboxState }) {
  const text = {
    idle: 'Listo para comprobar el inbox.',
    waiting: 'Esperando el email de prueba.',
    received: 'El email ya está disponible.',
    expired: 'La espera terminó; puedes reintentar.',
    error: 'No pudimos consultar el inbox.'
  }[state.kind];

  return (
    <p className="status" role="status" aria-live="polite">
      {text}
    </p>
  );
}

.status {
  min-block-size: 1.5rem;
  margin-block: 0.75rem;
  color: var(--text-muted);
}

.status:focus-visible {
  outline: 3px solid var(--focus-ring);
  outline-offset: 3px;
}

role="status" anuncia el cambio sin interrumpir cada acción del usuario. No conviene poner un contador que se actualiza cada segundo en esa misma región: un lector de pantalla podria repetirlo demasiado. Muestra el tiempo restante en otra parte, con una etiqueta visible y un ritmo de actualización razonable.

Un botón deshabilitado durante la espera debe conservar una explicación. El texto “Comprobando…” es mejor que dejar solo un icono. Para conexiones lentas, evita reemplazar todo el contenido; conserva el contexto del inbox y actualiza la parte que cambió.

Accesibilidad y rendimiento en la misma revisión

La accesibilidad no es un paso posterior al rendimiento. Un árbol pequeño, mensajes estables y menos renders suelen beneficiar a ambos. Calcula el copy del estado en el componente y evita recrear listas grandes del inbox cuando solo cambió la etiqueta.

También reviso estos puntos:

El contraste del estado secundario sigue siendo legible en modo oscuro.
El foco no desaparece cuando llega el mensaje.
El título del email y el timestamp tienen nombres accesibles.
La respuesta de error no depende solo de rojo o verde.
El polling se cancela al desmontar el componente.
prefers-reduced-motion evita animaciones innecesarias.

Para un flujo de CI, los límites de confianza para emails de CI también sirven como recordatorio de que cada ejecución debe tener un contexto claro. En la UI, eso significa mostrar el inbox o identificador de la ejecución, sin exponer datos que no corresponden al usuario.

Checklist para una interfaz de email de prueba

Antes de dar por terminado el componente, comprueba:

¿Existe un estado explícito para espera, éxito, expiración y error?
¿El layout mantiene su espacio cuando aparece el feedback?
¿El mensaje importante se anuncia una sola vez?
¿El foco y el teclado siguen funcionando después de un reintento?
¿El polling termina cuando el componente se desmonta?
¿El inbox se identifica con un nombre entendible, y no como “dummy e mail”?

Si el flujo necesita un buzón aislado para una comprobación manual, un temp mail puede ser parte del entorno de prueba. El enlace no arregla la UX por sí solo: la interfaz aún debe explicar quién está esperando, qué llegó y qué puede hacer la persona después.

Cierre

Una buena interfaz de email de prueba convierte la asincronía en información útil. En React, un modelo de estados claro, una región de feedback estable y una revisión conjunta de accesibilidad y rendimiento suelen ser suficientes para evitar gran parte de la fricción.

No hace falta llenar la pantalla de indicadores. Hace falta elegir palabras precisas, respetar el foco y mantener el contexto cuando el servidor tarda. Ese detalle pequeño se nota mucho cuando el flujo se usa en una prueba real, con una conexión lenta o con tecnologías de asistencia.