Skip to content
PigeonProbe

Use cases

Email testing with Playwright

Complete signup and reset tests through your normal sender. Wait for the received email, then check its link or code in Playwright.

Start free trialIntegration guide

When the browser needs the inbox

A signup test reaches “Check your email.” A password-reset test needs the link before it can continue. PigeonProbe gives your Node.js test process access to the received message, while the browser stays focused on your application.

Use it when your test should exercise the real sending path over public SMTP. The same message stays available in the PigeonProbe app so a teammate can inspect a failed run without reproducing it first.

One recipient per test

  1. Scope the credential. Create a test mailbox and issue a service credential for that mailbox with email:read and addresses:manage. Give its issuer read access to the mailbox.
  2. Create before you click. In the Node.js test process, create a temporary address and record the test start time. Fill that address into your application's signup or recovery form.
  3. Wait for the right message. After submitting the form, match the exact recipient, start time and expected subject. A fresh recipient keeps parallel tests and earlier runs separate.
  4. Complete the journey. Assert the message content, validate a test link's origin before navigating, and check the resulting application state. Revoke the recipient in your test's cleanup.

Keep service credentials in your CI secret store. They belong in the Node.js process, not in the page JavaScript or browser bundle.

Use the Node.js helper

Download email-check.mjs and import its connect function into your test setup. The helper uses Node.js 22 or later. After connecting, the email part of your test uses these calls:

const since = new Date().toISOString();
const address = await inbox.createAddress();
try {
  // Use address.address in your application's browser flow.
  // Submit that form before waiting for its email.
  const message = await inbox.waitForMessage({
    address: address.address,
    since,
    subject: 'Verify',
  });
  // Assert against message.parsed.text and message.parsed.links.
} finally {
  await inbox.revokeAddress(address);
}

This excerpt covers the inbox lifecycle; your Playwright test supplies the page actions and assertions. For a complete application example, run the local signup and password-reset flow. The integration guide includes connection setup and the helper's matching behavior. Use a bounded wait that fits your test timeout, and keep message bodies, codes and links out of shared CI logs.

Make a failure useful

Check three stages separately: did the browser submit the request, did your sender accept it, and did the expected message arrive? If it arrived with the wrong link or content, open the same mailbox to inspect parsed text, raw MIME and delivery checks.

If no match arrives, check the exact recipient, time filter, subject and sender logs. Also check receiving status and usage in PigeonProbe. A wait timeout tells you the expected message was not found within that wait; it does not identify which stage failed.

Put it into your next test run

Try this workflow with your normal sender and a PigeonProbe test address. Open the received message in the app, then bring the same check into CI when you are ready. Compare plans and trial limits.

Start free trialReceive your first test message

Related workflows