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.task fails after taskTimeout (60 seconds by default). Keep it above the SDK timeout, or pass { timeout: 90000 } as the third argument to cy.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 in cy.origin().
  • Unique inboxes: createInbox adds random characters to the prefix, so parallel runs and retries never read each other's mail.
  • CI: set RECEIVER_API_KEY as a secret in the environment that runs cypress run. See CI/CD Integration.

Next Steps