Skip to content
Facteur

The channel is your test framework

In this market, you do not integrate an API: you install a package in your framework. Four packages are published on npm, for Node, Playwright, Cypress and the first test. This page also shows the HTTP call, which works without any of them.

An HTTP API, and nothing to install

The wait happens on the server and the extraction on arrival: a test calls the message search without installing anything. Here is a complete email verification journey, in Playwright, without a single Facteur package.

signup.spec.ts TypeScript
import { expect, test } from '@playwright/test';

const INBOX = 'j3k9x2mq';

// Searches every second until the message arrives, thirty seconds at most.
async function waitForMail(sentTo: string, since: Date) {
  const search = new URLSearchParams({ inbox: INBOX, sentTo, since: since.toISOString() });
  for (let attempt = 0; attempt < 30; attempt++) {
    const response = await fetch('https://api.facteur.eu/messages?' + search, {
      headers: { authorization: 'Bearer ' + process.env.FACTEUR_API_KEY },
    });
    const { messages } = await response.json();
    if (messages?.[0]) return messages[0];
    await new Promise((resolve) => setTimeout(resolve, 1000));
  }
  throw new Error('Nothing arrived for ' + sentTo);
}

test('the verification link activates the account', async ({ page }) => {
  const tag = 'run-' + Date.now();

  // Noted before the click: only a message that arrives after it counts.
  const since = new Date();

  await page.goto('/signup');
  await page.getByLabel('Email').fill('signup+' + tag + '@' + INBOX + '.inbox.facteur.eu');
  await page.getByRole('button', { name: 'Create my account' }).click();

  const message = await waitForMail('signup+' + tag + '@', since);

  // The status before any field taken from the body.
  expect(message.status).toBe('parsed');
  await page.goto(message.links[0]);

  await expect(page.getByText('Account verified')).toBeVisible();
});
The same call is in the guides of the developers' portal, which play it against the service.

Four lines that matter

01

The request leaves before the click

It waits, and answers the moment the message arrives, not at the deadline. Sent after, it would chase a message that may already be there.

02

Sub-addressing keeps tests apart

Everything after the "+" is yours. That is what lets two tests share an inbox without stealing each other's messages.

03

Read status before any derived field

An accepted message exists for a moment before it is read: it then has no subject, no code, no links. By default, the search only returns messages already read, in the parsed state.

04

The key comes from the environment

Never written in the test, never passed as an argument: FACTEUR_API_KEY. The packages follow the same convention.

Four packages published on npm

Each package is published from a public repository, with the provenance npm checks. Install version 2.0.0 or later: it is the first that calls today's API.

Package Name on npm Install
A minimal Node library Open an inbox, wait for a message, read it with what was extracted from it, download an attachment. No runtime dependency.
@facteur-eu/sdk
npm i -D @facteur-eu/sdk
A Playwright plugin An address derived from the test itself: two tests in parallel never read the same mail, and a retried test does not read the mail of its first attempt. The wait stops within the test's budget, and the message received is attached to the report.
playwright-facteur
npm i -D playwright-facteur
A Cypress plugin One address per test and a command that waits for the message. The key stays in Node, out of the browser.
cypress-facteur
npm i -D cypress-facteur
An npm create initializer Two questions, then a first Playwright or Cypress test that waits for an email and reads its code.
create-facteur
npm create facteur
  • The packages call the Facteur API at https://api.facteur.eu, and read the API key from the FACTEUR_API_KEY variable.

  • Versions 1.0.0 of these four names target an old Facteur API and do not work with today's service. Install 2.0.0 or later.

  • The guides of the developers' portal call the API over HTTP: they work with or without the packages.

A first test in one command

npm create facteur asks two questions and writes a first test that receives an email. The free plan asks for no credit card.