Probar correos de verificación con Cypress

Cypress ejecuta el código de las pruebas dentro del navegador, por lo que el SDK de Node no puede importarse en un archivo de prueba. En su lugar, registra varios controladores cy.task en setupNodeEvents: las tareas administran el SDK en el proceso de Node de la configuración y las pruebas las llaman con valores simples.

Iniciar los servicios

Inicia InboxTap y la aplicación antes de la ejecución de Cypress, en local y en CI:

npx inboxtap &
npm run dev &
npx cypress run

Configura la aplicación que se está probando para enviar SMTP a localhost:1025.

Registrar las tareas

// cypress.config.ts
import { defineConfig } from "cypress";
import { InboxTapClient, TestInbox } from "inboxtap/client";

const inboxTap = new InboxTapClient();

interface WaitArgs {
  to: string;
  subject?: string;
  contains?: string;
  pattern?: string;
  timeoutMs?: number;
}

export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      on("task", {
        "inboxtap:createInbox": async (alias: string) =>
          (await inboxTap.createInbox({ alias })).address,
        "inboxtap:waitForLink": ({ to, ...options }: WaitArgs) =>
          new TestInbox(inboxTap, to).waitForLink(options),
        "inboxtap:waitForCode": ({ to, ...options }: WaitArgs) =>
          new TestInbox(inboxTap, to).waitForCode(options),
      });
    },
  },
});

La tarea de creación devuelve la dirección del buzón como una cadena, y cada tarea de espera reconstruye un TestInbox a partir de la dirección que recibe.

Escribir la prueba

describe("sign up", () => {
  it("verifies a new account", () => {
    cy.task<string>("inboxtap:createInbox", "signup").then((address) => {
      cy.visit("/signup");
      cy.get("input[name=email]").type(address);
      cy.contains("button", "Create account").click();

      cy.task<string>(
        "inboxtap:waitForLink",
        { to: address, subject: "verify your email", contains: "/verify", timeoutMs: 20_000 },
        { timeout: 30_000 },
      ).then((url) => {
        cy.visit(url);
        cy.contains("Email verified").should("be.visible");
      });
    });
  });
});

Da a la opción timeout de Cypress más tiempo que a timeoutMs, para que un correo lento falle dentro de la tarea con el mensaje de error de InboxTap y no como un tiempo de espera genérico de Cypress. Usa la tarea inboxtap:waitForCode cuando la aplicación pida un código OTP en lugar de un enlace.

Aislamiento en paralelo

Crea el buzón dentro de cada prueba, nunca una sola vez para todo el conjunto. Cada llamada a una tarea genera una dirección de destinatario nueva, por lo que las pruebas paralelas pueden compartir un único servidor InboxTap sin leer los mensajes de otras. El almacén acotado elimina por sí solo los mensajes antiguos; añade una tarea de limpieza únicamente si la limpieza inmediata facilita la depuración local.

Acceso HTTP directo

cy.request se ejecuta desde el proxy del lado de Node de Cypress, por lo que puede acceder directamente a la API de bucle local sin registrar ninguna tarea:

cy.request(
  "http://localhost:8025/api/emails/wait?to=signup-1@local.test&timeoutMs=20000",
)
  .its("body.email.links")
  .should("not.be.empty");

Esto prescinde del examen de varios mensajes y de la extracción de valores del SDK, por lo que conviene usar las tareas para cualquier operación que vaya más allá de una comprobación puntual. La lista completa de rutas está en la referencia de la API HTTP.