Manage test inboxes, phone leases and cleanup

Give each test a clear owner for its messaging resources. An email test can create an inbox during setup. An SMS test normally uses a number provisioned in advance and reserves it for the duration of the flow. Both need a time boundary before the application sends its message.

Choose the resource lifetime

Resource	Setup	Teardown
Test inbox	Create a fresh inbox for the test attempt; set an expiry longer than the maximum run duration	Delete it when assertions and permitted diagnostics are complete; expiry provides a fallback if the runner crashes
Provisioned phone number	Add the number in the dashboard before testing; place numbers intended for concurrent tests in a pool	Release the test's lease; keep the provisioned number for future runs
Phone lease	Acquire a lease with a duration covering browser actions, message wait and cleanup	Release it in finally or framework teardown, even after an assertion failure
Received message	Wait within the test's inbox or phone using the timestamp captured before the triggering action	Reuse the returned message ID for later reads instead of rerunning a broad wait

Create an inbox for each test attempt

Use createInboxWithOptions with expiresIn in milliseconds or expiresAt for an absolute expiry. Choose a duration that covers your test runner's maximum duration plus time to collect diagnostics. Do not let an inbox expire while a retry or cleanup step still needs it.

Keep the inbox ID in the fixture or message-service object and pass only its address to the browser page object. Put deletion in teardown or finally. If setup fails before an inbox is created, teardown should skip that resource. If cleanup fails after an assertion has already failed, report both failures without hiding the original assertion.

See inbox expiry, Playwright fixtures and the Selenium, TestNG and Playwright POM guide for implementation examples.

Reserve phones without deleting them

Provision phone numbers once in the dashboard, then acquire a pool lease during test setup. Use the leased number in the application and the lease's phone ID when waiting for SMS. A worker must not continue using a number after its lease expires because another worker may acquire it.

Release the lease when the flow ends. Do not delete a provisioned phone as routine test teardown. If no lease is available before the acquisition timeout, report a setup failure or reduce parallelism; do not fall back to an arbitrary shared number.

The phone pool guide includes a try/finally example that releases the lease whether the browser flow succeeds or throws.

Isolate retries and workers

1. Assign a run and worker identifier to diagnostics and phone lease ownership.
2. Create a new inbox or acquire a phone lease for the test attempt.
3. Capture since immediately before submitting the action that sends the message.
4. Wait with recipient, sender or subject/body conditions appropriate to the flow.
5. Extract the OTP or link, complete the browser action and assert the final application state.
6. Collect permitted failure evidence and clean up before the next attempt.

Unread state alone does not identify a test run. Another worker or a dashboard read can change it, and an older unread message can still match. Pair resource isolation with a timestamp boundary. For persistent test identities, plus addressing can distinguish recipients, but shared state still needs explicit matching.

Retain useful evidence

Record resource IDs, message IDs, timing, the failed assertion and relevant browser screenshots according to your team's retention policy. Redact credentials and OTPs before sharing artifacts. If investigation requires retaining an inbox, give it a bounded expiry and an explicit cleanup owner rather than leaving every failed test's inbox indefinitely.

Use wait troubleshooting to diagnose delivery failures and API errors and retries to handle setup or teardown request failures.