Playwright Email Tests Need a Clock Contract

Description and use

An automation recipe for deterministic Playwright email verification tests using a clock contract to manage mailbox ownership, timing, and evidence, reducing flakiness in CI.

Problem

Email verification tests are flaky because the mailbox contract is missing, causing timing and ownership issues across local runs and CI.

Outcome

Deterministic email verification tests with reduced flakiness, clear ownership, and reproducible evidence.

Workflow

• Reserve a mailbox with a unique lease ID and expiry
• Use the lease to poll for the expected email with subject and run ID
• Wait for the verification link to appear and return it
• Navigate to the link and assert account activation
• Release the mailbox lease in a finally block to ensure cleanup

Evidence

Email verification tests often look flaky for mysterious reasons. A user is created, the application sends a message, Playwright opens an inbox, and the test waits for a link.

Source

The test can fail at every boundary. The application may queue the email after the HTTP response. The inbox may expose the message before its body is fully available.

Source

Define the email clock contract… Reserved, Requested, Observed, Consumed…

Source

The example keeps cleanup in finally, which matters when an assertion fails.

Source