How to test magic links in CI

Why this is hard to test

• •E2E testing tools drive browsers but can’t receive emails
• •Email testing tools (Mailtrap, Mailosaur) receive emails but can’t drive browsers
• •Integrating them requires SMTP capture setup, email parsing, link extraction, and browser navigation - 3–4 separate tools
• •Most teams skip it entirely - magic link flows are the most critical PLG journey and the least tested

Approach 2: Zerocheck with explicit login setup

1. 1.Provide a safe login path using environment variables, a test account, or your own inbox tooling
2. 2.Approve browser checks for the authenticated product behavior that should run on PRs
3. 3.Keep inbox polling and magic-link extraction in customer-authored setup until first-class email primitives ship
4. 4.Review screenshots, recordings, and step traces when auth-adjacent behavior regresses

Extracting the magic link URL

Once your CI captures the email, you need to extract the magic link URL from the HTML body. Most magic link implementations embed a URL with a token parameter — something like https://app.example.com/auth/verify?token=abc123. The extraction pattern is the same regardless of which email capture service you use. The general approach: poll for the email (with a timeout), grab the HTML body, and parse out the URL. A regex works for most cases, but be aware of a common gotcha: if your app uses an email service like SendGrid or Postmark with click tracking enabled, the raw URL in the email HTML will be rewritten to a tracking redirect (e.g., https://url1234.sendgrid.net/ls/click?...). In your test environment, either disable click tracking or extract the final destination URL from the tracking wrapper. Another subtlety: some email templates use HTML entities or URL encoding in the href attribute. Always decode the extracted URL before navigating to it. The code example below shows a complete Playwright + Mailosaur flow that handles polling, extraction, and navigation. If you’re using Mailpit instead, swap the Mailosaur API call for a GET to http://localhost:8025/api/v1/search?query=to:[email protected] and parse the JSON response — the structure differs but the extraction logic is identical.

import { test, expect } from "@playwright/test";
import Mailosaur from "mailosaur";

const mailosaur = new Mailosaur(process.env.MAILOSAUR_API_KEY!);
const serverId = process.env.MAILOSAUR_SERVER_ID!;

test("magic link login completes successfully", async ({ page }) => {
  const testEmail = `test.${Date.now()}@${serverId}.mailosaur.net`;

  // 1. Trigger the magic link flow
  await page.goto("/login");
  await page.getByLabel("Email").fill(testEmail);
  await page.getByRole("button", { name: "Send magic link" }).click();
  await expect(page.getByText("Check your email")).toBeVisible();

  // 2. Poll for the email (30s timeout)
  const email = await mailosaur.messages.get(serverId, {
    sentTo: testEmail,
  }, { timeout: 30000 });

  // 3. Extract the magic link from HTML body
  const html = email.html!.body!;
  const match = html.match(/href="(https?:\/\/[^"]*\/auth\/verify[^"]*)"/i);
  expect(match).toBeTruthy();
  const magicLinkUrl = match![1].replace(/&/g, "&");

  // 4. Navigate to the magic link
  await page.goto(magicLinkUrl);

  // 5. Verify authenticated state
  await expect(page.getByText("Dashboard")).toBeVisible();
  await expect(page.getByRole("button", { name: "Log out" })).toBeVisible();
});

OTP and passwordless variants

The same testing patterns apply to other passwordless auth methods: TOTP (Google Authenticator, Authy), SMS OTP (Twilio, Vonage), and passkeys (WebAuthn). The core challenge is identical — your test needs to produce or intercept a credential that lives outside the browser. For TOTP, the trick is to capture the shared secret during test account setup rather than scanning a QR code. When your app displays the authenticator setup screen, it typically also shows the secret as a text string (or you can extract it from the otpauth:// URI in the QR code data). Store that secret, then use a library like otplib to generate the current 6-digit code at test time. This is deterministic and reliable — no need to mock anything. For SMS OTP, Twilio provides magic test credentials that work without sending real messages. The test credential SID and auth token, combined with specific magic phone numbers (like +15005550006), let you trigger verification flows that auto-complete. This means your CI never sends real SMS messages and never depends on carrier delivery. For passkeys and WebAuthn, Playwright has built-in support via the Virtual Authenticator API. You can create a virtual authenticator in your test, register a credential, and use it to authenticate — all without a physical security key or biometric sensor. Call cdpSession.send(‘WebAuthn.enable’) followed by cdpSession.send(‘WebAuthn.addVirtualAuthenticator’) to set it up. In all cases, the principle is the same: control the secret in your test environment so you can deterministically produce the credential. Never rely on external delivery (real email, real SMS) in CI.

import { authenticator } from "otplib";
import { test, expect } from "@playwright/test";

test("TOTP login with authenticator app", async ({ page }) => {
  // 1. Set up a test account with TOTP enabled
  //    Capture the secret from the setup flow
  await page.goto("/settings/security");
  await page.getByRole("button", { name: "Enable 2FA" }).click();

  // Extract the secret from the otpauth:// URI or text display
  const secret = await page
    .getByTestId("totp-secret")
    .textContent();

  // 2. Generate the current TOTP code
  const code = authenticator.generate(secret!.trim());

  // 3. Enter the code to complete setup
  await page.getByLabel("Verification code").fill(code);
  await page.getByRole("button", { name: "Verify" }).click();
  await expect(page.getByText("2FA enabled")).toBeVisible();

  // 4. Log out and log back in with TOTP
  await page.getByRole("button", { name: "Log out" }).click();
  await page.goto("/login");
  await page.getByLabel("Email").fill("[email protected]");
  await page.getByLabel("Password").fill("testpassword");
  await page.getByRole("button", { name: "Log in" }).click();

  // 5. Enter a fresh TOTP code (regenerate in case of time drift)
  const loginCode = authenticator.generate(secret!.trim());
  await page.getByLabel("Authentication code").fill(loginCode);
  await page.getByRole("button", { name: "Verify" }).click();

  await expect(page.getByText("Dashboard")).toBeVisible();
});

FAQ