Cypress Maildev - Plugin open source pour tester les emails

Le contexte

Lors de mes projets, je me suis souvent retrouvé à écrire du code répétitif pour tester les emails en E2E. Maildev propose une API REST pratique, mais l’intégrer dans Cypress demandait toujours les mêmes manipulations.

J’ai créé cypress-maildev pour simplifier ces tests. L’idée était de fournir des commandes Cypress natives qui s’intègrent naturellement dans les tests existants.

Cas d’usage principaux

Flow d’inscription avec vérification de compte

Un des cas d’usage les plus courants : tester le parcours complet d’inscription. L’utilisateur s’inscrit, reçoit un email de confirmation, clique sur le lien et active son compte.

// 1. L'utilisateur s'inscrit
cy.get('input[name="email"]').type('user@example.com');
cy.get('button[type="submit"]').click();

// 2. On récupère l'email de confirmation
cy.maildevGetLastMessage().then((email) => {
  expect(email.subject).to.contain('Confirmez votre compte');
  
  // 3. On visite le HTML de l'email
  cy.maildevVisitMessageById(email.id);
  
  // 4. On clique sur le lien de confirmation
  cy.get('a[href*="/confirm"]').click();
});

// 5. Le compte est activé
cy.url().should('include', '/welcome');

Authentification à deux facteurs (2FA)

Tester la 2FA par email est simplifié grâce à l’extraction automatique des codes OTP :

// 1. L'utilisateur se connecte
cy.get('input[name="email"]').type('user@example.com');
cy.get('input[name="password"]').type('password');
cy.get('button[type="submit"]').click();

// 2. Un code 2FA est demandé et envoyé par email
cy.maildevGetMessageBySubject('Votre code de vérification').then((email) => {
  // 3. On extrait automatiquement le code à 6 chiffres
  cy.maildevGetOTPCode(email.text, 6).then((code) => {
    // 4. On le saisit dans le formulaire
    cy.get('input[name="otp"]').type(code);
    cy.get('button[type="submit"]').click();
  });
});

// 5. L'utilisateur est connecté
cy.url().should('include', '/dashboard');

Test du rendu visuel des emails

Une fonctionnalité que je trouve particulièrement utile : pouvoir charger le HTML de l’email directement dans Cypress et le tester comme une page web classique.

cy.maildevGetMessageBySubject('Bienvenue !').then((email) => {
  // On visite le rendu HTML de l'email
  cy.maildevVisitMessageById(email.id);
  
  // On peut ensuite utiliser toutes les commandes Cypress
  cy.get('h1').should('have.text', 'Bienvenue sur notre plateforme');
  cy.get('img[alt="Logo"]').should('be.visible');
  cy.get('a.button').should('have.attr', 'href').and('include', '/activate');
  
  // Vérifier que le style est correct
  cy.get('.button').should('have.css', 'background-color', 'rgb(0, 123, 255)');
});

Cela permet de valider que les emails sont correctement formatés, que les images s’affichent, et que les liens fonctionnent.

Commandes disponibles

Le package fournit une dizaine de commandes suivant les conventions Cypress :

• cy.maildevGetAllMessages() - Récupérer tous les emails
• cy.maildevGetLastMessage() - Récupérer le dernier email
• cy.maildevGetMessageById(id) - Trouver un email par ID
• cy.maildevVisitMessageById(id) - Charger le HTML de l’email
• cy.maildevGetMessageBySubject(subject) - Chercher par sujet
• cy.maildevGetMessageBySentTo(email) - Chercher par destinataire
• cy.maildevGetOTPCode(text, digits) - Extraire un code OTP
• cy.maildevDeleteAllMessages() - Vider la boîte mail

Toutes retournent des Cypress Promises pour un chaînage naturel dans vos tests E2E.

Mise en œuvre technique

Simplicité d’intégration

L’installation se fait en une commande npm/yarn, puis un simple import dans le fichier de support Cypress. Si Maildev tourne sur le port par défaut, aucune configuration supplémentaire n’est nécessaire.

Pour des configurations personnalisées (notamment avec Docker Compose), le package supporte des variables d’environnement.

TypeScript et expérience développeur

J’ai développé le package en TypeScript avec exports de types, ce qui permet l’autocomplétion dans les IDE et aide à éviter les erreurs.

Architecture

Sous le capot, le package utilise l’API REST de Maildev en encapsulant les appels HTTP avec cy.request(). L’idée était de masquer cette complexité pour que l’utilisateur puisse simplement utiliser des commandes Cypress familières.

Le package lui-même est testé avec Cypress, avec une suite de tests E2E qui vérifie chaque commande.

Open source et communauté

J’ai publié le projet sous licence MIT pour que tout le monde puisse l’utiliser librement. Le package reçoit régulièrement des téléchargements, ce qui me fait plaisir et montre qu’il répond à un besoin concret.

Je maintiens le projet en répondant aux issues GitHub et en publiant des mises à jour pour rester compatible avec les nouvelles versions de Cypress. J’ai aussi rédigé une documentation avec des exemples concrets pour faciliter la prise en main.

Recevoir des retours de la communauté m’a beaucoup aidé à améliorer le package et à corriger des bugs que je n’aurais pas détectés seul.