Skip to content
nofeb

Test email verification in Cypress

Cypress runs specs in the browser, so put the nofeb SDK in cypress.config.ts as tasks: one creates an inbox, one waits for the email and returns the code. The spec calls cy.task for each, types the address, and enters the code it gets back.

Checked against the engine on .

What do you need?

  • Cypress 10 or later
  • @nofeb/sdk and NOFEB_API_KEY available to the Cypress Node process

Steps

  1. 1. Register two tasks

    Tasks run in Node, where the API key stays. Cypress's default task timeout is 60 seconds, so give the waiting task a longer one in the spec.

    cypress.config.ts
    import { defineConfig } from "cypress";
    import { Nofeb } from "@nofeb/sdk";
    
    const nf = new Nofeb(); // NOFEB_API_KEY
    
    export default defineConfig({
      e2e: {
        setupNodeEvents(on) {
          on("task", {
            async createInbox() {
              const inbox = await nf.inboxes.create({ ttl_seconds: 900 });
              return { id: inbox.id, address: inbox.address, since: new Date().toISOString() };
            },
            async waitForCode({ id, since }: { id: string; since: string }) {
              const { message } = await nf.inboxes.waitForEmail(id, { has_otp: true, timeout: 90, since });
              return message?.otps[0]?.code ?? null;
            },
          });
        },
      },
    });
  2. 2. Use them in a spec

    Create the inbox before visiting the form, so since predates the email.

    cypress/e2e/signup.cy.ts
    it("verifies a new account by email", () => {
      cy.task("createInbox").then(({ id, address, since }: any) => {
        cy.visit("/signup");
        cy.get("input[name=email]").type(address);
        cy.contains("button", "Create account").click();
    
        cy.task("waitForCode", { id, since }, { timeout: 100_000 }).then((code) => {
          expect(code, "verification code").to.be.a("string");
          cy.get("input[name=code]").type(String(code));
          cy.contains("button", "Verify").click();
          cy.contains("Welcome").should("be.visible");
        });
      });
    });
  3. 3. Links instead of codes

    Return message.links from the task instead and pick the link whose kind is verify or magic_login, then cy.visit it.

Frequently asked questions

Why use cy.task instead of calling the API from the spec?

Specs run in the browser, where an API key would be exposed and cross-origin calls get in the way. Tasks run in the Cypress Node process.

Do I need a fake SMTP server for Cypress email tests?

No. nofeb inboxes are real addresses, so your application sends through its normal provider and the test reads what actually arrived.

Status of everything on this page

Every capability named above, with its status as reconciled against the engine.

CapabilityWhat it doesStatus
Disposable inboxes with a time to live Give an inbox a lifetime in seconds; it and its mail are removed when it expires, and an event says so. Shipped
Wait for an email Long-poll an inbox for up to a minute until a message matching sender, subject or has-a-code arrives. Shipped
One-time code and link extraction Verification codes and classified links are pulled out of every message and returned as fields. Shipped
TypeScript and Python SDKs Official clients generated from the OpenAPI document: @nofeb/sdk for Node, Deno, Bun and edge runtimes, and nofeb for Python with sync and asyncio clients. Both chain long polls for waitForEmail, retry idempotent requests, page through lists and verify webhook signatures. Shipped