Tester les emails avec Cypress et InboxTap

Respecter la frontière entre navigateur et Node

Créez InboxTapClient dans cypress.config.ts, au sein du processus Node de Cypress. Enregistrez les tâches dans setupNodeEvents, puis appelez-les depuis le fichier de test pour créer un destinataire et attendre une valeur capturée.

N’importez pas directement inboxtap/client dans un fichier exécuté par le navigateur. En gardant l’accès réseau dans le processus des tâches, l’API locale n’a besoin ni de prendre en charge CORS ni d’être exposée à la page testée.

Enregistrer des tâches simples et sérialisables

Renvoyez des chaînes simples, comme l’adresse générée, l’URL capturée ou l’OTP. Cypress sérialise chaque argument et chaque résultat de tâche : transmettez donc les filtres de sujet et les motifs d’expression régulière sous forme de chaînes, et non comme des objets RegExp, des fonctions ou des instances de classe.

Un gestionnaire de tâche doit renvoyer une valeur ou une promesse qui se résout en valeur. Cypress interprète undefined comme une tâche non gérée ; renvoyez explicitement null pour une commande sans résultat.

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

const inboxTap = new InboxTapClient();

interface LinkArgs {
  to: string;
  subject?: string;
  contains?: 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 }: LinkArgs) =>
          new TestInbox(inboxTap, to).waitForLink(options),
      });
    },
  },
});

• Documentation Cypress sur cy.task() ↗

Créer une adresse par test

Appelez la tâche createInbox dans chaque test, puis saisissez exactement cette adresse dans l’application. Les tâches d’attente suivantes reconstruisent une TestInbox à partir de l’adresse et appliquent le filtrage par destinataire sur le serveur.

Une nouvelle adresse est plus fiable que le vidage d’une boîte partagée dans beforeEach. Elle conserve les éléments utiles au diagnostic et empêche les fichiers de test parallèles de supprimer ou de lire les messages des autres.

Coordonner les deux délais

La méthode d’attente d’InboxTap possède son propre timeoutMs, tandis que cy.task() applique un délai de commande Cypress. Accordez au délai externe de Cypress un peu plus de temps qu’à l’attente InboxTap. En cas d’échec de livraison, la tâche renvoie alors le contexte propre à l’email au lieu d’être remplacée par une expiration générique de Cypress.

Gardez les deux attentes bornées. Un test lent doit échouer avec assez de contexte pour déterminer si l’application n’a rien envoyé, a utilisé le mauvais port SMTP ou a choisi un autre destinataire.

Choisir le SDK ou l’accès HTTP direct

cy.request() peut atteindre l’API HTTP d’InboxTap sur l’interface de bouclage via le mandataire côté Node de Cypress ; cette approche suffit pour une petite assertion sur un point de terminaison. Les tâches du SDK restent généralement préférables, car TestInbox parcourt les messages existants et nouveaux, filtre par destinataire et extrait les liens ou les codes.

Quelle que soit l’approche, conservez InboxTap sur l’interface de bouclage et démarrez-le avec l’application avant Cypress. Cette intégration concerne des processus locaux ou CI sur la même machine d’exécution ; elle ne sert pas à exposer un service de boîte sans authentification.