Tester les emails de vérification avec Cypress

Cypress exécute le code des fichiers de test dans le navigateur, donc le SDK Node ne peut pas être importé dans un fichier de test. Enregistrez plutôt quelques gestionnaires cy.task() dans setupNodeEvents : les tâches détiennent le SDK dans le processus Node de la configuration, et les fichiers de test les appellent avec des valeurs simples.

Démarrer les services

Démarrez InboxTap et l’application avant l’exécution de Cypress, en local comme en CI :

npx inboxtap &
npm run dev &
npx cypress run

Configurez l’application testée pour envoyer le SMTP vers localhost:1025.

Enregistrer les tâches

// 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 tâche de création renvoie l’adresse de la boîte sous forme de chaîne, et chaque tâche d’attente reconstruit un TestInbox à partir de l’adresse qu’elle reçoit.

Écrire le test

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");
      });
    });
  });
});

Donnez à l’option timeout de Cypress plus de temps qu’à timeoutMs, afin qu’un email lent échoue dans la tâche avec le message d’erreur d’InboxTap plutôt que par une expiration générique du délai. Utilisez la tâche inboxtap:waitForCode quand l’application demande un OTP au lieu d’un lien.

Isolation parallèle

Créez la boîte dans chaque test, jamais une seule fois pour toute la suite. Chaque appel de tâche génère une adresse destinataire fraîche, donc les fichiers de test parallèles peuvent partager un seul serveur InboxTap sans lire les messages des autres. Le stockage borné évince les anciens messages de lui-même ; n’ajoutez une tâche de vidage que si un nettoyage immédiat aide au débogage local.

Accès HTTP direct

cy.request s’exécute depuis le proxy côté Node de Cypress, il peut donc atteindre directement l’API sur l’interface de bouclage sans enregistrer de tâche :

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

Vous perdez en échange le balayage multi-messages et l’extraction de valeurs du SDK, donc préférez les tâches pour tout ce qui dépasse une vérification ponctuelle. La liste complète des points de terminaison se trouve dans la référence de l'API HTTP.