Playwright Email Tests Need Lease Expiry

Description and use

Playwright email tests now use a lease system that records owner, creation, expiry, and release times, eliminating flaky failures caused by stale messages and worker collisions.

Problem

Email test fixtures that live indefinitely cause flaky tests due to stale messages, worker collisions, expired tokens, and cleanup races.

Outcome

Tests become deterministic; failures are attributed to lease expiry or worker collision rather than random message timing.

Workflow

• 1. Define a LeasedInbox type with address, owner, expiresAt, assertUsable, and release methods.
• 2. Extend Playwright’s test fixture to lease an inbox via a mail client, passing owner and ttlMs.
• 3. In the fixture, create a LeasedInbox object that checks expiry before use and releases the inbox after the test.
• 4. In tests, call inbox.assertUsable() before and after actions, use inbox.address for form inputs, and wait for messages with a since timestamp.
• 5. Attach lease metadata to test reports for post‑mortem analysis.

Evidence

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.

Source

A lease gives the fixture four useful facts: owner, createdAt, expiresAt, releasedAt.

Source

I usually find one of four patterns when an email test starts failing after parallelism is added: Old message match, Worker collision, Expired token, Cleanup race.

Source