Guide: Testing Emails in Cypress
To test emails in Cypress, register cy.task handlers in cypress.config.ts that call the Receiver.email SDK in Node, then call them from your spec to get a fresh address, the emailed code or a link.
How to Test Emails in Cypress
Cypress specs run in the browser, but your API key and the SDK belong in Node. cy.task bridges the two: the task creates an inbox or waits for an email server-side and returns plain JSON (an address, a code, a URL) to the spec.
bash
npm install --save-dev cypress @receiverdotemail/sdk
export RECEIVER_API_KEY="recv_live_..."Register the Tasks
cypress.config.ts
import { defineConfig } from "cypress";
import { ReceiverClient } from "@receiverdotemail/sdk";
type WaitArgs = { address: string; since: string };
export default defineConfig({
e2e: {
baseUrl: "http://localhost:3000",
taskTimeout: 90_000, // longer than the waits below
setupNodeEvents(on) {
const receiver = new ReceiverClient(); // reads RECEIVER_API_KEY
on("task", {
// Returns { address, prefix, projectId, createdAt }
createInbox(prefix: string) {
return receiver.inboxes.create({ prefix });
},
// Returns the code as a string
async waitForOtp({ address, since }: WaitArgs) {
const otp = await receiver.emails.waitForOtp({
recipient: address,
since,
timeout: 60,
});
return otp.code;
},
// Returns the first link whose path starts with pathPrefix
async waitForLink({ address, since, pathPrefix }: WaitArgs & { pathPrefix: string }) {
const email = await receiver.emails.waitFor({
recipient: address,
since,
timeout: 60,
});
const link = email.links.find((l) => new URL(l).pathname.startsWith(pathPrefix));
if (!link) throw new Error(`No ${pathPrefix} link in "${email.subject}": ${email.links.join(", ")}`);
return link;
},
});
},
},
});Example: Sign-Up Verification Code
cypress/e2e/signup.cy.ts
import type { Inbox } from "@receiverdotemail/sdk";
describe("sign-up", () => {
it("verifies the account with the emailed code", () => {
cy.task<Inbox>("createInbox", "signup").then((inbox) => {
cy.visit("/signup");
cy.get("input[name=email]").type(inbox.address);
cy.contains("button", "Send code").click();
cy.task<string>("waitForOtp", { address: inbox.address, since: inbox.createdAt })
.then((code) => {
cy.get("input[name=code]").type(code);
cy.contains("button", "Verify").click();
cy.location("pathname").should("eq", "/dashboard");
});
});
});
});Example: Password Reset Link
cypress/e2e/password-reset.cy.ts
import type { Inbox } from "@receiverdotemail/sdk";
describe("password reset", () => {
it("resets the password from the emailed link", () => {
cy.task<Inbox>("createInbox", "reset").then((inbox) => {
// Create the user first (seed task, API call or UI sign-up)
cy.request("POST", "/api/test/users", { email: inbox.address, password: "old-Pa55word!" });
cy.visit("/forgot-password");
cy.get("input[name=email]").type(inbox.address);
cy.contains("button", "Send reset link").click();
cy.task<string>("waitForLink", {
address: inbox.address,
since: inbox.createdAt,
pathPrefix: "/reset-password",
}).then((link) => {
cy.visit(link);
cy.get("input[name=password]").type("new-Pa55word!");
cy.contains("button", "Save").click();
cy.contains("Password updated").should("be.visible");
});
});
});
});Magic link login works the same way: wait for the link with waitForLink and cy.visit() it. See Testing Magic Link Login.
Tips
- Task timeout:
cy.taskfails aftertaskTimeout(60 seconds by default). Keep it above the SDKtimeout, or pass{ timeout: 90000 }as the third argument tocy.task. - Return JSON: a task must return something serializable and not
undefined. Return the code or the URL, not the SDK client. - Other origins: if the link points at a different domain than
baseUrl, wrap the steps that follow incy.origin(). - Unique inboxes:
createInboxadds random characters to the prefix, so parallel runs and retries never read each other's mail. - CI: set
RECEIVER_API_KEYas a secret in the environment that runscypress run. See CI/CD Integration.
Next Steps
- Testing Emails in Playwright: fixtures instead of tasks
- Testing OTP / 2FA: resends and multiple codes
- Testing Password Resets: the full reset flow
- TypeScript SDK Reference