Testing Sign-Up Email Verification

Check that sign-up sends a confirm-your-address email, and that its link or code really verifies the account.

To test sign-up email verification, create an inbox, sign up with its address, and wait for the confirmation email from inbox.createdAt. Open the link from email.links, or submit the code that waitForOtp() returns, then check that the account is verified, and that it was not before. The examples below call your app over HTTP; the browser guides do the same through the UI.

What to Cover

  • Delivery: the email reaches the address the user typed, from the sender and with the subject you expect.
  • The gate: the account is not verified until the link or code is used.
  • Verification: the link or code verifies the account.
  • Edge cases: resending, expired or reused links, wrong codes.

Install

TypeScript

bash
npm install --save-dev @receiverdotemail/sdk

Python

bash
pip install receiverdotemail httpx pytest-asyncio

Both SDKs read RECEIVER_API_KEY. The TypeScript tests run in Jest or Vitest; the Python tests need asyncio_mode = auto, as in Pytest Integration.

A Link Helper

An email can list the same link twice, once with & in place of &, or with a trailing full stop from the text body. Testing Magic-Link Login explains why. These helpers return the first link to a path, cleaned up:

links.ts
export function findLink(links: string[], path: string) {
  for (const raw of links) {
    const link = raw
      .replace(/&/g, "&")
      .replace(/[.,;:!?)]+$/, "");
    const { pathname } = new URL(link);
    if (pathname.startsWith(path)) return link;
  }
  throw new Error(`No ${path} link in ${links}`);
}
links.py
import html
import re
from urllib.parse import urlsplit


def find_link(links, path):
    for raw in links:
        link = html.unescape(raw)
        link = re.sub(r"[.,;:!?)]+$", "", link)
        if urlsplit(link).path.startswith(path):
            return link
    raise AssertionError(f"no {path} link in {links}")

Verify With a Link

Sign up, check that login is refused, follow the link, check that login works. Replace the endpoints and status codes with your app's:

verify-link.test.ts
import { ReceiverClient } from "@receiverdotemail/sdk";
import { findLink } from "./links";

const receiver = new ReceiverClient();
const APP = "https://staging.your-app.com";
const PASSWORD = "S3cure-test-pass";
const post = (path: string, body: object) =>
  fetch(APP + path, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

test("the link verifies the account", async () => {
  const inbox = await receiver.inboxes.create();
  const user = { email: inbox.address, password: PASSWORD };

  await post("/api/signup", user);
  const before = await post("/api/login", user);
  expect(before.status).toBe(403); // not verified yet

  const email = await receiver.emails.waitFor({
    recipient: inbox.address,
    since: inbox.createdAt,
    subject: "Confirm",
    timeout: 60,
  });
  expect(email.sender).toBe("[email protected]");

  const link = findLink(email.links, "/verify-email");
  expect((await fetch(link)).ok).toBe(true);

  const after = await post("/api/login", user);
  expect(after.status).toBe(200);
}, 90_000);
test_verify_link.py
import httpx
from receiverdotemail import ReceiverClient
from links import find_link

APP = "https://staging.your-app.com"
PASSWORD = "S3cure-test-pass"


async def test_link_verifies_account():
    async with ReceiverClient() as receiver, \
            httpx.AsyncClient(base_url=APP) as http:
        inbox = await receiver.inboxes.create()
        user = {"email": inbox.address,
                "password": PASSWORD}

        await http.post("/api/signup", json=user)
        res = await http.post("/api/login", json=user)
        assert res.status_code == 403  # not verified yet

        email = await receiver.emails.wait_for(
            recipient=inbox.address,
            since=inbox.created_at,
            subject="Confirm",
            timeout=60,
        )
        assert email.sender == "[email protected]"

        link = find_link(email.links, "/verify-email")
        res = await http.get(link, follow_redirects=True)
        assert res.is_success
        res = await http.post("/api/login", json=user)
        assert res.status_code == 200

Verify With a Code

verify-link.test.ts (continued)
test("the code verifies the account", async () => {
  const inbox = await receiver.inboxes.create();
  const user = { email: inbox.address, password: PASSWORD };
  await post("/api/signup", user);

  const otp = await receiver.emails.waitForOtp({
    recipient: inbox.address,
    since: inbox.createdAt,
    codeLength: 6,
    timeout: 60,
  });

  const res = await post("/api/verify-email", {
    email: inbox.address,
    code: otp.code,
  });
  expect(res.status).toBe(200);
}, 90_000);
test_verify_link.py (continued)
async def test_code_verifies_account():
    async with ReceiverClient() as receiver, \
            httpx.AsyncClient(base_url=APP) as http:
        inbox = await receiver.inboxes.create()
        user = {"email": inbox.address,
                "password": PASSWORD}
        await http.post("/api/signup", json=user)

        otp = await receiver.emails.wait_for_otp(
            recipient=inbox.address,
            since=inbox.created_at,
            code_length=6,
            timeout=60,
        )

        res = await http.post("/api/verify-email", json={
            "email": inbox.address,
            "code": otp.code,
        })
        assert res.status_code == 200

When Sign-Up Sends Two Emails

A welcome email and a confirmation email often leave together. waitFor() returns the newest matching email received after since, which may be the welcome email, so filter on subject (a case-insensitive substring) or sender (the exact From address). waitForOtp() takes the same filters; add codeLength so a year or an order number in the other email is not taken for the code.

Resending, Expiry and Reuse

For "Resend email", wait again from the first email's receivedAt, so only the new email can match. If your app invalidates the old link, check that as well:

typescript
const first = await receiver.emails.waitFor({
  recipient: inbox.address,
  since: inbox.createdAt,
  subject: "Confirm",
});
await post("/api/verify-email/resend", { email: inbox.address });

const second = await receiver.emails.waitFor({
  recipient: inbox.address,
  since: first.receivedAt,
  subject: "Confirm",
});
expect((await fetch(findLink(first.links, "/verify-email"))).ok).toBe(false);
expect((await fetch(findLink(second.links, "/verify-email"))).ok).toBe(true);

For expiry, give the test environment a short link lifetime instead of waiting it out. For reuse, open the same link twice and expect the second attempt to fail. For a wrong code, submit one that differs from otp.code.

Checking the Email Itself

waitFor() returns the subject, the sender, the plain-text body (textBody, text_body in Python) and the links, enough to assert on the wording. For the HTML body, headers or attachments, fetch the whole email with receiver.emails.get(email.id) and read htmlBody (html_body).

In the Browser

The same steps work through your sign-up page. Each browser guide has a test with a code and one with a link: Playwright, Cypress and Selenium.

Next Steps