Guide: Testing Emails in Playwright
To test email verification in Playwright, give each test its own inbox with a fixture, let the page trigger the email, then call waitForOtp() for a code or waitFor() for a link and continue in the browser.
How to Test Email Verification in Playwright
Create the inbox in a Playwright fixture so every test (and every parallel worker) gets a unique address. Type that address into your sign-up form, wait for the code from the inbox's createdAt, and fill it in. The wait returns within about two seconds of the email arriving, so there are no sleeps and no stale codes from earlier runs.
npm install --save-dev @playwright/test @receiverdotemail/sdk
export RECEIVER_API_KEY="recv_live_..."import { test as base, expect } from "@playwright/test";
import { ReceiverClient, type Inbox } from "@receiverdotemail/sdk";
type TestFixtures = { inbox: Inbox };
type WorkerFixtures = { receiver: ReceiverClient };
export const test = base.extend<TestFixtures, WorkerFixtures>({
// One client per worker (reads RECEIVER_API_KEY)
receiver: [
async ({}, use) => {
await use(new ReceiverClient());
},
{ scope: "worker" },
],
// A fresh, unique address for every test
inbox: async ({ receiver }, use) => {
await use(await receiver.inboxes.create({ prefix: "pw" }));
},
});
export { expect };import { test, expect } from "./fixtures";
test("sign-up with an emailed verification code", async ({ page, inbox, receiver }) => {
// 1. Trigger the email from the UI
await page.goto("/signup");
await page.getByLabel("Email").fill(inbox.address);
await page.getByRole("button", { name: "Send code" }).click();
// 2. Wait for the code (throws ReceiverTimeoutError if it never arrives)
const otp = await receiver.emails.waitForOtp({
recipient: inbox.address,
since: inbox.createdAt,
codeLength: 6,
timeout: 60,
});
// 3. Submit it and assert
await page.getByLabel("Verification code").fill(otp.code);
await page.getByRole("button", { name: "Verify" }).click();
await expect(page).toHaveURL(/\/dashboard/);
});Testing a Magic Link or Verification Link
For links, use waitFor(). The returned email has a parsed links array; pick the one that points at your app and open it with page.goto(), so the session cookie lands in the test's browser context.
import { test, expect } from "./fixtures";
test("log in with a magic link", async ({ page, inbox, receiver }) => {
await page.goto("/login");
await page.getByLabel("Email").fill(inbox.address);
await page.getByRole("button", { name: "Email me a link" }).click();
const email = await receiver.emails.waitFor({
recipient: inbox.address,
since: inbox.createdAt,
subject: "sign in",
timeout: 60,
});
// Skip unsubscribe, logo and footer links: match your app's login path
const magicLink = email.links.find((link) => new URL(link).pathname.startsWith("/auth/magic"));
expect(magicLink, "magic link in email").toBeDefined();
await page.goto(magicLink!);
await expect(page.getByText(`Signed in as ${inbox.address}`)).toBeVisible();
});The same pattern covers email verification links, password resets and invitations. The magic link guide has more on choosing the right link.
Timeouts
Playwright's default test timeout is 30 seconds. Give email tests more room than the timeout you pass to waitFor():
import { defineConfig } from "@playwright/test";
export default defineConfig({
timeout: 90_000,
use: { baseURL: "http://localhost:3000" },
});Python: pytest-playwright
The Python SDK is async, so use Playwright's async API with the pytest-playwright-asyncio plugin, which provides an async page fixture:
pip install receiverdotemail pytest-playwright-asyncio
playwright install chromium[pytest]
asyncio_default_fixture_loop_scope = session
asyncio_default_test_loop_scope = sessionimport re
import pytest
from playwright.async_api import Page, expect
from receiverdotemail import ReceiverClient
@pytest.mark.asyncio(loop_scope="session")
async def test_signup_with_code(page: Page):
async with ReceiverClient() as receiver: # reads RECEIVER_API_KEY
inbox = await receiver.inboxes.create(prefix="pw")
await page.goto("https://your-app.com/signup")
await page.get_by_label("Email").fill(inbox.address)
await page.get_by_role("button", name="Send code").click()
otp = await receiver.emails.wait_for_otp(
recipient=inbox.address,
since=inbox.created_at,
code_length=6,
timeout=60,
)
await page.get_by_label("Verification code").fill(otp.code)
await page.get_by_role("button", name="Verify").click()
await expect(page).to_have_url(re.compile(r"/dashboard"))For a link, call receiver.emails.wait_for(...) and pick from email.links the same way, then await page.goto(link).
Tips
- Parallel workers: the
inboxfixture mints a new address per test, sofullyParallel: trueand sharding are safe. - Resend flows: wait again with
sinceset to the first email'sreceivedAtso only the new email matches. - Several codes:
otp.candidateslists every code found, newest first. PasscodeLengthto skip years and order numbers. - CI: store
RECEIVER_API_KEYas a secret. See CI/CD Integration.
Next Steps
- Testing Magic Link Login: choosing and opening the right link
- Testing OTP / 2FA: resends and multiple codes
- Testing Emails in Cypress: the same flows with
cy.task - TypeScript SDK Reference