Playwright Email Tests Need Lease Expiry

A throwaway email address is useful in an end-to-end test because it keeps test mail away from real people. But an inbox that lives forever is not automatically a reliable fixture. If several Playwright workers reuse it, old verification messages and abandoned aliases can make a passing test look healthy when it is only lucky.

I treat a test inbox like a leased resource. The test claims it, uses it for one bounded scenario, and releases or expires it when the run ends. That small lifecycle rule makes failures easier to explain. It also works whether the address comes from a throwaway email generator, a local mail container, or a provider-specific API.

This complements one rollout for related alerts and preflight checks for trial emails: a test should know which resource it owns before it starts making assertions.

Why a throwaway inbox needs a lease

Without an expiry boundary, an email fixture has unclear ownership. A local run may create it on Monday, while a CI worker reads it on Tuesday. A retry can also select a message from the previous attempt because the helper only asks for the newest message.

The resulting failure is inconsistant. Sometimes the stale message contains a valid link and the test passes early. Sometimes the link has expired and the test fails after a long wait. When the suite mentions a phrase like temp gamil com in a debugging note, that is often a sign that the naming and ownership rules were never made explicit.

A lease gives the fixture four useful facts:

• owner: the worker or test run that claimed the inbox
• createdAt: when the fixture became available
• expiresAt: the last time it may be used
• releasedAt: when cleanup completed, if cleanup happened

These are not production email requirements. They are test evidence. The point is to make a stale fixture look like a clear setup failure instead of an unpredictable product failure.

The failure modes caused by stale fixtures

I usually find one of four patterns when an email test starts failing after parallelism is added:

1. Old message match: the assertion searches by subject and accepts yesterday's verification mail.
2. Worker collision: two tests share an address, so one worker consumes the message intended for the other.
3. Expired token: the test correctly finds a message, but its link was generated for an earlier run.
4. Cleanup race: teardown deletes or releases the inbox while a final assertion is still polling.

The first three are especially hard to spot when the test only logs “email not received.” A test may actually have received three messages and rejected all of them for good reasons. The failure output should say which lease was active, which message ids were observed, and whether the fixture was already expired.

A Playwright fixture with explicit expiry

I prefer putting the lease in a fixture so every spec gets the same rules. The provider client below is deliberately small; the important part is that the test records its ownership and checks expiry before reading.

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

type LeasedInbox = {
  address: string;
  owner: string;
  expiresAt: number;
  assertUsable(): void;
  release(): Promise<void>;
};

export const test = base.extend<{ inbox: LeasedInbox }>({
  inbox: async ({}, use, testInfo) => {
    const now = Date.now();
    const inbox = await mail.lease({
      owner: `${testInfo.workerIndex}:${testInfo.title}`,
      ttlMs: 90_000,
    });

    const leased: LeasedInbox = {
      address: inbox.address,
      owner: inbox.owner,
      expiresAt: inbox.expiresAt,
      assertUsable() {
        if (Date.now() >= inbox.expiresAt) {
          throw new Error(`Inbox lease expired for ${inbox.address}`);
        }
      },
      release: () => mail.release(inbox.address),
    };

    await use(leased);
    await leased.release();
  },
});

test("verifies a new account", async ({ page, inbox }) => {
  inbox.assertUsable();
  await page.getByLabel("Email").fill(inbox.address);
  await page.getByRole("button", { name: "Create account" }).click();
  inbox.assertUsable();
  const message = await mail.waitForMessage(inbox.address, {
    since: Date.now() - 5_000,
  });
  expect(message.to).toContain(inbox.address);
});

In a real project, mail would be injected by the fixture module rather than left global. The example keeps the lifecycle visible: claim, check, consume, release. It is also worth attaching the lease metadata to the test report. That makes a CI failure usefull even after the temporary inbox has been cleaned up.

How to diagnose lease-related failures

When a run fails, I read the evidence in this order:

1. Compare the message timestamp with createdAt and expiresAt.
2. Confirm the message recipient matches the current lease, not just the expected domain.
3. Check whether another worker has the same owner or address.
4. Look at teardown timing: did release happen before the last poll finished?

If the address expired before delivery, the test infrastructure has a latency problem. If delivery happened inside the lease but the message was rejected, inspect the subject, recipient, and token parser. If the message was accepted but the next page failed, the email fixture is probably innocent.

That separation is important. Otherwise teams lengthen every timeout and call it a fix. It makes the suite slower while the ownership bug stays in place. A slightly longer lease can be sensible, but it should follow measured delivery time, not guesswork.

An automation-friendly checklist

Before merging a Playwright email test, I check:

• every worker receives a unique address or a provably isolated mailbox
• the fixture records owner, creation, expiry, and release times
• message polling starts after the triggering action
• assertions check recipient or message ownership, not only subject
• an expired lease fails with a specific diagnostic
• teardown runs after the final message assertion
• the report preserves enough metadata for a person to reproduce the issue

This also prevents confusing aliases such as temp mailid from being treated as a durable test identity. Names can be messy; ownership rules should not be.

Q&A

Is a lease needed if my test suite runs serially?

It is still helpful. Serial execution removes one collision, but it does not remove stale messages, retries, or cleanup races. A short lease documents the intended lifetime.

What should the TTL be?

Start with the normal delivery time plus a small margin, then inspect slow runs. Keep the value long enough for genuine infrastructure variance but short enough that an old fixture cannot survive unnoticed.

Should I release an inbox after every test?

Usually yes, provided the release happens after all message assertions and report attachments. If a provider cannot release immediately, mark the fixture expired and prevent it from being leased again.

What if the provider only gives one shared inbox?

Use a unique recipient alias, a run id in the subject, or a message ownership token. If none of those are possible, treat the shared inbox as a constrained integration resource and make that limitation visible in the test report.