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
npm install --save-dev @receiverdotemail/sdkPython
pip install receiverdotemail httpx pytest-asyncioBoth 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:
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}`);
}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:
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);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 == 200Verify With a Code
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);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 == 200When 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:
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
- Testing Magic-Link Login: picking links, one-time links and tracking redirects
- Testing OTP / 2FA: resending codes and choosing between them
- Concepts: how
sinceworks, and why waiting fromcreatedAtis safe