Skip to content
PigeonProbe

Supabase tutorial

Test Supabase emails with Playwright

A successful send request is only the start. This example signs up a disposable user, reads the confirmation email in PigeonProbe, requests a password reset, and checks that the new password signs in.

Using an app with its own SMTP sender? Follow the local Playwright email guide.

Download exampleStart free trial

One test, from signup to a new password

  1. Create a fresh, temporary PigeonProbe address for this run.
  2. Submit the sample application's signup form. Supabase sends through your configured SMTP provider.
  3. Wait for the confirmation email, validate its recipient and link, then complete confirmation in the browser.
  4. Request a reset and wait for a new matching email on the same address.
  5. Follow the recovery link, choose a new password and sign in with it.
  6. Revoke the test address and clean up the disposable Supabase user.

The sample runs on your computer. Supabase handles authentication; your SMTP provider sends; PigeonProbe receives. You can use the same receipt helper in your application's existing Playwright suite.

Prepare a dedicated test project

Supabase and your sender

Use a disposable Supabase project with email confirmation enabled. Configure your sending provider in Supabase's custom SMTP settings; PigeonProbe is the receiving destination. The default Supabase sender restricts recipients and is unsuitable for this workflow. Follow the Supabase SMTP setup.

Add http://127.0.0.1:4188/confirmed and http://127.0.0.1:4188/reset to the project's allowed redirect URLs. Use the project's URL and publishable key in the sample. Sender credentials stay in Supabase.

A scoped PigeonProbe credential

Create a dedicated mailbox. In Organization agents, create a credential for CI and scheduled runs, select only that mailbox, and grant email:read and addresses:manage. Keep its client secret in your local environment or CI secret store. See the integration guide for the credential flow.

You need Node.js 22.9 or newer and a Chromium browser installed by Playwright. Supabase and your sender have their own accounts and service limits.

Run the example

Download and extract the example, then follow its README to install dependencies and create your local environment file. The archive includes the application, Playwright flow and PigeonProbe receipt helper. Its environment template lists the required values without any credentials.

tar -xzf supabase-email-testing.tar.gz
cd supabase-email-testing
npm ci
npx playwright install chromium

Supply SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, PIGEON_CLIENT_ID, PIGEON_CLIENT_SECRET and PIGEON_MAILBOX_ID. Only the Supabase URL and publishable key belong in the browser. The PigeonProbe secret stays in the Node test process.

In one terminal, run npm start. In a second terminal with the same environment, run npm run test:live. Use SUPABASE_ADMIN_KEY in the Node test process for automatic cleanup of the user created by this run, or explicitly set KEEP_TEST_USER=1 and remove that disposable user afterward. Never put the admin key in browser code. npm test is a separate local UI check with mocked services; use the live command to test actual delivery.

Assert the outcome your user needs

Each run gets its own address so concurrent tests cannot consume one another's email. The test matches receipt time and message type before following a link. It then checks the application state and signs in with the replacement password.

A timeout, wrong recipient, unexpected link or failed sign-in fails the test. Sender acceptance alone does not pass it. Inspect the same received message in PigeonProbe when diagnosing a failure; keep passwords, recovery links and raw message bodies out of shared logs.

The test revokes the temporary address on exit. The README explains optional cleanup for only the Supabase user created by that run and how to remove it manually when an admin credential is not supplied.

When a run fails

No confirmation email
Check custom SMTP, the sender's verified identity and logs, and whether the Supabase project requires email confirmation. Then check the exact recipient and PigeonProbe receiving allowance.
The reset email does not match
Check the configured subject filters if you customized Supabase templates. Keep signup and reset matching separate; a message from the earlier step must not satisfy the reset assertion.
The link is rejected or redirects elsewhere
Check the exact redirect allowlist and project URL. Disable sender link rewriting for this test. Recovery links are sensitive and may be single-use.
The test passes locally but times out in CI
Keep the project and mailbox credentials in CI secrets, install the browser dependencies, and allow a bounded wait for delivery. Review sender rate limits before increasing parallelism.

Read Supabase's password authentication guide for its confirmation and recovery behavior.

Adapt this to your Playwright suite or plan broader signup and recovery coverage.