A Playwright Mailbox Lease for Reliable Tests

Description and use

Implementing a mailbox lease in Playwright tests removes flakiness by providing a unique address, run ID, timestamps, and cleanup, ensuring reliable email verification.

Problem

Email verification tests fail due to race conditions and shared inboxes, causing flaky results in CI environments.

Outcome

The mailbox lease pattern eliminates flakiness by ensuring each test owns a unique inbox, filters messages by recipient, timestamp, and subject, and cleans up after itself, leading to more reliable CI test results.

Workflow

• Create a mailbox lease before browser starts, including address, runId, createdAt, and expiresAt.
• Use the lease address to fill the email field in the signup form.
• Wait for a message matching the lease address, createdAt, and subject using waitForMessage.
• Verify recipient and timestamp against the lease.
• Extract the verification URL from the message text and navigate to it.
• Assert the account verified page is visible.
• Finally, release the mailbox lease in a finally block to clean up resources.

Evidence

Email verification tests often fail for a reason that has nothing to do with the verification code. Two workers read the same inbox, a previous message wins the race, or cleanup happens before the test has captured its evidence.

Source

A useful mental model is to treat a test mailbox as a short‑lived lease. One test owns it for one scenario, knows when the lease started, and can prove which message belongs to the run.

Source

The important part is not the provider API. It is the sequence of checks around the API: recipient must match, the message must be newer than the lease, and the subject must identify the expected workflow.

Source

Before the browser starts, create the lease. After the test finishes, release it in a finally block.

Source