Troubleshooting - QA Wolf Docs

`mail.inbox()` throws because no client is configured

Cause: The runtime did not call configureEmailsClient(...) before the flow ran. Check:

the runner creates the client
the runner configures it before flow execution

`waitForMessage(...)` returns an older message

Check:

whether the flow should pass after: new Date()
whether the same inbox is being reused across multiple steps or retries

No message arrives before timeout

Check:

the product under test actually sent the email
the address being used is allowed for the workspace
the timeout is long enough for the expected delivery path

Old emails are matched by waitForMessage

Using new: true to generate a unique address for each run ensures waitForMessage only sees messages from the current run. When reusing a stable address is unavoidable, pass after: new Date() immediately before the action that triggers the email:

const after = new Date();
await page.getByRole("button", { name: "Send code" }).click();

const message = await inbox.waitForMessage({ after });

For a local harness where neither option is available, calling resetEmailsClient() between test suites clears the client state.

Last modified on September 10, 2026