Getting started / quickstart-playwright

Quickstart: Playwright

From zero to a green OTP test in about four minutes. You'll create an inbox, point your signup form at it, and assert on the code your app sends.

1 · Install

The SDK is a single dependency with zero transitive baggage.

terminal

$ npm install -D mailfixture

$ pip install mailfixture

# no install — curl ships with your OS.
# you'll want jq for the examples below.

2 · Authenticate

Create a key in Dashboard → API keys, then export it. The SDK reads MAILFIXTURE_KEY automatically — never hardcode it in the repo your tests live in.

.env / CI secret

MAILFIXTURE_KEY=mf_live_••••••••••••••••

3 · Write the test

One inbox per test keeps runs independent and parallel-safe. waitForOtp() long-polls the server — it resolves the moment the email lands, or throws after the timeout.

signup.spec.ts

import { test, expect } from '@playwright/test';
import { MailFixture } from 'mailfixture';

const mail = new MailFixture(); // reads MAILFIXTURE_KEY

test('signup sends a one-time code', async ({ page }) => {
  const inbox = await mail.createInbox({ ttl: '15m' });

  await page.goto('/signup');
  await page.fill('#email', inbox.address);
  await page.click('text=Send code');

  const otp = await inbox.waitForOtp({ timeout: 30_000 });
  await page.fill('#otp', otp);

  await expect(page.locator('h1')).toHaveText('Welcome');
});

from mailfixture import MailFixture

mail = MailFixture()  # reads MAILFIXTURE_KEY

def test_signup_sends_otp(page):
    inbox = mail.create_inbox(ttl="15m")

    page.goto("/signup")
    page.fill("#email", inbox.address)
    page.click("text=Send code")

    otp = inbox.wait_for_otp(timeout=30)
    page.fill("#otp", otp)

    assert page.locator("h1").inner_text() == "Welcome"

# create an inbox
$ curl -X POST https://api.mailfixture.com/v1/inboxes \
    -H "Authorization: Bearer $MAILFIXTURE_KEY" \
    -d '{"ttl":"15m"}'
→ {"id":"ibx_7f3a","address":"qa-7f3a@tests.acme.dev"}

# …trigger your app's signup, then long-poll:
$ curl "https://api.mailfixture.com/v1/inboxes/ibx_7f3a/wait?timeout=30s" \
    -H "Authorization: Bearer $MAILFIXTURE_KEY" | jq .extracted.otp
→ "482913"

tip Need the magic link instead? waitForLink({ kind: 'magic_link' }) returns the URL, already classified. No regex was harmed.

4 · Run it

Locally or in CI — same behavior, because there's no sleep to tune. Keep the message viewer open while it runs; watching the email arrive never gets old.

terminal

$ npx playwright test signup.spec.ts

Running 1 test using 1 worker
  ✓  signup sends a one-time code (1.4s)

  1 passed (2.1s)

Next steps

Custom domains

One MX record; never “disposable.”

Extraction

OTPs, links, and how we classify them.

Webhooks

Push messages to your own endpoint.

Was this page useful? yes no Quickstart: Cypress →