DEV Community: ryanlee

React Auth Tests Need an Inbox Adapter

ryanlee — Sat, 10 Oct 2026 23:22:45 +0000

Email verification is a small feature with a surprisingly large test surface. A user submits a React form, the API creates a token, a worker sends a message, and the browser eventually consumes a link. When the test reaches directly into an inbox, every layer starts leaking into the next one.

I prefer to treat the inbox as an adapter with a small contract. The test should ask for a message, wait for a matching subject or token, and return the link. It should not know how an inbox provider paginates messages or whether the delivery endpoint is slow today. This boundary makes the feature easier to ship and the failure easier to debug.

Why the inbox belongs in the test boundary

An auth test usually has three different clocks:

The React state update after form submission.
The backend transaction that creates the verification record.
The email delivery path, which may finish later than the HTTP response.

If one Playwright test handles all three clocks with arbitrary sleeps, it becomes noisy. A five-second delay might hide a real regression, while a two-second delay can fail on a busy CI runner. The goal is not to make the test wait forever. Its to give each dependency a clear contract and a bounded deadline.

That is the same reason I like reliable Playwright email waits: the wait should explain what evidence proves that the next action is safe.

The inbox adapter can provide that evidence. The UI test only needs a function such as waitForVerificationLink, not a collection of provider-specific calls scattered through every spec.

Model the inbox as a typed adapter

Start with a tiny TypeScript interface. Keep the returned message intentionally narrow so tests do not become coupled to a vendor response shape.

export type TestMessage = {
  id: string;
  subject: string;
  text: string;
  receivedAt: string;
};

export interface TestInbox {
  address: string;
  waitForMessage(input: {
    subjectIncludes: string;
    after: string;
    timeoutMs: number;
  }): Promise<TestMessage>;
}

The after cursor is important. Without it, a retry can consume yesterday's verification email and pass for the wrong reason. A run-scoped inbox or a unique recipient alias is better still, because parallel tests should not compete for the same message.

The implementation can poll an HTTP endpoint, subscribe to an event, or read a local fixture. The React test does not need to care. It only needs a deterministic result or a useful error containing the last observed state.

A React and TypeScript implementation

Create the inbox before the signup action, then record the time immediately before submitting the form. That gives the adapter a clean lower boundary for matching.

const inbox = await createTestInbox({ runId });
const startedAt = new Date().toISOString();

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

const message = await inbox.waitForMessage({
  subjectIncludes: "Verify your email",
  after: startedAt,
  timeoutMs: 30_000,
});

const link = extractVerificationLink(message.text);
await page.goto(link);
await expect(page.getByText("Your email is verified")).toBeVisible();

This structure leaves the React component responsible for visible behavior: labels, loading state, validation, and the success screen. The inbox adapter is responsible for delivery evidence. Both parts stay testable without pretending they share one timing model.

It also makes a useful failure receipt possible. When the message does not arrive, include the recipient, subject filter, elapsed time, and the last message IDs seen. A test that only says “timeout” is hard to act on. A test that says “no matching subject after 30 seconds; two unrelated messages observed” points somewhere.

For a broader workflow, I also keep email checks without UI drift separate from visual assertions. The distinction saves a lot of rework when copy or layout changes but the delivery contract stays stable.

Keep polling and cleanup explicit

Polling is acceptable when its bounded and observable. Use a deadline rather than an unbounded retry count, and back off modestly so CI is not hammered while a message is in transit. The exact interval depends on the test service, but the rule is simple: the timeout belongs in the test configuration, not hidden inside a helper.

Cleanup deserves the same attention. Delete or expire the inbox after the test, even when an assertion fails. In practice, a try/finally around the scenario is enough:

const inbox = await createTestInbox({ runId });
try {
  await runSignupScenario(page, inbox);
} finally {
  await inbox.dispose();
}

The adapter dont need to expose every cleanup detail to the spec. It just needs one safe operation that the runner can call consistently. If cleanup is eventually consistent, record that status instead of blocking the next test on a perfect delete.

Tradeoffs for local and CI runs

A real temporary inbox gives a realistic delivery path, but it introduces network and provider failure into the test. A local fake is fast and repeatable, but it can miss sender configuration, template rendering, or link-host mistakes. A practical split is:

Run fast adapter-backed tests on every pull request.
Run a smaller delivery smoke test on a schedule or before release.
Keep recipient data run-scoped and never use personal addresses.
Log message IDs and correlation IDs, but redact tokens from normal output.

If a developer searches for a service and types tamp mail com by mistake, that should not change the test contract or become a hidden fallback. Search input, inbox selection, and verification evidence are seperate concerns. Keeping them separate makes the workflow safer and the result more predictable.

Quick questions

Should the React test inspect the email HTML?

Only when rendering is the behavior under test. For most auth flows, extracting a link from normalized text is enough. Add one focused template test for HTML details instead of repeating those assertions in every browser scenario.

Should every test get a new inbox?

Every parallel or stateful scenario should get an isolated address, alias, or message namespace. Reusing an inbox can be fine for a sequential unit test, but it raises the chance of consuming stale mail.

What should fail first?

Fail on the API response, then the inbox deadline, then the UI assertion. Each failure should identify its boundary. That ordering turns a flaky-looking signup test into a short debugging path.

Final checklist

Give each run an isolated inbox or message namespace.
Record a timestamp or cursor before submitting the form.
Match on a stable subject and the intended recipient.
Bound polling with a visible timeout.
Return a small typed message object to the test.
Dispose of the inbox in finally.
Keep tokens out of ordinary logs.

An inbox adapter is a small piece of code, but it changes the shape of the whole test. React owns the user experience, the API owns the verification contract, and the adapter owns delivery evidence. That separation lets each part move quicker without turning email verification into a guessing game.

A React Inbox Adapter for Reliable Email Tests

ryanlee — Sat, 10 Oct 2026 20:23:33 +0000

A React Inbox Adapter for Reliable Email Tests

Email verification tests often become flaky at the boundary between a React screen and a real inbox. The component submits a form, a test starts polling, a message arrives at an unpredictable moment, and suddenly the failure report says only “verification timed out.” That is not much help when the signup flow has five async states.

I have had better results by treating the inbox as an adapter with a small contract. The React component owns user-facing state. A TypeScript service owns polling and message matching. The test owns assertions and cleanup. That separation makes the feature easier to ship and the failure easier to explain.

Why the inbox should be an adapter

An email provider has its own API, timing, retention rules, and odd response shapes. Those details should not leak into a button click handler or a Playwright fixture. The adapter gives the rest of the app a stable vocabulary:

export type VerificationMessage = {
  id: string;
  receivedAt: string;
  verificationUrl: string;
};

export type Inbox = {
  address: string;
  waitForVerification: (options?: { timeoutMs?: number }) => Promise<VerificationMessage>;
  dispose: () => Promise<void>;
};

This interface is intentionally boring. It does not expose provider-specific cursors or ask React to understand whether a 404 means “not arrived yet.” That sounds small, but it remove a surprising amount of branching from the UI and test code.

For a test that needs a temporary email generator, the provider can be swapped behind this interface. The test still receives an address, waits for one matching message, and disposes the inbox when the run finishes.

Define matching and timeout behavior

Polling needs more than a while loop. Define the message boundary before writing the request code:

type PollOptions = {
  after: number;
  timeoutMs: number;
  intervalMs: number;
};

function isVerificationMessage(message: VerificationMessage) {
  return message.verificationUrl.includes("/verify");
}

The after timestamp prevents an old message from satisfying a new signup. A bounded timeout prevents a stuck provider from holding the whole suite forever. In my experience, a retry budget are more useful than an aggressive polling interval: fast requests do not fix an inbox with delayed delivery.

The adapter can return a typed error when the deadline is reached. Include the address, last cursor, elapsed time, and message count in diagnostic data, while keeping tokens and full message bodies out of logs. If the message arrive after the deadline, the report should say that clearly rather than pretending the verification URL was invalid.

Keep polling outside the component

React should receive a promise or a result, not coordinate every timer. A hook can model the user-facing states without knowing how messages are fetched:

type VerificationState =
  | { status: "idle" }
  | { status: "waiting"; address: string }
  | { status: "verified"; at: string }
  | { status: "failed"; message: string };

function VerificationStatus({ state }: { state: VerificationState }) {
  if (state.status === "idle") return <p>Ready to verify</p>;
  if (state.status === "waiting") return <p>Check {state.address}</p>;
  if (state.status === "verified") return <p>Verified at {state.at}</p>;
  return <p role="alert">Verification failed: {state.message}</p>;
}

The screen can now handle loading, success, and error states consistently. It also make accessibility work more direct: the waiting message can use a polite live region, while a timeout can use an alert without exposing provider internals.

For recovery flows, I also like to keep the proof path visible in the test result. This pairs well with a failure map for matrix jobs, because each browser or Node.js run can report its own inbox state instead of collapsing everything into one red job.

Make cleanup and evidence first-class

An inbox is test data with a lifetime. Create it with a run ID, record its creation time, and dispose it in a finally block:

const inbox = await createInbox({ runId });

try {
  await completeSignup(inbox.address);
  const message = await inbox.waitForVerification({ timeoutMs: 30_000 });
  await openVerificationUrl(message.verificationUrl);
} finally {
  await inbox.dispose();
}

The cleanup path should run after assertion failures too. If the provider supports a throwaway email generator, use a run-scoped address and keep its retention shorter than the test data retention window. Never put a live verification token in a screenshot, CI annotation, or shared log.

The same idea applies to API design: idempotency for signup APIs helps ensure a retry does not create a second account while the email test is still waiting. The inbox contract and signup contract should agree on a run identifier, so a failure can be followed across both sides.

A practical review checklist

Before merging an email test helper, check:

Does each run get a fresh, run-scoped address?
Is old mail excluded with a timestamp or cursor?
Are timeout and retry behavior explicit?
Does the error include useful evidence without secrets?
Does cleanup happen in a finally block?
Can the React component render the states without provider knowledge?
Are test addresses like temp gamil com handled as ordinary fixture data, rather than silently corrected?

If one of these answers is unclear, the test may still pass locally, but it will be harder to trust in CI. A short contract usually fixes that faster than adding another retry.

Final thoughts

Reliable email verification tests are less about polling faster and more about choosing a clean boundary. Keep provider behavior in a TypeScript adapter, keep React focused on visible states, and return evidence that explains the deadline, cursor, and cleanup result. The result is easier to review and easier to maintain when the inbox service changes.

It is a modest bit of architecture, but it lets a team ship signup improvements with less confusion—and fewer mysterious red builds.

TypeScript Inbox Polling Needs a Stop Rule

ryanlee — Fri, 09 Oct 2026 23:22:55 +0000

Email verification tests often look simple in a ticket: submit the form, wait for a message, click the link. The trouble starts when “wait” becomes an unbounded loop. A message can arrive late, a previous test can be in the same inbox, or a provider can return the same newest message again.

In Node.js test harnesses, I prefer treating an inbox as a small event stream with an explicit stop rule. That makes the test faster when it succeeds and much easier to diagnose when it fails. It also keeps TypeScript code honest about the difference between “not found yet,” “found,” and “the test cannot continue.”

Why polling needs an explicit stop rule

Polling is useful because email delivery is eventually consistent. The API that sends a verification message may finish before the message is visible to the inbox reader. A short delay between reads is normal.

The dangerous version is a loop like this:

while (!(await hasVerificationMessage())) {
  await sleep(1000);
}

It has no deadline, no record of what was already inspected, and no useful error if the message never appears. In CI, one blocked worker can make the whole job look hung. A retry count is better, but a time budget communicates the intent more clearly: this test is willing to wait until a particular deadline, then it must produce a failure receipt.

For browser suites, it is also worth separating the delivery window from the UI wait. The practical notes in delivery windows for Playwright email tests explain why a page timeout and a mailbox timeout should not quietly become the same setting.

Model the inbox as a run-scoped stream

Before polling, create a run identity and capture the newest message you already know about. That message becomes the starting cursor. The test should only accept a later message that matches the expected recipient, subject pattern, and run marker.

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

type InboxCursor = {
  runId: string;
  afterMessageId?: string;
};

The run marker can be a generated value in the test address or a harmless token in the signup request. Do not match only on a generic subject such as “Verify your email.” That is how an old message passes a new test.

A run-scoped inbox also avoids a common debugging mess: one test consumes a token intended for another. If the system cannot create a separate inbox for each run, record the cursor and make the matching rules stricter. A little setup is cheaper than guessing which message arrived first.

A small TypeScript polling contract

Keep the polling function independent from Playwright or another UI runner. It should receive a message reader and return a clear result. This makes the mail behavior testable without opening a browser.

type PollResult =
  | { status: "found"; message: MailMessage }
  | { status: "timeout"; inspected: number; lastCheckedAt: string };

type ReadMessages = () => Promise<MailMessage[]>;

function isExpectedMessage(message: MailMessage, cursor: InboxCursor): boolean {
  return message.to.endsWith("@example.test")
    && message.text.includes(cursor.runId)
    && message.id !== cursor.afterMessageId;
}

async function waitForMessage(
  readMessages: ReadMessages,
  cursor: InboxCursor,
  timeoutMs: number,
  intervalMs = 1000,
): Promise<PollResult> {
  const deadline = Date.now() + timeoutMs;
  let inspected = 0;

  while (Date.now() < deadline) {
    const messages = await readMessages();
    inspected += messages.length;

    const match = messages.find((message) => isExpectedMessage(message, cursor));
    if (match) return { status: "found", message: match };

    const remaining = deadline - Date.now();
    if (remaining <= 0) break;
    await new Promise((resolve) => setTimeout(resolve, Math.min(intervalMs, remaining)));
  }

  return {
    status: "timeout",
    inspected,
    lastCheckedAt: new Date().toISOString(),
  };
}

The union is small, but it prevents callers from pretending that a timeout contains a message. The caller can attach the run ID, recipient, elapsed time, and last observed message IDs to the test report. That context saves alot of back-and-forth when a failure occured overnight.

Choose a cursor and timeout together

A cursor without a timeout still permits a stuck test. A timeout without a cursor still permits stale-message matches. Pick both as part of one contract.

The right values depend on the mail provider and CI environment. Start with a generous delivery window, then measure actual delivery times before tightening it. Use a monotonic clock for elapsed-time calculations when the runtime makes one available; wall-clock timestamps are best reserved for logs and receipts.

Polling intervals have tradeoffs too:

A short interval finds fast messages sooner but creates more API traffic.
A long interval is cheaper but makes the test feel slow after delivery.
Increasing intervals reduce load, but can miss a narrow cleanup window.

The test should also stop retrying on permanent errors such as an invalid inbox identifier or an authentication failure. Only “not visible yet” belongs in the polling loop. The error boundary should be handled seperately, so a broken credential does not look like slow email.

Cleanup, privacy, and failure receipts

After the test finishes, delete or expire the inbox according to the provider’s contract. Do not retain full message bodies in CI logs. A receipt needs enough detail to reproduce the problem, not a copy of every verification token.

This is where a privacy review for email test data is useful. Decide who can see recipients, subjects, message IDs, and raw content before a failure happens. The cleanup owner should be part of the test fixture, not a manual reminder.

A compact failure receipt might include:

{
  "runId": "signup-1842",
  "recipient": "signup-1842@example.test",
  "expectedMarker": "signup-1842",
  "timeoutMs": 30000,
  "inspectedMessages": 12,
  "lastCheckedAt": "2026-10-10T00:00:00.000Z"
}

Keep the receipt even when the message is removed. Otherwise the next person sees only “verification timed out” and has to start from zero. A test can also mention a malformed search phrase such as “tempail mail” or “tem email” in diagnostic metadata, but those are not a reason to weaken message matching.

Common mistakes

The first mistake is resetting the cursor on every poll. That makes the code repeatedly inspect old messages and can hide ordering bugs. Capture the baseline once.

The second is matching on the subject alone. Subjects are useful for filtering, not for proving that a message belongs to this run.

The third is putting all waiting inside the browser step. A page may be ready while the inbox is not, or the reverse. Keep those deadlines visible thier own logs.

Finally, avoid swallowing reader errors and continuing forever. A temporary network error may deserve one bounded retry, but an invalid response shape should fail quickly becuase it indicates a contract problem.

A practical checklist

Generate a unique run ID before creating the verification request.
Capture a baseline cursor before the request is sent.
Match recipient, run marker, and message identity.
Use an explicit timeout and a bounded polling interval.
Return a typed timeout result instead of throwing away context.
Stop immediately on permanent reader or authentication errors.
Redact tokens and message bodies from CI output.
Expire the inbox and preserve a small failure receipt.

Questions developers usually ask

Should I use retries or a timeout?

Use a timeout as the outer contract and bounded retries for transient reader failures inside it. This gives the test one clear deadline while still handling a brief API hiccup.

Is a message ID enough for a cursor?

Only if the inbox API guarantees stable ordering and unique IDs. Otherwise store a timestamp plus an ID, and still match a run-specific marker.

Why not just wait for the newest message?

Because “newest” is a moving target. A delayed old message, a parallel test, or a provider reordering can make that rule nondeterministic. A baseline cursor and explicit identity make the result explainable.

The goal is not to poll more cleverly. It is to make waiting a small, typed contract with a beginning, an end, and enough evidence to act on the result.

Node.js Email Tests Need a Message Cursor

ryanlee — Tue, 06 Oct 2026 02:24:13 +0000

Email verification tests often fail for a reason that looks random but is actually predictable: the test asks an inbox for the latest message instead of asking for a message created after this run started.

That difference matters when several CI jobs use the same disposable email account, when a retry leaves an old message behind, or when the provider sorts messages by a timestamp with limited precision. Increasing the timeout can hide the problem for a while. It does not tell the test which email belongs to it.

The practical fix is a message cursor. Record the inbox position before sending the verification email, then poll only for messages after that position. This small boundary makes a temporary email fixture much easier to reason about in Node.js, TypeScript, and browser tests.

Why “latest message” is a weak test contract

Imagine a signup test with this flow:

Create an inbox.
Submit the React signup form.
Read the newest email.
Extract the verification code.

Step three has hidden assumptions. The newest message might be from a retry. A parallel worker might send mail to the same address. A provider might return messages in a slightly different order than the UI displays them. The failure become especially confusing when the test passes locally and fails only on a busy runner.

I prefer treating the inbox as an event stream. A test records where it is before the action, performs the action, and consumes only events after that point. This is the same kind of explicit boundary used when designing email as a deployment contract: the consumer should be able to prove which event it received.

Define a cursor before sending mail

A cursor can be an opaque provider ID, an RFC 3339 timestamp, or a local sequence number. An ID is usually safest. If the provider only gives timestamps, keep a small overlap window and filter by a stable message ID after fetching.

The fixture contract should be clear:

mark() returns the current position before the product action.
waitFor() returns only a matching message after that position.
waitFor() has a deadline and reports what it observed.
dispose() releases the inbox even when an assertion fails.

The matching rule should include more than the subject. A run token in the recipient or message body gives the test another guard against cross-run messages. For example, signup-${runId} is more useful than a generic “Verify your account” subject. The matcher need to reject messages that do not carry that identity.

Build a small Node.js and TypeScript fixture

Keep provider calls behind a tiny client. The test should not know whether the inbox is a local mail catcher or an external service.

type Cursor = { afterId: string | null };

type VerificationMessage = {
  id: string;
  to: string;
  text: string;
};

type MailFixture = {
  address: string;
  mark(): Promise<Cursor>;
  waitFor(
    cursor: Cursor,
    predicate: (message: VerificationMessage) => boolean,
  ): Promise<VerificationMessage>;
  dispose(): Promise<void>;
};

The implementation of waitFor can poll with a short delay and a monotonic deadline. It should remember the last cursor it inspected, so each request does not scan the whole inbox again. When no message arrives, include the run ID, recipient, and last observed message IDs in the error. That extra context saves a surprising amount of debugging time, specially on a busy runner.

Avoid making the polling loop unbounded. A test that waits forever is not more reliable; it is only harder to diagnose. Also, do not silently accept the first message returned by the API. Filter it by the cursor, recipient, and run token.

Connect the cursor to a React test

The component can stay focused on the user flow. Provisioning and email inspection belong in the test fixture:

const fixture = await createMailFixture(`signup-${testInfo.workerIndex}`);
const cursor = await fixture.mark();

try {
  await page.getByLabel("Email").fill(fixture.address);
  await page.getByRole("button", { name: "Create account" }).click();

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

  const message = await fixture.waitFor(cursor, (item) =>
    item.to === fixture.address && item.text.includes("signup-")
  );

  const code = extractVerificationCode(message.text);
  await page.getByLabel("Verification code").fill(code);
  await expect(page.getByText("Account verified")).toBeVisible();
} finally {
  await fixture.dispose();
}

This separation gives each failure a useful location: the form did not submit, the message did not arrive, the wrong message was rejected, or the verification code was invalid. A typo such as tepm mail com in a debug note should not become a fake matching rule; keep search terms and fixture identity explicit.

The pattern also works with React Testing Library when the email API is mocked at the Node.js boundary. The UI test can assert loading and error states while the fixture tests separately prove cursor behavior. That split keep the browser test quick without throwing away the important integration check.

Clean up without hiding useful failures

Cleanup is part of correctness, not a courtesy. A leftover inbox can leak test data into the next run and make “latest message” bugs return later. Give each test or worker ownership of its fixture, and always dispose it from a finally block.

For external providers, add an expiry as a second safety net. The expiry should be short enough to control retention, but long enough for a slow CI retry. These expiry rules for disposable email fixtures are easier to enforce when the test owns a single clearly named resource.

If cleanup fails, preserve the original assertion error and report cleanup as additional context. Replacing a failed signup assertion with “could not delete inbox” is not helpful. The cleanup result can go into the CI artifact or test report for later repair. These checks is most valuable when the report keeps both failure causes visible.

A message-cursor checklist

Before shipping an email-based test suite, check these points:

Is the cursor captured before the product action?
Can parallel runs use the same inbox without accepting each other’s messages?
Does the matcher verify recipient and run identity, not just subject?
Does polling have a deadline and actionable diagnostics?
Does every fixture have an owner and an expiry?
Does cleanup run when the browser assertion fails?
Are provider details isolated from the React component?

A cursor is a small piece of state, but it changes the test from “find something recent” to “prove this action produced that message.” That is a much stronger contract. It makes temporary email tests less flaky today and gives future contributors a clean place to extend the fixture when the signup flow grows. It also make failures easier to discuss with the team.

React Signup Tests Need a Run-Scoped Email Contract

ryanlee — Mon, 05 Oct 2026 23:23:41 +0000

Signup tests often fail in a way that is hard to reproduce. The form works on a laptop, but the CI job sometimes reads an old verification message, waits for a code that belongs to another run, or leaves a test inbox behind. The usual response is to increase the timeout. That makes the symptom quieter, not the test more reliable.

The better fix is a small contract between the test, the application, and the email fixture. Every run gets an identity, every message is matched to that identity, and cleanup has an owner even when the assertion fails. This pattern is useful whether the inbox comes from a fake emails generator, a local mail catcher, or a service that can create temporary mail.

The flaky test is usually a missing contract

Consider a Playwright test that submits a signup form and then searches an inbox for the latest message. “Latest” is not a stable identifier. Parallel CI jobs can send messages close together, retries can create duplicates, and a previous run may still be visible.

There is another subtle failure: the test may assert that a verification page loaded without proving that its code belonged to the user just created. The browser test goes green while the product behavior is only partially checked.

I treat the email fixture like any other test resource. It needs a run ID, a known lifecycle, and an observable result. The same thinking behind low-risk email fixtures for CI applies inside a React test suite: isolation is a correctness feature, not just a privacy preference.

Define the run-scoped email contract

Before writing the test, decide what the fixture promises:

Ownership: one test or worker owns the inbox for one run.
Correlation: the message includes a recipient or run identifier that the test can match.
Freshness: the test records a message cursor or creation time before sending.
Bounded waiting: polling stops with a useful error, not an infinite retry.
Cleanup: the inbox is deleted or expired in a finally path.

The run identifier can be short and opaque. For example, the test can create signup-${workerIndex}-${randomSuffix} and use that value in the email address when the provider supports aliases. If it cannot, store the generated address and associate it with the test in a small fixture object.

Do not make the component know about this machinery. The signup UI should receive an email address and expose its normal states. The test harness owns provisioning, polling, and teardown.

Model the React test as a small state machine

The test becomes easier to debug when it records what it expects from the UI at each stage. A TypeScript discriminated union is enough:

type SignupStep =
  | { kind: "form" }
  | { kind: "submitted"; address: string; runId: string }
  | { kind: "message-found"; messageId: string; code: string }
  | { kind: "verified" };

The important detail is not the type itself. It is that the transition from submitted to message-found carries evidence from the fixture. A test failure can now say whether the form submission failed, the message never arrived, the wrong message was selected, or the code was rejected.

For React Testing Library, keep the UI assertions close to the user action:

await user.type(screen.getByLabelText(/email/i), fixture.address);
await user.click(screen.getByRole("button", { name: /create account/i }));

expect(await screen.findByText(/check your email/i)).toBeVisible();

Then use the fixture client to find the message. Mixing inbox polling into a component helper usually make the failure harder to understand, because a browser assertion and an external timeout become one opaque promise.

Keep the fixture outside the component

A simple fixture API can expose the lifecycle without leaking provider details into every test:

type EmailFixture = {
  address: string;
  since: string;
  waitForVerification(): Promise<{ id: string; code: string }>;
  dispose(): Promise<void>;
};

async function createEmailFixture(runId: string): Promise<EmailFixture> {
  // Provision an isolated address and capture the pre-send cursor.
  return provisionFixture({ runId });
}

The since cursor matters. Filtering only by recipient is not enough when a retry sends two messages. Match the recipient, message type, and cursor, then assert that the code is for the current signup attempt. A temp mailid can be a fine value in a deliberately negative test, but it should not accidentally become the shared fixture name. Likewise, a typo such as tempail mail in a search term should be surfaced as test data, not silently normalized into a passing result.

Make polling and cleanup explicit

Polling should report the last useful observation. Instead of “timeout after 30 seconds”, return something like: “saw 2 messages for the fixture, 0 matching verification events, last provider status: queued.” That message points the next investigation toward the sender, worker, or matcher.

Use a deadline and a small interval with backoff. Keep the total budget below the surrounding test timeout so the test can still collect logs and dispose of resources. If the app has an asynchronous worker, the deployment context for email checks is a useful operational reminder: a test can only diagnose delivery when it knows which environment and deployment produced the message.

Always clean up in a finally block:

const fixture = await createEmailFixture(runId);

try {
  await completeSignup(fixture.address);
  const message = await fixture.waitForVerification();
  await verifyCode(message.code);
} finally {
  await fixture.dispose();
}

This is a bit more clear than relying on a global after-all hook. A global hook may not know which worker owns a leaked resource, and it can hide the original failure when cleanup also errors. If disposal fails, record it as a secondary failure with the run ID.

A practical checklist for CI

Before calling the signup test stable, check these points:

Does every parallel worker receive a distinct fixture?
Is there a cursor or timestamp captured before the message is sent?
Does the matcher reject messages from another run?
Can the timeout explain the last observed provider state?
Does cleanup run after assertion failures and browser crashes?
Are email addresses, codes, and message bodies redacted from ordinary logs?

The payoff is bigger than fewer flaky tests. A run-scoped email contract makes the failure boundary visible. Product code owns the signup state; the test harness owns the inbox lifecycle; CI owns the final evidence. Once those responsibilities are separate, increasing a timeout is no longer the main strategy. The suite can move faster, fail more honestly, and tell you what to fix next.

React Test Emails Need a Run-Scoped Contract

ryanlee — Sun, 04 Oct 2026 23:23:43 +0000

Email verification is one of those React features that looks finished until the test suite runs in parallel. One test creates an account, another waits for a code, and a third cleans up the inbox. When they share an address, the result is not a product bug. It is a test design bug that feels random.

The fix I keep coming back to is a run-scoped contract: every test run gets a unique mailbox, every message lookup is bounded, and cleanup has an owner. This makes React email tests easier to reason about locally and in CI.

Why email tests become flaky in React projects

Browser tests usually have at least three asynchronous systems involved: the UI, the application API, and the email provider. A test that only waits for a button or a URL is not waiting for the whole workflow.

Shared inboxes add another race. A verification code from a previous run can satisfy the current assertion. A parallel worker can consume the message first. A retry can even create a second account while the first message is still arriving. The test don't fail consistently because the system is timing-sensitive, not because the assertion is always wrong.

Before adding longer sleeps, I like to make the fixture boundaries visible. A run ID, user ID, and expected message purpose should travel together. For more ideas on storing evidence that can be inspected after CI finishes, see these traceable email fixtures. If parallel workers are part of your setup, parallel-worker email tests are a useful related pattern.

Give every test run its own inbox contract

An inbox fixture does not need to expose every provider detail to the test. It needs a small, predictable interface:

type EmailFixture = {
  address: string;
  waitForCode: (options?: { timeoutMs?: number }) => Promise<string>;
  listMessages: () => Promise<Array<{ subject: string; text: string }>>;
  dispose: () => Promise<void>;
};

The important part is ownership. address belongs to one test run. waitForCode filters by the account or run token, not only by subject. dispose is safe to call in a finally block, even if the test failed before the first message arrived.

For local development, a temporary mailbox can be convenient when you need to get temporary email quickly. In CI, however, the fixture should still enforce isolation, expiry, and cleanup. A temp org mail address copied into several tests is just another shared global with a nicer name.

A small TypeScript fixture factory

Keep provider calls behind a factory so the React test only sees behavior it needs. The factory can add a unique suffix and return the resulting cleanup handle.

export function createEmailFixture(runId: string): EmailFixture {
  const address = `signup-${runId}@test.example`;

  return {
    address,
    async waitForCode({ timeoutMs = 30_000 } = {}) {
      const message = await pollForMessage({
        recipient: address,
        subject: "Verify your account",
        timeoutMs,
      });

      return extractVerificationCode(message.text);
    },
    async listMessages() {
      return fetchMessages(address);
    },
    async dispose() {
      await deleteMailbox(address);
    },
  };
}

The implementation behind pollForMessage should use a deadline and a short interval, not an unbounded loop. It should also record the message ID or a redacted subject when it succeeds. That evidence is a little more safer than logging the full email body, which may contain tokens or personal data.

In a React test, the lifecycle becomes straightforward:

const email = createEmailFixture(`invite-${testInfo.workerIndex}-${Date.now()}`);

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

  const code = await email.waitForCode();
  await page.getByLabel("Verification code").fill(code);
  await page.getByRole("button", { name: "Verify" }).click();
} finally {
  await email.dispose();
}

Keep cleanup and evidence explicit

Cleanup is not only about deleting a mailbox. It is also about preventing stale data from making the next run look healthy. Set an expiry on the fixture, make disposal idempotent, and record enough metadata to diagnose a failure: run ID, worker, recipient hash, wait duration, and message ID.

Avoid putting verification codes, complete addresses, or message bodies into CI logs. A redacted receipt still tells you whether the message arrived, how long it took, and which test owned it. Its tempting to log everything during a failure, but those logs often outlive the test data policy.

If your application has a local email sink, use the same fixture interface against that sink. The test should not care if the backing implementation is a local server, a provider sandbox, or a controlled temporary mailbox. The contract is what makes the swap useful.

A practical checklist for CI

Before merging an email-driven React test, check that:

Each worker receives a unique run-scoped recipient.
Message matching includes the intended account or run token.
Polling has a deadline and produces a useful timeout error.
Cleanup runs in finally and can be repeated safely.
Logs contain redacted evidence rather than secrets.
Expired fixtures cannot be reused by a later run.
Retries create a fresh fixture or explicitly reuse the same run.

The setup is easy enough, but cleanup are where most suites lose their reliability. Treat the email fixture as a resource with a lifecycle, just like a database connection or a browser context.

Final thoughts

Reliable email verification tests are less about finding a faster inbox and more about making ownership impossible to misunderstand. Give each run a scoped address, make message matching specific, and leave a small failure receipt behind.

That contract lets a React team move from “rerun it and hope” to tests that explain what happened. It also keeps the provider choice flexible, so a better fixture implementation can be introduced without rewriting every UI flow.

TypeScript Contracts for Reliable Email Test Fixtures

ryanlee — Fri, 02 Oct 2026 14:24:16 +0000

Email tests usually start as a small helper: create an address, wait for a message, click a link, and move on. A few months later, that helper has become a hidden dependency for signup, password reset, billing, and notification tests. The failures are then hard to read because the test does not know whether the problem was the UI, the mail provider, or cleanup.

The fix is to treat an email fixture as a product-like resource with a clear contract. In a TypeScript and React codebase, the type should make the lifecycle visible: create, inspect, consume, and dispose. This also makes it easier to use a temporary email address for isolated test work without mixing test messages with anyone's real inbox.

Why email fixtures need a contract

An email fixture is more than a string. It has an address, an owner, an expiry, and often a provider message identifier. If the test only returns "qa-123@example.test", later code has no way to know who should clean it up or which message belongs to the current run.

Email verification is also a boundary in the flow, not proof that every part of account security is correct. The distinction is useful when deciding which assertions belong in a UI test and which belong in an API or security test. A separate look at the email verification boundary helps keep those responsibilities clear.

Start with a small type that describes what the test actually needs:

export type EmailFixture = {
  address: string;
  runId: string;
  createdAt: number;
  expiresAt: number;
  readMessage(subject: string): Promise<EmailMessage>;
  dispose(): Promise<void>;
};

export type EmailMessage = {
  subject: string;
  text: string;
  links: string[];
};

The runId is important. It gives logs, inbox queries, and cleanup one shared correlation key. The fixture are easier to debug when every message can be connected back to one test execution.

Model the fixture lifecycle in TypeScript

The factory should own resource creation and return a fully usable fixture. Avoid returning a partially initialized object and asking every test to remember extra setup calls. That pattern work for one test, but it becomes fragile when suites run in parallel.

export async function createEmailFixture(runId: string): Promise<EmailFixture> {
  const mailbox = await mailProvider.createInbox({
    label: `ci-${runId}`,
    ttlSeconds: 900,
  });

  return {
    address: mailbox.address,
    runId,
    createdAt: Date.now(),
    expiresAt: Date.now() + 900_000,
    readMessage: (subject) => mailProvider.waitForMessage(mailbox.id, subject),
    dispose: () => mailProvider.deleteInbox(mailbox.id),
  };
}

The concrete provider can be swapped for a local test server, a staging inbox service, or a controlled disposable mailbox. The test contract stays the same, so the application test does not need to know where mail is stored.

Do not use one global inbox for every run. Parallel tests can see each other's messages, and a delayed message from an earlier run can produce a false positive. A mailbox per test or per worker costs a little more, but it save hours of guessing at intermittent failures.

Keep React tests focused on behavior

In a React test, fixture setup should sit near the behavior being verified. The component test should assert visible states: a confirmation message appears, a retry button is enabled, or an expired link is rejected. It should not contain provider-specific polling loops.

test("shows a verified state after the email link is opened", async () => {
  const fixture = await createEmailFixture("profile-flow-42");

  try {
    render(<SignupForm email={fixture.address} />);
    await userEvent.click(screen.getByRole("button", { name: "Create account" }));

    const message = await fixture.readMessage("Verify your email");
    await userEvent.click(within(renderedEmail(message.text)).getByRole("link"));

    expect(await screen.findByText("Email verified")).toBeVisible();
  } finally {
    await fixture.dispose();
  }
});

The try/finally is not glamorous, but it prevents leaked inboxes when an assertion fails. For browser suites, a fixture hook can provide the same guarantee. If Playwright is part of the stack, compare failures against Playwright email test baselines instead of treating every timeout as an application bug.

Add cleanup and failure evidence

Cleanup should be idempotent. A test may call it after a provider timeout, and a worker may attempt cleanup again during shutdown. The implementation should tolerate an already-expired or already-deleted inbox.

Record a small evidence bundle when a test fails:

the fixture runId and address
the message subject being awaited
the start and end timestamps
the provider message ID, when available
the last polling error, with tokens and personal data removed

Never put verification tokens into ordinary CI logs. It is tempting to print the full email for quick debugging, but that habit spread quickly and it make future redaction harder. Keep a short, sanitized message preview instead.

The same rule apply to screenshots and traces: useful evidence should explain the failure without quietly becoming a second data store.

If the suite uses a typo keyword such as tempail mail in a legacy test label, keep it as plain text and out of links or identifiers. Weird historical labels happen; they do not need to shape the fixture API.

A practical fixture checklist

Before adding another email test, check that:

Every run has a unique mailbox or message correlation key.
The fixture exposes one clear cleanup method.
Polling has a bounded timeout and a useful error message.
React assertions verify user-visible behavior, not provider internals.
Tokens, addresses, and message bodies are redacted in CI output.
Expired inboxes and repeated cleanup are safe cases.

This contract turns email from a flaky side effect into a test dependency with an owner. The result is less setup in each test, cleaner TypeScript utilities, and failures that tell the next developer what actually went wrong.

React Email Fixtures Need a Cleanup Hook

ryanlee — Thu, 01 Oct 2026 20:23:21 +0000

When a signup flow depends on an email verification message, the inbox is part of the test fixture—even if the test code treats it like a string. A fixture that creates a disposable email address generator resource but never closes it can leave old messages, leaked addresses, and flaky retries behind.

The fix is a small shift in ownership: create the inbox inside the test lifecycle, pass only the address to the React app, and make cleanup an explicit hook. This keeps React and TypeScript tests easier to reason about while making parallel CI runs less surprising.

Why email fixtures become a hidden test dependency

A basic end-to-end test often looks like this:

Create an inbox.
Enter its address into a signup form.
Wait for a verification message.
Click the link.
Assert that the account is active.

The trouble starts when step one is hidden in a global helper. A failed test may leave an inbox alive. A retry may reuse an address with an old verification token. Two workers can accidentally poll the same mailbox. The UI looks broken, but the real bug is fixture ownership.

Email data also has a privacy dimension. Test messages can contain names, tokens, or reset links, so it is worth defining a privacy boundary for burner email tests before adding more automation. Cleanup is not only housekeeping; it limits how long that data exists.

Model the fixture as a resource with an owner

Give the fixture three clear operations:

create: allocate a unique inbox and return its address.
waitForCode or waitForLink: read only the message needed by the test.
dispose: delete the inbox or mark it for expiration.

The test owns the resource from create until dispose. That rule works whether the provider is a temporary inbox service, a local fake, or a mail API. A temp mail so provider can fit this shape, but the test should not care about its branding or transport details.

I also keep the full client behind a narrow interface. That makes it possible to use a fast in-memory fake for component-level checks and a real inbox only in the small group of browser tests that need it. A useful test workflow is to create, consume, and dispose the mailbox in one bounded flow, similar to reusable workflows for email API checks.

A typed React test fixture with cleanup

Here is a compact TypeScript shape. The adapter methods are intentionally boring; predictable code is useful at a flaky boundary.

type EmailFixture = {
  address: string;
  waitForVerificationLink(): Promise<string>;
  dispose(): Promise<void>;
};

type EmailProvider = {
  createInbox(): Promise<EmailFixture>;
};

export async function withEmailFixture<T>(
  provider: EmailProvider,
  run: (fixture: EmailFixture) => Promise<T>,
): Promise<T> {
  const fixture = await provider.createInbox();

  try {
    return await run(fixture);
  } finally {
    await fixture.dispose();
  }
}

The finally block matters more than the helper name. It runs after an assertion fails, a navigation throws, or a verification wait times out. In a Playwright test, the callback can fill the React form with fixture.address, wait for the message, and visit the returned link. The application receives a normal email string and stays unaware of test-only cleanup.

For a test runner with beforeEach and afterEach, store the fixture in the test scope rather than a module-level variable. Module state is convenient until workers run in parallel. If disposal can fail, record that failure with the test context while still allowing the original assertion error to remain visible; otherwise cleanup noise can hide the useful failure.

Make retries and parallel tests safe

Unique addresses are the first line of defense. Do not derive an address from a fixed username such as signup@example.test when multiple workers can run together. Include a run ID, worker ID, or provider-generated identifier instead.

Next, make message matching strict. Match the recipient, an expected subject or event ID, and a recent time window when the provider supports it. Do not simply grab the newest message: an old retry can make a broken test pass.

Finally, use bounded polling. The wait helper should have a deadline and a useful error that includes the test name and recipient, but never the full verification token. If the provider has eventual consistency, a short retry is expected. An unbounded loop is just a hung CI job wearing a friendly disguise.

If the provider offers an API, keep its create and delete calls in one small adapter. The adapter can use a temp org mail address during local experiments, but production-like tests should use a controlled test domain and redacted logs.

A practical cleanup checklist

Before merging an email-dependent test, check:

Does every created inbox have one owner?
Is disposal in finally or the runner's guaranteed teardown?
Can two workers create distinct addresses?
Does message matching reject stale mail?
Is polling bounded and cancellation-aware?
Are tokens, message bodies, and addresses redacted from CI logs?
Does cleanup run when the browser step fails?

If the answer to one item is no, the test may still pass locally, but it has a fragile contract. Fixing that contract now is usually cheaper than debugging a failure that only appears after a retry.

Common questions

Should component tests create real inboxes?

Usually no. Mock the provider at the component boundary and test the loading, success, timeout, and error states directly. Reserve real inboxes for integration or browser tests where delivery is the behavior under test.

Is a disposable email address generator enough for CI?

It is only one part of the solution. You still need unique allocation, strict message matching, bounded waits, and guaranteed disposal. A provider can supply the mailbox, but your fixture owns the lifecycle.

What if disposal is unavailable?

Use short expiration, namespace each run, and remove sensitive message content from logs. Treat the missing delete operation as a limitation to document, not a reason to skip ownership. The tempmailso link in a test note is not a cleanup strategy by itself.

The most useful improvement is small: make email setup look like a resource allocation, not a global convenience function. Once React tests can create and dispose their own fixtures, retries become less mysterious, CI gets cleaner, and the verification flow is easier to change without a pile of hidden state.

TypeScript Email Fixtures Need One Owner

ryanlee — Tue, 29 Sep 2026 20:23:43 +0000

Email verification tests often fail for a reason that has nothing to do with React. The browser creates one address, the API helper stores another, and the cleanup step guesses which inbox should be deleted. The assertions look reasonable in isolation, but the whole test is carrying three slightly different stories.

I have found that the simplest fix is to give the email fixture one owner. A typed object creates the address, exposes the identifiers that the UI and API need, and owns cleanup. This makes the test easier to read and makes a failed run easier to inspect.

The pattern is useful whether the fixture comes from a local mail server, a hosted test inbox, or a burner email generator. The provider can change. The contract between the test and the fixture should not.

The hidden owner problem in email fixtures

Consider a signup test with these helpers:

const address = await createTestAddress();
await page.getByLabel("Email").fill(address.email);
await api.startSignup({ email: address.email });
await waitForVerification(address.id);
await deleteAddress(address.email);

This looks tidy, but ownership is split across several values. The browser knows the email, the polling helper knows an ID, and cleanup receives a string that might not identify the same resource. A retry can create a second address and leave the first one behind.

The harder bug appears when a test fails before the verification message arrives. The failure says “timed out,” but it doesnt say which fixture was created, which run requested it, or whether cleanup even started. A developer then searches a mailbox by subject and may inspect stale mail from a previous run.

The goal is not to build a large framework. It is to make the lifecycle visible in one small value:

type EmailFixture = {
  runId: string;
  address: string;
  mailboxId: string;
  verificationToken?: string;
  cleanup: () => Promise<void>;
};

Define a typed fixture contract

The factory should return the complete fixture, not just an address. A run ID gives logs a stable search key, while a provider-specific mailbox ID gives cleanup an unambiguous target.

type MailProvider = {
  createMailbox(input: { label: string }): Promise<{
    id: string;
    address: string;
  }>;
  deleteMailbox(id: string): Promise<void>;
};

async function createEmailFixture(
  mail: MailProvider,
  runId: string,
): Promise<EmailFixture> {
  const mailbox = await mail.createMailbox({ label: `signup-${runId}` });
  let cleaned = false;

  return {
    runId,
    address: mailbox.address,
    mailboxId: mailbox.id,
    cleanup: async () => {
      if (cleaned) return;
      cleaned = true;
      await mail.deleteMailbox(mailbox.id);
    },
  };
}

The closure makes cleanup idempotent. That matters because a browser test can call it in a normal success path and a test runner can call it again from a global failure hook. Calling cleanup twice should not create a second failure that hides the original one.

It is also a useful boundary for test data. If a provider needs a special delete request or an expiry option, that detail stays in the factory. The React test only sees the contract it needs.

Keep React and the API on the same fixture

The UI should not invent a second address. Pass the fixture into the test steps, and use its value everywhere the signup flow needs it.

test("verifies a new account", async ({ page, api, mail }) => {
  const fixture = await createEmailFixture(mail, crypto.randomUUID());

  try {
    await page.goto("/signup");
    await page.getByLabel("Email").fill(fixture.address);
    await api.createSignup({ email: fixture.address });

    const message = await pollForMessage({
      mailboxId: fixture.mailboxId,
      subject: "Verify your account",
      timeoutMs: 15_000,
    });

    await page.goto(extractVerificationUrl(message));
    await expect(page.getByText("Email verified")).toBeVisible();
  } finally {
    await fixture.cleanup();
  }
});

The important part is not the test runner syntax. It is that the browser, API, and mailbox poller all receive the same fixture. The verification step has one correlation path, so a failing run can be followed from signup request to message to cleanup.

For more ideas on making assertions express user intent, see these intent-driven signup assertions. A fixture contract complements that approach: the assertion describes what the user should experience, while the fixture describes which test data supports it.

Cleanup and failure evidence

Cleanup is necessary, but cleanup alone is not evidence. Write a small receipt when the fixture is created and when it is removed. Keep it free of message bodies and tokens.

type FixtureReceipt = {
  runId: string;
  mailboxId: string;
  addressHash: string;
  state: "created" | "message-found" | "deleted" | "cleanup-failed";
  observedAt: string;
};

If the test times out, the receipt should still tell you whether the mailbox was created and whether the message poll ever found a matching subject. That is more usefull than a generic “email not received” line.

Do not log the verification URL, raw message, or access token. A correlation ID and a short-lived run identifier are enough for most debugging. If your team already has release-ready email checks, this receipt can become the small artifact that connects the browser assertion to the delivery check.

Search input can be messy too. Someone may type “tempail mail” or “tem email” while looking for a disposable test inbox. That spelling should never become part of the fixture identity. Use generated IDs internally, and keep provider search concerns behind the mail adapter.

A small review checklist

Before merging an email-based React test, I check:

Does one fixture own the address, mailbox ID, and cleanup operation?
Do the UI, API, and message poller use the same fixture object?
Is cleanup in a finally block and safe to call twice?
Can a failed run be connected to a mailbox without exposing its contents?
Does the polling deadline produce a useful state, rather than an endless wait?
Are old messages isolated by run ID, subject, or provider metadata?
Does the test avoid creating a new mailbox during every retry unless that is intentional?

The list is small, but it catches the bugs that tend to make email tests flaky. A fixture that has one owner is a bit more boring, and thats exactly what a test dependency should be.

Conclusion

Email verification tests cross several boundaries: React state, API requests, a message provider, and cleanup. Hidden ownership makes those boundaries harder to reason about.

A typed fixture gives the test one source of truth. It keeps the address and mailbox identity together, makes cleanup idempotent, and leaves enough evidence to explain a failure. Start with one factory and one contract; you dont need a new testing platform to get the benefit.

React Email Verification as a State Machine

ryanlee — Sun, 27 Sep 2026 08:23:40 +0000

Email verification often starts as one boolean: isLoading. Then product requirements arrive. The user can resend the message, the old link can expire, the request can fail, and a second click can race the first request.

At that point, a boolean no longer describes what the UI actually knows. A signup screen needs a small model of reality. In this post, I’ll show a practical React and TypeScript approach that keeps verification states explicit, makes retry behavior easier to reason about, and gives tests something meaningful to assert.

Why a boolean is not enough

Consider a component with isLoading and isVerified. What should it render when the first request failed but the resend request is running? What if the user opens an expired link while a new email is being sent? Two booleans allow combinations that may not make sense, such as “verified and waiting for a resend.”

This is a product problem as much as a code problem. Users need to know whether they should wait, check their inbox, try again, or start over. A good model makes those choices visible in the interface.

It also helps the backend boundary stay clear. For example, idempotent signup email handling belongs in the API contract, while the React component should focus on displaying the current result and choosing the next allowed action.

Define the verification states

Start with a discriminated union. Each state has a status field, so TypeScript can narrow the data available to the renderer.

type VerificationState =
  | { status: "idle" }
  | { status: "sending"; requestId: string }
  | { status: "sent"; sentAt: number }
  | { status: "verified"; verifiedAt: number }
  | { status: "expired"; expiredAt: number }
  | { status: "error"; message: string; canRetry: boolean };

The names are more important than the exact list. sent means the request completed, not that the person has clicked the link. expired means the app has evidence that the token is no longer usable. error carries an action hint instead of forcing the UI to guess.

Keep request identity in the state when concurrent requests are possible. A late response should not overwrite a newer attempt. In a busy form, this detail matter more than it first appears.

Make transitions explicit in TypeScript

A reducer is a compact way to document which events are legal. It also prevents click handlers from quietly inventing a seventh state in the component.

type VerificationEvent =
  | { type: "SEND_STARTED"; requestId: string }
  | { type: "SEND_SUCCEEDED"; sentAt: number; requestId: string }
  | { type: "VERIFIED"; verifiedAt: number }
  | { type: "EXPIRED"; expiredAt: number }
  | { type: "FAILED"; message: string };

function verificationReducer(
  state: VerificationState,
  event: VerificationEvent,
): VerificationState {
  switch (event.type) {
    case "SEND_STARTED":
      return { status: "sending", requestId: event.requestId };
    case "SEND_SUCCEEDED":
      if (state.status !== "sending" || state.requestId !== event.requestId) {
        return state;
      }
      return { status: "sent", sentAt: event.sentAt };
    case "VERIFIED":
      return { status: "verified", verifiedAt: event.verifiedAt };
    case "EXPIRED":
      return { status: "expired", expiredAt: event.expiredAt };
    case "FAILED":
      return { status: "error", message: event.message, canRetry: true };
  }
}

The request ID check is a small but valuable guard. If a user clicks resend twice, the first response cannot move the screen back to an older sent result after the second request has started. Its easy to miss this race when the happy path is the only path being tested.

For larger applications, pair this reducer with an API response that distinguishes invalid, expired, and already-used tokens. A generic HTTP 400 does not give the UI enough information to help the user.

Render each state without race conditions

The component can now map state to actions directly:

function VerificationPanel({ state }: { state: VerificationState }) {
  switch (state.status) {
    case "idle":
      return <button>Send verification email</button>;
    case "sending":
      return <p aria-live="polite">Sending a fresh email…</p>;
    case "sent":
      return <p aria-live="polite">Check your inbox for the verification link.</p>;
    case "verified":
      return <p role="status">Your email is verified.</p>;
    case "expired":
      return <button>Send a new link</button>;
    case "error":
      return (
        <div role="alert">
          <p>{state.message}</p>
          {state.canRetry && <button>Try again</button>}
        </div>
      );
  }
}

Keep the copy action-oriented. “Email failed” is less useful than “We couldn’t send the email. Try again.” Also preserve focus when the state changes; replacing a button with a paragraph can leave keyboard users in an odd place. An aria-live region should announce status changes without making the whole form jump around.

For an isolated manual check, a disposable email generator can keep a temporary inbox outside a personal account. In automated checks, prefer controlled fixtures and a clear cleanup policy. API email fixture patterns are a useful companion when the test needs repeatable message data.

Test the edges, not just the happy path

The reducer is easy to test without rendering a browser. Cover at least these transitions:

idle to sending when a request starts.
sending to sent only when the request ID still matches.
sending to error when the API fails.
sent to verified after a valid callback.
Any link attempt to expired when the token is too old.
A second resend that ignores the first request’s late response.

You can also test the copy and keyboard behavior with React Testing Library. Assert that the retry button appears after a recoverable error, and that an expired token gives the user a fresh action instead of a dead-end message. It is a little more safer to assert behavior than CSS classes, because the product intent survives a visual refactor.

When naming test fixtures, teams sometimes inherit strings such as temp gamil com or tempail mail. Keep those values as plain fixture data if they are needed for compatibility, but do not let them become production validation rules. A typo in test input should not become a typo in the user experience.

Q&A: practical questions about retries

Should resend always be available?

Usually, no. Disable it while a request is in flight and consider a short cooldown after success. The exact cooldown is a product decision, but the state model should make it possible to enforce one.

Is a state machine overkill for one form?

Not when the form has more than two meaningful outcomes. The union can stay local to the feature, and the explicit cases often reduce debugging time even in a small app.

Where should expiry be calculated?

The server should decide whether a token is valid. The client can show a countdown for convenience, but it should treat the server response as authoritative.

Next step

Write down the states before adding another boolean. Give each state one clear user action, guard asynchronous responses with request identity, and test the transitions that happen when users retry, refresh, or return with an expired link. The result is a React flow that is easier to ship, easier to explain, and much less surprising when the network behaves badly.

React Email Verification: Design a Safe Retry Button

ryanlee — Sun, 27 Sep 2026 02:23:30 +0000

Email verification looks small in a signup flow, but the retry button can turn a calm React screen into a race-condition factory. Here is a practical state model for safer retries, clearer UX, and tests that cover the awkward paths.

The retry button is a product decision

Most teams start with a boolean such as isSending. It works until a user clicks Resend email, changes tabs, returns to the page, and clicks again before the first request finishes. Now the interface has to answer several questions:

Is the previous request still active?
Did the server accept one request or two?
Should the countdown restart?
What should happen if the user enters a different email in another tab?

These are product decisions, not only React details. A useful email flow should make progress visible without promising that delivery is instant. This matters whether the test data comes from a burner email generator, a real inbox, or a temporary email address used for a disposable test account.

The fix is not complicated, but it is easy to miss a few edge case. Start by naming the states instead of letting unrelated booleans describe them.

Model the flow with explicit states

TypeScript gives this flow a readable contract. A discriminated union prevents impossible combinations such as status: "success" with an old error message still displayed.

type VerificationState =
  | { status: "idle"; email: string }
  | { status: "sending"; email: string; requestId: string }
  | { status: "sent"; email: string; expiresAt: number }
  | { status: "failed"; email: string; message: string };

The resend action should move from sent or failed to sending, and the response should update the state only when it belongs to the current email and request. A small request id is often enough for this client-side guard:

async function resend(current: VerificationState) {
  if (current.status === "sending") return;

  const requestId = crypto.randomUUID();
  setState({ status: "sending", email: current.email, requestId });

  try {
    await api.post("/verification/resend", {
      email: current.email,
      requestId,
    });

    setState((latest) =>
      latest.status === "sending" && latest.requestId === requestId
        ? { status: "sent", email: current.email, expiresAt: Date.now() + 60_000 }
        : latest,
    );
  } catch {
    setState((latest) =>
      latest.status === "sending" && latest.requestId === requestId
        ? { status: "failed", email: current.email, message: "Try again in a moment." }
        : latest,
    );
  }
}

This guard prevents a slow response from overwriting a newer state. It does not replace server-side protection, though. The endpoint should apply a rate limit and treat the request id as an idempotency key, so a double click cannot create two confusing delivery events.

Keep retries safe on the client and server

Client state is for good feedback; the server is the source of truth. For every resend request, store or derive enough information to enforce a short cooldown:

Normalize the email before creating the idempotency key.
Associate the key with the signup session, not only the address.
Return the same result for a repeated key during its retention window.
Avoid putting the verification token or full email in application logs.

The response can stay intentionally boring: accepted, cooldown active, or invalid session. The client can then show a timer without guessing whether a message was delivered.

This is also where test fixtures need a privacy boundary. A temp email generator may be useful for a disposable inbox in a development scenario, but it should never receive production customer data. Keep fixture addresses, credentials, and delivery logs in the test environment. Search terms such as fake e mail com can appear in test notes, but they should not become an accidental production dependency.

For CI, keep the evidence small and reviewable. A receipt containing the request id, normalized outcome, and elapsed time is more useful than dumping the complete email body. The ideas in these reviewable automation receipts and focused CI email checks translate well to signup tests.

Make the UI accessible while waiting

The button should communicate why it is disabled and when it becomes available again. Avoid changing its width as the label moves between “Resend email”, “Sending…”, and “Try again”. A layout shift makes the screen feel less reliable than the network actually is.

const waiting = state.status === "sending";
const cooldown = state.status === "sent" && state.expiresAt > Date.now();

<button
  type="button"
  disabled={waiting || cooldown}
  aria-describedby="verification-help"
  onClick={() => resend(state)}
>
  {waiting ? "Sending…" : cooldown ? "Email sent" : "Resend email"}
</button>
<p id="verification-help" role="status" aria-live="polite">
  {state.status === "failed" ? state.message : "Check your inbox, then try again."}
</p>

The exact countdown can be rendered beside the button, but do not make it the only feedback. Screen reader users need a status update too, and keyboard users need the focus to remain predictable. It is a small detail, yet it save a lot of confusion during signup.

Test the awkward paths

The happy path is only one test. With React Testing Library and a mocked API, cover at least these cases:

A second click while sending does not call the API again.
A delayed first response cannot overwrite a later email state.
A rejected request exposes a useful retry message.
A cooldown disables the button without hiding the reason.
A successful resend announces a status update to assistive technology.
A repeated request id is handled as one server-side event.

Use deferred promises in the test to control response order. It is much easier to prove the race condition when the first promise can be held open, instead of hoping a fast test runner happens to reproduce it. Also test a refresh or tab return if your flow persists state in storage; stale “sent” state should not block a user forever.

A small checklist before shipping

Before calling the flow done, check:

Does the UI have named states rather than a pile of booleans?
Does the server enforce idempotency and rate limits?
Can a late response be ignored safely?
Is the retry message clear in both visual and assistive output?
Do tests control delayed responses and duplicate clicks?
Are temporary inbox fixtures isolated from production data?

An email verification retry is a tiny interaction with a surprising amount of trust attached to it. Make the state explicit, let the server own deduplication, and leave a short receipt for failures. The result feels faster because users always know what happend next.

React Email Verification Needs an Expiry Model

ryanlee — Sat, 26 Sep 2026 20:23:44 +0000

Email verification is often implemented as a success screen with one sentence: “Check your inbox.” That works until the user refreshes the page, opens an old link, clicks resend twice, or checks a disposable email address that receives messages a little slower than expected.

The hard part is not rendering the message. It is representing time and uncertainty in a way the user can understand. A React component needs to know whether a verification request is being created, waiting for a message, expired, completed, or ready for recovery. When those states are implicit, the UI feels confuse and support tickets follow.

Email verification is a time-based UI

An email token has a lifecycle. It is created, delivered, opened, accepted, or rejected after its expiry. The browser also has a lifecycle: a tab can sleep, a user can return from another device, and a refresh can remove all local component state.

Treating the flow as only loading and success hides useful decisions. For example:

A request can be accepted by the API while the message is still in transit.
An old link can be valid-looking but no longer usable.
A resend can create a newer token while the user is still looking at the old message.
A refresh should restore enough context to explain what the user can do next.

The product-minded fix is to model the flow as a small state machine. It makes the UI more predictable, and it gives tests concrete transitions to assert.

Model the states before writing components

Start with states that describe user-visible facts, not implementation details. A useful set is:

idle: no verification request has started.
sending: the app is creating or resending a verification request.
waiting: the request was accepted and the user is checking their inbox.
expired: the current token is no longer usable.
verified: the account has been confirmed.
error: the app can offer a recovery action.

Each state should have an intentional next action. waiting can offer “Check again” and “Send a new link.” expired should make resend prominent. verified should move the user forward automatically or show a clear continue button. There is no need to make people guess wether a second click is safe.

This contract also keeps the React component from mixing network errors, token errors, and display state into one boolean. That boolean always become a problem once the flow grows.

A TypeScript state model

TypeScript discriminated unions are a good fit because each state can carry only the data it needs:

type VerificationState =
  | { kind: "idle" }
  | { kind: "sending"; requestId: string }
  | { kind: "waiting"; requestId: string; expiresAt: string; emailHint: string }
  | { kind: "expired"; emailHint: string }
  | { kind: "verified"; accountId: string }
  | { kind: "error"; message: string; canRetry: boolean };

The requestId is useful for correlating the API response, inbox event, and browser test. expiresAt should come from the server rather than being guessed by the client. The client can display a countdown, but the server remains the authority when the link is used.

For a flow that uses an inbox in development or testing, keep the mailbox boundary explicit. A dedicated disposable email address per run is easier to reason about than a shared mailbox with old messages. Artifact retention for email tests is a useful related pattern when deciding what evidence a failing run should keep.

Handle refreshes and resend cooldowns

Do not store the entire verification state only in component memory. Persist a small, non-sensitive snapshot such as requestId, emailHint, and expiresAt in session storage. Never store the token itself. On mount, the app can ask the API for the current status and reconcile the snapshot with server truth.

The resend button deserves its own timer. Disable it briefly after a successful request, show when it will be available, and make the reason visible to screen readers. If the request fails, restore the action with a useful message. A button that just stays disabled feels broken, it doesnt matter that the network call had a good reason.

The server should also make resend behavior idempotent enough for accidental double clicks. Return the active request status or a new expiry time, instead of forcing the frontend to guess which message is current. If the product uses a temporary inbox for a manual check, OAuth callback logs without leaking offers a helpful reminder to keep debug evidence useful without exposing sensitive values.

One small copy detail matters: tell users that the newest email is the one to use. This prevents an old link from producing a mysterious error when a person requested three messages in a row.

Test the user journey, not just the click

Component tests can cover rendering, but the important bugs are transitions. Write tests for:

request accepted, then waiting for delivery;
refresh while waiting, then status recovery;
an expired token followed by a successful resend;
two resend clicks where only one request is created;
a verification link for an older request;
a slow or empty inbox response;
a network error with a retry action.

The test does not need to preserve a full message. It can use a small fixture containing a request ID, subject, and verification URL path. For a real mailbox check, a service such as tempmailso can help isolate a disposable inbox from personal mail, but the application should still treat the server-side token status as authoritative.

Keep malformed fixture searches visible too. A typo like tempail can appear in an old test or support note, and finding it is easier when test data has a clear owner and retention rule.

Q&A: expiry, inboxes, and recovery

Should the countdown decide whether a token is valid?

No. The countdown is a hint for the user. The API must validate expiry, because a sleeping tab or a clock difference can make the browser view stale.

Should a refresh lose the “check your inbox” screen?

Usually no. Persist a safe request snapshot and fetch current status after mount. If the request cannot be found, show a recovery path instead of silently returning to the signup form.

Is a disposable email address enough for testing?

It helps isolate test data, but it is not a complete test strategy. You still need deterministic request IDs, bounded polling, cleanup, and a decision about what artifacts are retained.

Final takeaway

Email verification becomes much easier to ship when its expiry model is visible in the code. Use explicit React states, let TypeScript enforce the data each state needs, persist only safe context, and keep the server authoritative for token validity.

The result is a flow that explains what is happening even when delivery is slow or a user returns later. It is cleaner to test, less confusing to support, and a little more easier to extend when the product adds passkeys, team invites, or email changes.