Recevoir un email dans un test Playwright

Un parcours d’inscription se termine dans une boîte mail, et votre test doit lire ce qui y arrive. Voici le fichier entier, sans rien à installer de notre part.

Avant de commencer

Deux choses, et rien d’autre :

1. Une clé d’API en lecture seule. Créez-la dans Réglages → Clés d’API et mettez-la dans les secrets de votre intégration continue, sous FACTEUR_API_KEY. Le test ci-dessous ne crée rien : il lit. Voir Clés d’API.
2. L’identifiant de votre inbox, les huit caractères affichés en haut de la vue inbox.

import { expect, test } from '@playwright/test';

const KEY = process.env.FACTEUR_API_KEY!;
const INBOX = 'j3k9x2mq';

/** Reste ouvert jusqu'à l'arrivée du message, trente secondes au plus. */
const attendre = (sentTo: string) =>
  fetch('https://api.facteur.eu/v1/messages/search', {
    method: 'POST',
    headers: {
      authorization: `Bearer ${KEY}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify({ inbox: INBOX, sentTo, wait: 30_000 }),
  }).then((response) => response.json());

test('le lien de vérification active le compte', async ({ page }) => {
  const tag = `run-${Date.now()}`;

  // Lancée avant le clic : elle répond dès que l'email arrive.
  const arrive = attendre(`inscription+${tag}`);

  await page.goto('/inscription');
  await page.getByLabel('Email').fill(`inscription+${tag}@${INBOX}.inbox.facteur.eu`);
  await page.getByRole('button', { name: 'Créer mon compte' }).click();

  const { messages } = await arrive;
  expect(messages[0].status).toBe('parsed');
  await page.goto(messages[0].links[0].href);

  await expect(page.getByText('Compte vérifié')).toBeVisible();
});

Lancez l’attente avant l’action

C’est la seule ligne dont l’ordre compte. La requête part avant le clic, reste ouverte, et répond à l’instant où l’email arrive. Lancée après, elle courrait après un message peut-être déjà traité, et vous verriez ce défaut le jour où votre intégration continue devient lente.

Une adresse par test, sans rien créer

Toute adresse qui finit par le domaine de votre inbox y arrive. Vous n’avez donc pas d’appel à faire pour créer inscription+run-1734@j3k9x2mq.inbox.facteur.eu : il suffit de l’écrire. C’est ce qui permet à seize tests parallèles de partager une inbox sans se voler leurs emails.

Mettez le nom du test et le numéro de tentative dans l’étiquette. Sans le numéro, un test rejoué relit l’email de sa première tentative et passe pour une mauvaise raison, précisément quand quelque chose est déjà instable.

Lisez status avant tout le reste

Un email accepté existe avant d’être analysé. Pendant quelques millisecondes il n’a ni sujet, ni code, ni liens. Le champ status sépare « il n’y a pas de code dans ce message » de « le code n’est pas encore extrait ». La recherche ne rend que des messages analysés par défaut, donc le cas ne se présente que si vous demandez status: any.

Le code est déjà sorti du message

messages[0].otp porte le code à usage unique, extrait à la réception. Vous n’écrivez aucune expression régulière, et vous n’avez rien à corriger le jour où le gabarit d’email change.

Les liens sont là aussi : messages[0].links en porte un objet par lien, dans l’ordre où ils apparaissent, avec son href et son text.

Installer le greffon Playwright

Le greffon écrit à votre place l’adresse de chaque test et l’attente du message. Il demande Node 20 et Playwright 1.40 au minimum.

1. Installez-le : npm i -D playwright-facteur.
2. Créez une clé dans Réglages → Clés d’API, et posez-la en FACTEUR_API_KEY dans l’environnement de votre chaîne d’intégration.
3. Importez test et expect depuis playwright-facteur plutôt que depuis @playwright/test.

Vous obtenez une fixture inbox qui donne une adresse par test, et des assertions comme expect(message).toHaveOtp() que le moteur de Playwright rejoue tout seul. Le test ci-dessus n’a pas besoin du greffon et continue de fonctionner tel quel.

L’état de chaque intégration est sur la page Intégrations.