\n

ShazaMail

How to Fix Flaky Email Verification Tests

A flaky email test is often a synchronization problem: the browser continues before the message is available, or the test reads a message from another run.

Product documentation last reviewed: 2026-11-18

Software team collaborating around laptops during a testing workflow

Remove fixed sleeps from the test path

A fixed delay assumes that every email arrives within the same number of seconds. Network latency, provider queues, spam filtering, and CI load make that assumption unreliable. Replace sleeps with a polling loop that checks for the specific expected message until a deadline. Use a short interval and a maximum duration so the test remains responsive without hammering the API.

Correlate each message with one test run

Create a fresh inbox for every test or worker and attach a run identifier to the resource when supported. Match the target recipient and expected message context rather than accepting the first unread email. This prevents parallel test runs from consuming each other's OTPs and makes it possible to investigate a failure without guessing which test generated the message.

Make failure states visible

Separate the failure cases: inbox creation failed, message did not arrive before the deadline, sender or subject did not match, message parsing failed, or the application rejected the code. Log safe diagnostics such as the test run ID, elapsed time, and message count. Do not expose message bodies, verification codes, phone numbers, or API credentials in public CI logs.

Use idempotency and bounded retries

When a network request times out, the server may have completed it even though the client did not receive the response. Reuse the same idempotency key for the same request body so a retry does not create duplicate resources. Use exponential backoff for transient rate-limit or network errors, respect Retry-After when supplied, and stop retrying validation errors that require a code change.