# 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.

```bash
npm install --save-dev @playwright/test @receiverdotemail/sdk
export RECEIVER_API_KEY="recv_live_..."
```

```typescript
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 };
```

```typescript
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.

```typescript
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](https://www.receiver.email/docs/guides/magic-links) 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()`:

```typescript
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:

```bash
pip install receiverdotemail pytest-playwright-asyncio
playwright install chromium
```

```ini
[pytest]
asyncio_default_fixture_loop_scope = session
asyncio_default_test_loop_scope = session
```

```python
import 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 `inbox` fixture mints a new address per test, so `fullyParallel: true` and sharding are safe.
- **Resend flows**: wait again with `since` set to the first email's `receivedAt` so only the new email matches.
- **Several codes**: `otp.candidates` lists every code found, newest first. Pass `codeLength` to skip years and order numbers.
- **CI**: store `RECEIVER_API_KEY` as a secret. See [CI/CD Integration](https://www.receiver.email/docs/guides/ci-cd).

## Next Steps

- [Testing Magic Link Login](https://www.receiver.email/docs/guides/magic-links): choosing and opening the right link
- [Testing OTP / 2FA](https://www.receiver.email/docs/guides/otp-verification): resends and multiple codes
- [Testing Emails in Cypress](https://www.receiver.email/docs/guides/cypress): the same flows with `cy.task`
- [TypeScript SDK Reference](https://www.receiver.email/docs/sdks/typescript)

---

Source: https://www.receiver.email/docs/guides/playwright
