playwright-facteur 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,89 +1,103 @@
1
1
  # playwright-facteur
2
2
 
3
- Receive email in your Playwright tests, and assert on what arrived.
3
+ Receive email in your Playwright tests. Your application sends a mail to an address of a Facteur inbox, and the test waits for it, reads its code, its links and its attachments, and finds the mail in the Playwright report.
4
4
 
5
- ```ts
6
- import { test, expect } from 'playwright-facteur';
7
-
8
- test('the verification link activates the account', async ({ page, inbox }) => {
9
- await page.goto('/signup');
10
- await page.getByLabel('Email').fill(inbox.address('signup'));
11
- await page.getByRole('button', { name: 'Create my account' }).click();
5
+ Needs `@playwright/test` 1.60.0 or later, and Node 22 or later. It builds on `@facteur-eu/sdk`.
12
6
 
13
- const message = await inbox.waitFor();
14
- expect(message).toHaveOtp();
7
+ ## Install
15
8
 
16
- await page.goto(message.links[0].href);
17
- await expect(page.getByText('Account verified')).toBeVisible();
18
- });
9
+ ```sh
10
+ npm install --save-dev playwright-facteur @playwright/test
19
11
  ```
20
12
 
21
- No `sleep`, no retry loop, no regular expression pulling a six-digit code out of an HTML
22
- body. The wait happens on the server; the extraction happens when the mail is received.
23
-
24
- ## Install
13
+ Create an API key in the application, under Settings, API keys. A key that reads and writes mail (`ws:read` and `ws:write`) is enough. Keep it, and the inbox your tests use, in the environment:
25
14
 
26
15
  ```sh
27
- npm i -D playwright-facteur
28
16
  export FACTEUR_API_KEY=fk_...
17
+ export FACTEUR_INBOX=<the id of the inbox>
29
18
  ```
30
19
 
31
- Node 20 or later, and Playwright 1.40 or later. Mint the key in the application under
32
- **Settings → API keys**.
33
-
34
- ## What you get
20
+ ## Write a test
35
21
 
36
- **`inbox`** is a fixture, one address per test. The tag carries the worker index, the
37
- retry number and the test title, so `--workers=16` collides with nothing. The retry
38
- matters: without it, a retried test reads the mail its own first attempt received, and
39
- passes for the wrong reason exactly when something is already flaky.
22
+ Import `test` and `expect` from `playwright-facteur` instead of `@playwright/test`.
40
23
 
41
24
  ```ts
42
- inbox.address() // test+the-title-w3r0-lz9k@j3k9x2mq.inbox.facteur.eu
43
- inbox.address('billing') // billing+the-title-w3r0-lz9k@…
44
- await inbox.waitFor({ subject: /invoice/ })
45
- ```
25
+ import { expect, test } from 'playwright-facteur'
46
26
 
47
- **Matchers**, retried by Playwright's own engine and inheriting the test's timeout:
27
+ test('signs up with a confirmation code', async ({ page, inbox }) => {
28
+ await page.goto('/signup')
29
+ await page.getByLabel('Email').fill(inbox.address('signup'))
30
+ await page.getByRole('button', { name: 'Create account' }).click()
48
31
 
49
- ```ts
50
- await expect(inbox).toReceiveEmail({ subject: /verification/ });
51
- expect(message).toHaveOtp('882314');
52
- expect(message).toHaveLinkTo('app.example.com');
53
- expect(message).toHaveAttachment('invoice.pdf');
32
+ await expect(inbox).toReceiveEmail({ subject: 'confirmation code' })
33
+ await expect(inbox).toHaveLinkTo('/confirm')
34
+ await page.getByLabel('Code').fill(inbox.latest!.otp!)
35
+ })
54
36
  ```
55
37
 
56
- `toHaveOtp` fails with a different sentence when the message is not parsed yet, because
57
- "there is no code in this mail" and "the code is not extracted yet" are different
58
- problems and an `undefined` cannot tell them apart.
38
+ `inbox.address('signup')` is an address that belongs to this test alone, such as `signup+sign-up-with-a-confirmation-code-1x2y3z-p0r0-m3k9q@<id>.inbox.facteur.eu`. Your application can send to any address of the inbox without creating anything first, so tests share one inbox and never read each other's mail.
59
39
 
60
- **The message in the report.** Every awaited message is attached to the test: the JSON
61
- for the extracted fields, the HTML body to open. When a test fails, the mail that
62
- actually arrived is next to the failure.
40
+ ## Fixtures
63
41
 
64
- ## One inbox per worker, one address per test
42
+ | Fixture | Scope | What it is |
43
+ | --- | --- | --- |
44
+ | `inbox` | test | The inbox seen through the address of this test. |
45
+ | `facteurInbox` | worker | The inbox of the worker. `FACTEUR_INBOX` names an existing one, which is what a plan with a single inbox needs. Without it, each worker opens an inbox (in `FACTEUR_WORKSPACE`, or in the default workspace if the key may read the organization) and deletes it when the worker ends. |
46
+ | `facteur` | worker | The `Facteur` client of the SDK, with the key from `FACTEUR_API_KEY` and the address from `FACTEUR_BASE_URL`. |
65
47
 
66
- Every address ending in the inbox's domain arrives, with nothing to create first, so a
67
- sub-address isolates a test as well as a whole inbox would.
48
+ An `inbox` has:
68
49
 
69
- It also survives your plan. Creating an inbox per test walks into the inbox ceiling (one
70
- on the free plan, three on Solo), so that arrangement works on a laptop and fails the
71
- first time the suite runs on the plan you pay for.
50
+ | Member | Does |
51
+ | --- | --- |
52
+ | `address(local?)` | The address to send the mail under test to. `local` is the text before the `+`, `test` by default. |
53
+ | `waitFor(criteria?)` | Waits for a mail sent to this address, attaches it to the report and returns it. The criteria are the SDK's: `subject`, `body`, `sentFrom`, `otp`, `attachmentName`... plus `timeout` in milliseconds. |
54
+ | `latest` | The last message `waitFor` returned in this test, or `null`. |
55
+ | `messages()` | The last messages of the whole inbox, whatever their address. |
56
+ | `tag` | The part after the `+` of the address. |
72
57
 
73
- Name an existing inbox to skip creation entirely, which is what most suites end up doing:
58
+ ## What isolates one test from another
74
59
 
75
- ```sh
76
- export FACTEUR_INBOX=j3k9x2mq
60
+ The tag in the address is built from four things:
61
+
62
+ - the title of the test, and a short hash of its full path (project, file, groups), so two tests with the same title in two files differ;
63
+ - the parallel slot, so two tests running at once differ;
64
+ - the attempt number, so a test that Playwright replays does not read the mail its first attempt received;
65
+ - the run, so a suite that keeps its inbox between runs does not read the mail of the previous run.
66
+
67
+ ## How long a test waits
68
+
69
+ A wait lasts as long as what is left of the test's own timeout, less two seconds, with five minutes at most. When the mail does not come, the failure is written by this package, inside the test's timeout, instead of Playwright's message about a slow test:
70
+
71
+ ```
72
+ No message matched {"subject":"Your invoice"} at test+<tag>@<id>.inbox.facteur.eu.
73
+ Waited 6s. What did arrive: test+<tag>@<id>.inbox.facteur.eu, "Welcome" (parsed).
77
74
  ```
78
75
 
79
- Without it, the plugin opens one per worker and destroys it at the end. That costs
80
- nothing: an operation is a message received, never a call.
76
+ Pass `timeout` to wait less, for example to check that no mail was sent: `await expect(inbox).not.toReceiveEmail({ timeout: 3000 })`.
77
+
78
+ ## Matchers
79
+
80
+ Each matcher takes a message or an inbox. With an inbox, it reads `inbox.latest`, the last message received in the test.
81
+
82
+ | Matcher | Passes when |
83
+ | --- | --- |
84
+ | `toReceiveEmail(criteria?)` | A message matching the criteria reaches the address of the test. |
85
+ | `toHaveOtp(code?)` | The message carries a one-time code, or this one. A message refused for want of plan fails with a message that says so. |
86
+ | `toHaveLinkTo(text)` | A link of the message contains the text. Links are strings. |
87
+ | `toHaveAttachment(fileName?)` | The message has an attachment, or one with this name. Embedded images such as a signature logo do not count. |
88
+
89
+ ## The report
90
+
91
+ Each message `waitFor` returns is attached to the test in the report: `facteur-<message id>.json` holds the message as the API returned it, with its extracted code and links, and `facteur-<message id>.html.txt` holds the source of its HTML body, as plain text. The report never renders it: the HTML comes from whoever sent the mail, and a script in it would run in the report's page.
81
92
 
82
- ## Parallel runs
93
+ ## Environment
83
94
 
84
- The API refuses past twenty open waits per organization. The client keeps its own queue,
85
- sized from your worker count, so the surplus waits its turn instead of coming back as a
86
- `429`.
95
+ | Variable | Use |
96
+ | --- | --- |
97
+ | `FACTEUR_API_KEY` | The API key. Required. |
98
+ | `FACTEUR_INBOX` | The id of the inbox to use. Without it each worker opens its own. |
99
+ | `FACTEUR_WORKSPACE` | The slug of the workspace in which workers open their inbox. |
100
+ | `FACTEUR_BASE_URL` | The address of the API. Defaults to `https://api.facteur.eu`. |
87
101
 
88
102
  ## Licence
89
103
 
@@ -0,0 +1,11 @@
1
+ import type { Message } from '@facteur-eu/sdk';
2
+ export type Check = {
3
+ pass: boolean;
4
+ message: () => string;
5
+ };
6
+ /** The code of the message: any, or the expected one. A message refused for want of plan has no code to read. */
7
+ export declare function otpCheck(message: Message, expected?: string): Check;
8
+ /** The links of a message are strings (the API's `links`), compared by inclusion. */
9
+ export declare function linkCheck(message: Message, fragment: string): Check;
10
+ /** A real attachment, any or by name. Embedded images are another list (`inlines`) and never count. */
11
+ export declare function attachmentCheck(message: Message, fileName?: string): Check;
package/dist/checks.js ADDED
@@ -0,0 +1,27 @@
1
+ /** The code of the message: any, or the expected one. A message refused for want of plan has no code to read. */
2
+ export function otpCheck(message, expected) {
3
+ if (message.status !== 'parsed') {
4
+ return { pass: false, message: () => `the message is ${message.status ?? 'in an unknown state'}: it was refused, and nothing derived from its body was kept` };
5
+ }
6
+ const found = message.otp ?? null;
7
+ return {
8
+ pass: expected === undefined ? found !== null : found === expected,
9
+ message: () => (expected === undefined ? `expected a one-time code, the message carries ${found ?? 'none'}` : `expected the code ${expected}, the message carries ${found ?? 'none'}`),
10
+ };
11
+ }
12
+ /** The links of a message are strings (the API's `links`), compared by inclusion. */
13
+ export function linkCheck(message, fragment) {
14
+ const links = message.links ?? [];
15
+ return {
16
+ pass: links.some((link) => link.includes(fragment)),
17
+ message: () => `expected a link containing ${fragment}, the message carries ${links.length > 0 ? links.join(', ') : 'no link'}`,
18
+ };
19
+ }
20
+ /** A real attachment, any or by name. Embedded images are another list (`inlines`) and never count. */
21
+ export function attachmentCheck(message, fileName) {
22
+ const names = (message.attachments ?? []).map((one) => one.fileName);
23
+ return {
24
+ pass: fileName === undefined ? names.length > 0 : names.includes(fileName),
25
+ message: () => `expected ${fileName ?? 'an attachment'}, the message carries ${names.length > 0 ? names.join(', ') : 'none'} (embedded images are never counted)`,
26
+ };
27
+ }
@@ -0,0 +1,34 @@
1
+ import { Facteur } from '@facteur-eu/sdk';
2
+ import type { Inbox, Message, MessagePage, WaitCriteria } from '@facteur-eu/sdk';
3
+ /**
4
+ * What `toReceiveEmail` and `inbox.waitFor` accept: the criteria of a search, without the inbox and the
5
+ * address, which are the test's own, plus a ceiling for this wait.
6
+ */
7
+ export type ReceiveCriteria = Omit<WaitCriteria, 'inbox' | 'sentTo'> & {
8
+ /** Milliseconds to wait at most. Never more than what is left of the test's own timeout. */
9
+ timeout?: number;
10
+ };
11
+ /** What a test holds: the shared inbox, seen through an address that belongs to this test alone. */
12
+ export type TestInbox = {
13
+ readonly id: string;
14
+ readonly domain: string;
15
+ /** The part after the `+` of this test's address. */
16
+ readonly tag: string;
17
+ /** The last message `waitFor` returned in this test, or null. */
18
+ readonly latest: Message | null;
19
+ /** This test's address: send the mail under test here. */
20
+ address: (local?: string) => string;
21
+ /** Waits for a message sent to this test's address, attaches it to the report, and returns it. */
22
+ waitFor: (criteria?: ReceiveCriteria) => Promise<Message>;
23
+ /** The last messages of the whole inbox, whatever their address (to see what else arrived). */
24
+ messages: () => Promise<MessagePage>;
25
+ };
26
+ type TestFixtures = {
27
+ inbox: TestInbox;
28
+ };
29
+ type WorkerFixtures = {
30
+ facteur: Facteur;
31
+ facteurInbox: Inbox;
32
+ };
33
+ export declare const test: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & TestFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions & WorkerFixtures>;
34
+ export {};
@@ -0,0 +1,83 @@
1
+ import { Facteur, addressFor } from '@facteur-eu/sdk';
2
+ import { test as base } from '@playwright/test';
3
+ import { reportAttachments } from './report.js';
4
+ import { tagFor } from './tag.js';
5
+ import { boundedWait } from './wait.js';
6
+ /**
7
+ * One value for the whole run. The runner loads the test files before it starts the workers, which
8
+ * inherit its environment: the first load sets the variable and every worker reads the same one. A
9
+ * worker that finds it empty (a runner that did not load this module) falls back to its own start.
10
+ */
11
+ const runId = (process.env.FACTEUR_RUN ??= Date.now().toString(36));
12
+ export const test = base.extend({
13
+ // The client, one per worker: it holds the queue of waits, which is per process.
14
+ facteur: [
15
+ // Playwright reads the fixtures a function needs from its first parameter, which must be a destructuring.
16
+ // eslint-disable-next-line no-empty-pattern
17
+ async ({}, use, workerInfo) => {
18
+ // The API refuses past twenty open waits per organization, shared by every process that uses
19
+ // the organization's keys: a worker keeps a share of sixteen, at least one.
20
+ const share = Math.max(1, Math.floor(16 / Math.max(1, workerInfo.config.workers)));
21
+ await use(new Facteur({ maxConcurrentWaits: share }));
22
+ },
23
+ { scope: 'worker' },
24
+ ],
25
+ // The inbox of the worker. `FACTEUR_INBOX` names an existing one, which is what a plan with a single inbox needs.
26
+ // Without it, the worker opens an inbox (in `FACTEUR_WORKSPACE`, or the default workspace) and deletes it at the end.
27
+ facteurInbox: [
28
+ async ({ facteur }, use, workerInfo) => {
29
+ const existing = process.env.FACTEUR_INBOX;
30
+ if (existing) {
31
+ const found = (await facteur.inboxes.list()).find((one) => one.id === existing);
32
+ if (!found) {
33
+ throw new Error(`FACTEUR_INBOX names ${existing}, which this key does not reach. Check the id on the inbox screen, or widen the key's workspaces.`);
34
+ }
35
+ await use(found);
36
+ return;
37
+ }
38
+ const opened = await facteur.inboxes.create({
39
+ name: `playwright ${runId} w${workerInfo.workerIndex}`,
40
+ workspace: process.env.FACTEUR_WORKSPACE,
41
+ });
42
+ try {
43
+ await use(opened);
44
+ }
45
+ finally {
46
+ await facteur.inboxes.delete(opened.id).catch(() => undefined);
47
+ }
48
+ },
49
+ { scope: 'worker' },
50
+ ],
51
+ inbox: async ({ facteur, facteurInbox }, use, testInfo) => {
52
+ const tag = tagFor({ titlePath: testInfo.titlePath, title: testInfo.title, parallelIndex: testInfo.parallelIndex, retry: testInfo.retry, runId });
53
+ const startedAt = Date.now();
54
+ const inboxId = facteurInbox.id;
55
+ let latest = null;
56
+ await use({
57
+ id: inboxId,
58
+ domain: facteurInbox.domain,
59
+ tag,
60
+ get latest() {
61
+ return latest;
62
+ },
63
+ address: (local = 'test') => addressFor(facteurInbox, tag, { local }),
64
+ async waitFor(criteria = {}) {
65
+ const { timeout, ...search } = criteria;
66
+ const wait = boundedWait(testInfo, startedAt, timeout);
67
+ // `+<tag>@` and not the bare tag: a tag that is the start of another tag does not match it.
68
+ const found = await facteur.messages.waitFor({ ...search, inbox: inboxId, sentTo: `+${tag}@`, wait });
69
+ // The search carries the bodies and the headers, as the read of one message does: no second call.
70
+ latest = found;
71
+ await attach(testInfo, found);
72
+ return found;
73
+ },
74
+ messages: () => facteur.inboxes.messages(inboxId, { limit: 20 }),
75
+ });
76
+ },
77
+ });
78
+ /** The message, in the report: its JSON and the source of its HTML body, never a rendered page (see `reportAttachments`). */
79
+ async function attach(testInfo, message) {
80
+ for (const { name, contentType, body } of reportAttachments(message)) {
81
+ await testInfo.attach(name, { contentType, body });
82
+ }
83
+ }
@@ -0,0 +1,5 @@
1
+ export { test } from './fixtures.js';
2
+ export type { ReceiveCriteria, TestInbox } from './fixtures.js';
3
+ export { expect } from './matchers.js';
4
+ export { FacteurError, FacteurTimeout } from '@facteur-eu/sdk';
5
+ export type { Message } from '@facteur-eu/sdk';
package/dist/index.js ADDED
@@ -0,0 +1,3 @@
1
+ export { test } from './fixtures.js';
2
+ export { expect } from './matchers.js';
3
+ export { FacteurError, FacteurTimeout } from '@facteur-eu/sdk';
@@ -0,0 +1,23 @@
1
+ import type { Message } from '@facteur-eu/sdk';
2
+ import type { ExpectMatcherState, MatcherReturnType } from '@playwright/test';
3
+ import type { ReceiveCriteria, TestInbox } from './fixtures.js';
4
+ export declare const expect: import("@playwright/test").Expect<{
5
+ /**
6
+ * `await expect(inbox).toReceiveEmail({ subject: 'code' })`.
7
+ *
8
+ * The wait is the server's: the criteria go out once and the connection answers as soon as a message
9
+ * matches. The criteria are Facteur's (substrings of the subject, the body, the sender...). The message found is
10
+ * kept on the inbox (`inbox.latest`) and attached to the report.
11
+ */
12
+ toReceiveEmail(this: ExpectMatcherState, inbox: TestInbox, criteria?: ReceiveCriteria): Promise<MatcherReturnType>;
13
+ /**
14
+ * `expect(message).toHaveOtp('123456')`, or `expect(inbox).toHaveOtp()` for the last message received.
15
+ * A matcher rather than a field read: an unparsed message has no code yet, and `undefined` cannot tell
16
+ * "no code in this mail" from "not read yet".
17
+ */
18
+ toHaveOtp(this: ExpectMatcherState, subject: Message | TestInbox, expected?: string): MatcherReturnType;
19
+ /** `expect(message).toHaveLinkTo('app.example.com')`: any link of the message that contains the text. */
20
+ toHaveLinkTo(this: ExpectMatcherState, subject: Message | TestInbox, fragment: string): MatcherReturnType;
21
+ /** `expect(message).toHaveAttachment('invoice.pdf')`, or any attachment without a name. An embedded image is not one. */
22
+ toHaveAttachment(this: ExpectMatcherState, subject: Message | TestInbox, fileName?: string): MatcherReturnType;
23
+ }>;
@@ -0,0 +1,67 @@
1
+ import { FacteurTimeout } from '@facteur-eu/sdk';
2
+ import { expect as base } from '@playwright/test';
3
+ import { attachmentCheck, linkCheck, otpCheck } from './checks.js';
4
+ function isInbox(subject) {
5
+ return typeof subject.waitFor === 'function';
6
+ }
7
+ /** The message a matcher reads: the one it is given, or the last one the inbox received. */
8
+ function messageOf(subject) {
9
+ if (!isInbox(subject))
10
+ return subject;
11
+ return subject.latest ?? 'no message was received yet in this test: await expect(inbox).toReceiveEmail() first, or pass the message';
12
+ }
13
+ /** What did arrive, in one line per message, for the failure of `toReceiveEmail`. */
14
+ function describeArrived(messages) {
15
+ if (messages.length === 0)
16
+ return 'nothing arrived in that inbox during the wait';
17
+ return messages.map((one) => `${one.toAddress ?? 'unknown recipient'}, ${one.subject ? `"${one.subject}"` : 'no subject'} (${one.status ?? 'unknown status'})`).join('; ');
18
+ }
19
+ function withMessage(subject, name, check) {
20
+ const message = messageOf(subject);
21
+ if (typeof message === 'string')
22
+ return { pass: false, name, message: () => message };
23
+ return { name, ...check(message) };
24
+ }
25
+ export const expect = base.extend({
26
+ /**
27
+ * `await expect(inbox).toReceiveEmail({ subject: 'code' })`.
28
+ *
29
+ * The wait is the server's: the criteria go out once and the connection answers as soon as a message
30
+ * matches. The criteria are Facteur's (substrings of the subject, the body, the sender...). The message found is
31
+ * kept on the inbox (`inbox.latest`) and attached to the report.
32
+ */
33
+ async toReceiveEmail(inbox, criteria = {}) {
34
+ try {
35
+ await inbox.waitFor(criteria);
36
+ return { pass: true, name: 'toReceiveEmail', message: () => `expected no message matching ${JSON.stringify(criteria)} at ${inbox.address()}, one arrived` };
37
+ }
38
+ catch (error) {
39
+ if (!(error instanceof FacteurTimeout))
40
+ throw error;
41
+ return {
42
+ pass: false,
43
+ name: 'toReceiveEmail',
44
+ message: () => [
45
+ `No message matched ${JSON.stringify(criteria)} at ${inbox.address()}.`,
46
+ `Waited ${Math.round(error.waitedMs / 1000)}s. What did arrive: ${describeArrived(error.arrived)}.`,
47
+ ].join('\n'),
48
+ };
49
+ }
50
+ },
51
+ /**
52
+ * `expect(message).toHaveOtp('123456')`, or `expect(inbox).toHaveOtp()` for the last message received.
53
+ * A matcher rather than a field read: an unparsed message has no code yet, and `undefined` cannot tell
54
+ * "no code in this mail" from "not read yet".
55
+ */
56
+ toHaveOtp(subject, expected) {
57
+ return withMessage(subject, 'toHaveOtp', (message) => otpCheck(message, expected));
58
+ },
59
+ /** `expect(message).toHaveLinkTo('app.example.com')`: any link of the message that contains the text. */
60
+ toHaveLinkTo(subject, fragment) {
61
+ return withMessage(subject, 'toHaveLinkTo', (message) => linkCheck(message, fragment));
62
+ },
63
+ /** `expect(message).toHaveAttachment('invoice.pdf')`, or any attachment without a name. An embedded image is not one. */
64
+ toHaveAttachment(subject, fileName) {
65
+ return withMessage(subject, 'toHaveAttachment', (message) => attachmentCheck(message, fileName));
66
+ },
67
+ });
@@ -0,0 +1,15 @@
1
+ import type { Message } from '@facteur-eu/sdk';
2
+ /** One file for the Playwright report. */
3
+ export type ReportAttachment = {
4
+ name: string;
5
+ contentType: string;
6
+ body: Buffer;
7
+ };
8
+ /**
9
+ * The message, as the report shows it: its JSON (the extracted fields, the links) and the source of its HTML body.
10
+ *
11
+ * The HTML body comes from whoever sent the mail. The report serves an attachment under its content type, from
12
+ * the report's own origin: as `text/html`, a `<script>` in a received mail would run there. It is attached as
13
+ * `text/plain`, under a `.html.txt` name, so the report shows the source and never renders it.
14
+ */
15
+ export declare function reportAttachments(message: Message): ReportAttachment[];
package/dist/report.js ADDED
@@ -0,0 +1,16 @@
1
+ /**
2
+ * The message, as the report shows it: its JSON (the extracted fields, the links) and the source of its HTML body.
3
+ *
4
+ * The HTML body comes from whoever sent the mail. The report serves an attachment under its content type, from
5
+ * the report's own origin: as `text/html`, a `<script>` in a received mail would run there. It is attached as
6
+ * `text/plain`, under a `.html.txt` name, so the report shows the source and never renders it.
7
+ */
8
+ export function reportAttachments(message) {
9
+ const attachments = [
10
+ { name: `facteur-${message.id}.json`, contentType: 'application/json', body: Buffer.from(JSON.stringify(message, null, 2)) },
11
+ ];
12
+ if (message.htmlBody) {
13
+ attachments.push({ name: `facteur-${message.id}.html.txt`, contentType: 'text/plain', body: Buffer.from(message.htmlBody) });
14
+ }
15
+ return attachments;
16
+ }
package/dist/tag.d.ts ADDED
@@ -0,0 +1,27 @@
1
+ /**
2
+ * The tag that makes a test's address its own: the part after the `+` in `test+<tag>@<inbox domain>`.
3
+ *
4
+ * Every component answers one way of reading another test's mail:
5
+ * - the title and a short hash of its full path (project, file, describe blocks): two tests that share
6
+ * a title in two files do not share an address;
7
+ * - the parallel slot: two tests running at once do not share it. The slot, not the worker index,
8
+ * because Playwright starts a new worker after a failure and gives it a new index, while the slot
9
+ * is kept; the attempt number below is then what tells the retry from the first try;
10
+ * - the attempt number: a retried test does not read the mail its first attempt received;
11
+ * - the run: a suite that uses a kept inbox (`FACTEUR_INBOX`) does not read the mail of the previous run.
12
+ */
13
+ /** Lower-case letters and digits joined by single dashes, cut at `max`; never empty. */
14
+ export declare function slug(text: string, max?: number): string;
15
+ export type TagParts = {
16
+ /** Playwright's `testInfo.titlePath`. */
17
+ titlePath: string[];
18
+ /** Playwright's `testInfo.title`. */
19
+ title: string;
20
+ /** Playwright's `testInfo.parallelIndex`. */
21
+ parallelIndex: number;
22
+ /** Playwright's `testInfo.retry`: 0 on the first attempt. */
23
+ retry: number;
24
+ /** One value for the whole run (see `runId` in `fixtures.ts`). */
25
+ runId: string;
26
+ };
27
+ export declare function tagFor({ titlePath, title, parallelIndex, retry, runId }: TagParts): string;
package/dist/tag.js ADDED
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The tag that makes a test's address its own: the part after the `+` in `test+<tag>@<inbox domain>`.
3
+ *
4
+ * Every component answers one way of reading another test's mail:
5
+ * - the title and a short hash of its full path (project, file, describe blocks): two tests that share
6
+ * a title in two files do not share an address;
7
+ * - the parallel slot: two tests running at once do not share it. The slot, not the worker index,
8
+ * because Playwright starts a new worker after a failure and gives it a new index, while the slot
9
+ * is kept; the attempt number below is then what tells the retry from the first try;
10
+ * - the attempt number: a retried test does not read the mail its first attempt received;
11
+ * - the run: a suite that uses a kept inbox (`FACTEUR_INBOX`) does not read the mail of the previous run.
12
+ */
13
+ /** Lower-case letters and digits joined by single dashes, cut at `max`; never empty. */
14
+ export function slug(text, max = 24) {
15
+ const clean = text
16
+ .toLowerCase()
17
+ .replace(/[^a-z0-9]+/g, '-')
18
+ .replace(/^-+|-+$/g, '')
19
+ .slice(0, max)
20
+ .replace(/-+$/, '');
21
+ return clean || 'test';
22
+ }
23
+ /** FNV-1a over the text, in base 36: short, stable from one process to the next, not a security hash. */
24
+ function shortHash(text) {
25
+ let hash = 0x811c9dc5;
26
+ for (let index = 0; index < text.length; index++) {
27
+ hash ^= text.charCodeAt(index);
28
+ hash = Math.imul(hash, 0x01000193) >>> 0;
29
+ }
30
+ return hash.toString(36);
31
+ }
32
+ export function tagFor({ titlePath, title, parallelIndex, retry, runId }) {
33
+ return `${slug(title)}-${shortHash(titlePath.join('›'))}-p${parallelIndex}r${retry}-${runId}`;
34
+ }
package/dist/wait.d.ts ADDED
@@ -0,0 +1,7 @@
1
+ import type { TestInfo } from '@playwright/test';
2
+ /**
3
+ * How long to hold when the caller does not say: what is left of the test's timeout, less two seconds,
4
+ * so that the failure written is the plugin's (what did arrive) and not Playwright's own timeout message.
5
+ * `testInfo.timeout` is 0 when timeouts are off; the ceiling alone applies then.
6
+ */
7
+ export declare function boundedWait(testInfo: Pick<TestInfo, 'timeout'>, startedAt: number, asked?: number, now?: number): number;
package/dist/wait.js ADDED
@@ -0,0 +1,14 @@
1
+ /** The API holds a wait for five minutes at most. */
2
+ const MAX_WAIT_MS = 300_000;
3
+ /** Left to the test after the wait, to write the failure message inside the test's timeout. */
4
+ const MARGIN_MS = 2_000;
5
+ /**
6
+ * How long to hold when the caller does not say: what is left of the test's timeout, less two seconds,
7
+ * so that the failure written is the plugin's (what did arrive) and not Playwright's own timeout message.
8
+ * `testInfo.timeout` is 0 when timeouts are off; the ceiling alone applies then.
9
+ */
10
+ export function boundedWait(testInfo, startedAt, asked, now = Date.now()) {
11
+ const left = testInfo.timeout > 0 ? testInfo.timeout - (now - startedAt) - MARGIN_MS : MAX_WAIT_MS;
12
+ const ceiling = Math.max(1_000, Math.min(left, MAX_WAIT_MS));
13
+ return asked === undefined ? ceiling : Math.max(1, Math.min(asked, ceiling));
14
+ }
package/package.json CHANGED
@@ -1,51 +1,67 @@
1
1
  {
2
- "name": "playwright-facteur",
3
- "version": "1.0.0",
4
- "type": "module",
5
- "description": "Receive email in your Playwright tests: a fixture that waits, matchers that assert, and the message attached to the report",
6
- "license": "MIT",
7
- "keywords": [
8
- "playwright",
9
- "email testing",
10
- "e2e",
11
- "otp",
12
- "2fa",
13
- "qa",
14
- "test automation",
15
- "fixture"
16
- ],
17
- "engines": {
18
- "node": ">=20"
19
- },
20
- "exports": {
21
- ".": {
22
- "types": "./index.d.mts",
23
- "default": "./index.mjs"
2
+ "name": "playwright-facteur",
3
+ "version": "2.0.0",
4
+ "description": "Receive email in your Playwright tests: an inbox fixture, matchers for codes, links and attachments, and the message attached to the report.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "keywords": [
8
+ "playwright",
9
+ "email testing",
10
+ "e2e",
11
+ "otp",
12
+ "qa",
13
+ "fixture"
14
+ ],
15
+ "homepage": "https://facteur.eu",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/Aliud-Corp/facteur-sdk.git",
19
+ "directory": "packages/playwright-facteur"
20
+ },
21
+ "bugs": {
22
+ "url": "https://github.com/Aliud-Corp/facteur-sdk/issues"
23
+ },
24
+ "main": "./dist/index.js",
25
+ "types": "./dist/index.d.ts",
26
+ "exports": {
27
+ ".": {
28
+ "types": "./dist/index.d.ts",
29
+ "default": "./dist/index.js"
30
+ },
31
+ "./package.json": "./package.json"
32
+ },
33
+ "files": [
34
+ "dist",
35
+ "README.md",
36
+ "LICENSE"
37
+ ],
38
+ "engines": {
39
+ "node": ">=22"
40
+ },
41
+ "publishConfig": {
42
+ "access": "public",
43
+ "provenance": true
44
+ },
45
+ "scripts": {
46
+ "build": "tsc -p tsconfig.build.json",
47
+ "typecheck": "tsc --noEmit -p tsconfig.json",
48
+ "lint": "eslint . --max-warnings 0",
49
+ "test": "vitest run --passWithNoTests"
50
+ },
51
+ "dependencies": {
52
+ "@facteur-eu/sdk": "^2.0.0"
53
+ },
54
+ "peerDependencies": {
55
+ "@playwright/test": ">=1.60.0"
56
+ },
57
+ "devDependencies": {
58
+ "@eslint/js": "10.0.1",
59
+ "@playwright/test": "1.60.0",
60
+ "@types/node": "24.19.0",
61
+ "eslint": "10.4.1",
62
+ "globals": "17.6.0",
63
+ "typescript": "6.0.3",
64
+ "typescript-eslint": "8.59.3",
65
+ "vitest": "4.1.6"
24
66
  }
25
- },
26
- "files": [
27
- "index.mjs",
28
- "index.d.mts",
29
- "README.md",
30
- "LICENSE"
31
- ],
32
- "dependencies": {
33
- "@facteur-eu/sdk": "^1.0.0"
34
- },
35
- "peerDependencies": {
36
- "@playwright/test": ">=1.40.0"
37
- },
38
- "repository": {
39
- "type": "git",
40
- "url": "git+https://github.com/facteur-eu/facteur.git",
41
- "directory": "packages/playwright-facteur"
42
- },
43
- "homepage": "https://facteur.eu",
44
- "bugs": {
45
- "url": "https://github.com/facteur-eu/facteur/issues"
46
- },
47
- "publishConfig": {
48
- "access": "public",
49
- "provenance": true
50
- }
51
67
  }
package/index.d.mts DELETED
@@ -1,57 +0,0 @@
1
- /**
2
- * Types for `index.mjs`, hand-written beside it — see `@facteur-eu/sdk` for why nothing
3
- * here is compiled.
4
- *
5
- * The matcher declarations are the part that earns its keep: without them
6
- * `expect(inbox).toReceiveEmail(...)` is a type error in the suites this package exists
7
- * for, which are written in TypeScript.
8
- */
9
-
10
- import type { Inbox, Message, SearchCriteria, Facteur } from '@facteur-eu/sdk';
11
- import type { TestType, PlaywrightTestArgs, PlaywrightTestOptions, PlaywrightWorkerArgs, PlaywrightWorkerOptions } from '@playwright/test';
12
-
13
- /** The inbox as a test holds it: shared with its worker, addressed to this test alone. */
14
- export interface TestInbox {
15
- id: string;
16
- domain?: string;
17
- /** The sub-address tag for this test: worker, retry and title. */
18
- tag: string;
19
- /** `test+<tag>@<inbox>.inbox.facteur.eu`, with `local` replacing `test`. */
20
- address(local?: string): string;
21
- /** Wait for a message addressed to this test. Attaches it to the report. */
22
- waitFor(criteria?: Omit<SearchCriteria, 'inbox'>): Promise<Message>;
23
- /** Everything currently in the shared inbox, this test's mail and its neighbours'. */
24
- messages(): Promise<Message[]>;
25
- }
26
-
27
- export interface FacteurFixtures {
28
- /** The client, one per worker. */
29
- facteur: Facteur;
30
- /** The inbox, opened once per worker or named by `FACTEUR_INBOX`. */
31
- facteurInbox: Inbox;
32
- /** This test's view onto it. */
33
- inbox: TestInbox;
34
- }
35
-
36
- export declare const test: TestType<
37
- PlaywrightTestArgs & PlaywrightTestOptions & FacteurFixtures,
38
- PlaywrightWorkerArgs & PlaywrightWorkerOptions & FacteurFixtures
39
- >;
40
-
41
- declare global {
42
- namespace PlaywrightTest {
43
- interface Matchers<R, T> {
44
- /** Wait for a message matching the criteria, and attach it to the report. */
45
- toReceiveEmail(criteria?: Omit<SearchCriteria, 'inbox'>): Promise<R>;
46
- /** A one-time code was extracted; optionally, this exact one. */
47
- toHaveOtp(expected?: string): R;
48
- /** A link whose URL contains this fragment. */
49
- toHaveLinkTo(fragment: string): R;
50
- /** A real attachment; an inline signature image is never counted. */
51
- toHaveAttachment(fileName?: string): R;
52
- }
53
- }
54
- }
55
-
56
- export { expect } from '@playwright/test';
57
- export { FacteurTimeout } from '@facteur-eu/sdk';
package/index.mjs DELETED
@@ -1,274 +0,0 @@
1
- /**
2
- * Facteur inside Playwright: a fixture that waits, matchers that assert, and the message
3
- * that arrived attached to the report.
4
- *
5
- * **Why this exists when a ten-line fixture would do.** The objection is a fair one:
6
- * Playwright's fixtures make a plugin less indispensable than Cypress's command registry.
7
- * Four things answer it, and none of them is a wrapper around a call:
8
- *
9
- * 1. **The address is derived from the test, not written by hand.** Worker index, test
10
- * title and retry number make a sub-address no other test can collide with, which is
11
- * what lets a suite run at `--workers=16` against one inbox.
12
- * 2. **The matchers are retried by Playwright's own engine** and rewrite their failure.
13
- * `await expect(inbox).toReceiveEmail({ subject: /code/ })` inherits the test's
14
- * timeout and prints what did arrive. An `await` on a promise does neither.
15
- * 3. **The message lands in the report.** `testInfo.attach` puts the subject, the
16
- * headers, the extracted fields and the HTML body next to the failure — the
17
- * difference between "the test failed" and "here is the mail that arrived instead".
18
- * 4. **The wait ceiling follows the worker count.** The API refuses past twenty open
19
- * waits per organization; the plugin knows `workerInfo`, a hand-written fixture does
20
- * not.
21
- *
22
- * **One inbox per worker, not one per test — and that is a product decision, not a
23
- * shortcut.** Every address ending in an inbox's domain arrives without being created
24
- * first, so a sub-address per test isolates just as well as an inbox per test would, at
25
- * no cost. Creating one per test would also walk straight into the inbox ceiling, which
26
- * is one on the free plan and three on Solo: the isolation would work on a laptop and
27
- * fail the first time somebody ran the suite on the plan they actually pay for.
28
- */
29
-
30
- import { test as base, expect } from '@playwright/test';
31
- import { Facteur, FacteurTimeout, addressFor } from '@facteur-eu/sdk';
32
-
33
- /** Characters that survive in the local part of an address, and read back on a screen. */
34
- const slug = (text) =>
35
- text
36
- .toLowerCase()
37
- .replace(/[^a-z0-9]+/g, '-')
38
- .replace(/^-|-$/g, '')
39
- .slice(0, 40);
40
-
41
- /**
42
- * The Playwright fixtures, and the object a test actually holds.
43
- *
44
- * `inbox` is per test even though the inbox itself is per worker: what the test gets is a
45
- * view onto the shared inbox carrying *its* address, which is the thing that must not be
46
- * shared.
47
- */
48
- export const test = base.extend({
49
- /** The client, one per worker: it holds the wait queue, which is per process. */
50
- facteur: [
51
- async ({}, use, workerInfo) => {
52
- const client = new Facteur({
53
- /*
54
- * Half the workers' ceiling, floored at one. Twenty waits is per *organization*,
55
- * so every worker of every suite in that organization shares it — a client that
56
- * spent it alone would push the refusal onto whoever started second.
57
- */
58
- maxConcurrentWaits: Math.max(1, Math.floor(16 / Math.max(1, workerInfo.config.workers))),
59
- });
60
- await use(client);
61
- },
62
- { scope: 'worker' },
63
- ],
64
-
65
- /**
66
- * The inbox, opened once per worker and destroyed with it.
67
- *
68
- * `FACTEUR_INBOX` names an existing one, which is what a suite on a plan with a single
69
- * inbox does — and what most suites end up doing, since an inbox is a stable address
70
- * worth putting in a CI secret rather than a thing to create four times a minute.
71
- */
72
- facteurInbox: [
73
- async ({ facteur }, use, workerInfo) => {
74
- const existing = process.env.FACTEUR_INBOX;
75
- if (existing) {
76
- const inboxes = await facteur.inboxes.list();
77
- const found = inboxes.find((one) => one.id === existing);
78
- if (!found) {
79
- throw new Error(
80
- `FACTEUR_INBOX names ${existing}, which this key does not reach. Check the id on the inbox screen, or widen the key's workspaces.`,
81
- );
82
- }
83
- await use(found);
84
- return;
85
- }
86
-
87
- const opened = await facteur.inboxes.create({
88
- name: `playwright w${workerInfo.workerIndex}`,
89
- workspace: process.env.FACTEUR_WORKSPACE,
90
- });
91
-
92
- try {
93
- await use(opened);
94
- } finally {
95
- /*
96
- * Destroying is how an inbox is purged — there is no route that empties one. It
97
- * is also free: an operation is the message received, never the call.
98
- */
99
- await facteur.inboxes.delete(opened.id).catch(() => {});
100
- }
101
- },
102
- { scope: 'worker' },
103
- ],
104
-
105
- /**
106
- * What a test holds: the inbox, plus an address that belongs to this test alone.
107
- *
108
- * The tag carries the worker, the retry and the title. The retry matters more than it
109
- * looks: without it a retried test reads the mail its own first attempt received, and
110
- * passes for the wrong reason exactly when something is already flaky.
111
- */
112
- inbox: async ({ facteur, facteurInbox }, use, testInfo) => {
113
- const tag = `${slug(testInfo.title)}-w${testInfo.workerIndex}r${testInfo.retry}-${Date.now().toString(36)}`;
114
- const startedAt = Date.now();
115
-
116
- /**
117
- * How long to hold, when the caller does not say: whatever is left of the test's own
118
- * timeout, less two seconds to fail inside it.
119
- *
120
- * This is the difference between two failures. Held for a fixed thirty seconds inside
121
- * a ninety-second test, a missing mail reads as a passing wait followed by a failed
122
- * assertion; held past the test's timeout, Playwright kills the test and prints its
123
- * own message about a slow test. Neither says the mail never came. Ending two seconds
124
- * early means the plugin's diagnostic — what did arrive instead — is the last thing
125
- * written, which is the only one worth reading.
126
- *
127
- * `testInfo.timeout` is `0` when timeouts are disabled, and the SDK's own default
128
- * applies then: an unbounded wait would hang a suite on a mail that is never sent.
129
- */
130
- const remainingWait = () => {
131
- if (!testInfo.timeout) return undefined;
132
- const left = testInfo.timeout - (Date.now() - startedAt) - 2_000;
133
- return Math.max(1_000, Math.min(left, 300_000));
134
- };
135
-
136
- await use({
137
- id: facteurInbox.id,
138
- domain: facteurInbox.domain,
139
- tag,
140
- address: (local = 'test') => addressFor(facteurInbox, tag, { local }),
141
-
142
- async waitFor(criteria = {}) {
143
- const message = await facteur.messages.waitFor({
144
- inbox: facteurInbox.id,
145
- sentTo: tag,
146
- wait: remainingWait(),
147
- ...criteria,
148
- });
149
- await attach(testInfo, message);
150
- return message;
151
- },
152
-
153
- async messages() {
154
- return facteur.inboxes.messages(facteurInbox.id);
155
- },
156
- });
157
- },
158
- });
159
-
160
- /**
161
- * The message, in the HTML report.
162
- *
163
- * Two attachments rather than one: the JSON is what a developer reads for the extracted
164
- * fields, and the HTML body is what they open to see what the customer would have seen.
165
- * Both are named after the test, so a failure with three mails in it stays readable.
166
- */
167
- async function attach(testInfo, message) {
168
- await testInfo.attach(`facteur-${message.id}.json`, {
169
- contentType: 'application/json',
170
- body: Buffer.from(JSON.stringify(message, null, 2)),
171
- });
172
-
173
- if (message.html?.body) {
174
- await testInfo.attach(`facteur-${message.id}.html`, {
175
- contentType: 'text/html',
176
- body: Buffer.from(message.html.body),
177
- });
178
- }
179
- }
180
-
181
- /** What a failed match should say, given what the inbox actually holds. */
182
- function describe(messages) {
183
- if (!messages.length) return 'nothing arrived in that inbox during the wait';
184
- return messages
185
- .slice(0, 5)
186
- .map((one) => `${one.to} · ${one.subject ?? 'no subject'} (${one.status})`)
187
- .join('; ');
188
- }
189
-
190
- expect.extend({
191
- /**
192
- * `await expect(inbox).toReceiveEmail({ subject: /code/ })`.
193
- *
194
- * The wait is the server's, so this does not poll: it hands the criteria over and the
195
- * connection answers the moment a message matches. What Playwright adds is the failure
196
- * message and the timeout the test already carries.
197
- */
198
- async toReceiveEmail(inbox, criteria = {}) {
199
- try {
200
- const message = await inbox.waitFor(criteria);
201
- this.received = message;
202
- return {
203
- pass: true,
204
- message: () => `expected no message matching ${JSON.stringify(criteria)}, one arrived`,
205
- name: 'toReceiveEmail',
206
- };
207
- } catch (error) {
208
- if (!(error instanceof FacteurTimeout)) throw error;
209
- const arrived = describe(error.arrived ?? []);
210
- return {
211
- pass: false,
212
- name: 'toReceiveEmail',
213
- message: () =>
214
- [
215
- `No message matched ${JSON.stringify(criteria)} at ${inbox.address()}.`,
216
- `Waited ${Math.round((error.waitedMs ?? 0) / 1000)}s. What did arrive: ${arrived}.`,
217
- ].join('\n'),
218
- };
219
- }
220
- },
221
-
222
- /**
223
- * `expect(message).toHaveOtp()` — and the reason it is a matcher rather than a field
224
- * read: an unparsed message has no `otp`, and asserting on `undefined` cannot tell
225
- * "there is no code in this mail" from "the code is not extracted yet".
226
- */
227
- toHaveOtp(message, expected) {
228
- if (message.status !== 'parsed') {
229
- return {
230
- pass: false,
231
- name: 'toHaveOtp',
232
- message: () =>
233
- `the message is ${message.status}, so nothing derived from its body is populated yet — read status before any extracted field`,
234
- };
235
- }
236
-
237
- const pass = expected === undefined ? Boolean(message.otp) : message.otp === expected;
238
- return {
239
- pass,
240
- name: 'toHaveOtp',
241
- message: () =>
242
- expected === undefined
243
- ? `expected a one-time code, the message carries ${message.otp ?? 'none'}`
244
- : `expected the code ${expected}, the message carries ${message.otp ?? 'none'}`,
245
- };
246
- },
247
-
248
- /** `expect(message).toHaveLinkTo('app.example.com')` — host, or any part of the URL. */
249
- toHaveLinkTo(message, fragment) {
250
- const links = (message.links ?? []).map((link) => link.href ?? link.url ?? '');
251
- const pass = links.some((href) => String(href).includes(fragment));
252
- return {
253
- pass,
254
- name: 'toHaveLinkTo',
255
- message: () =>
256
- `expected a link containing ${fragment}, the message carries ${links.length ? links.join(', ') : 'no link'}`,
257
- };
258
- },
259
-
260
- /** `expect(message).toHaveAttachment('invoice.pdf')` — a real one; a signature image is not. */
261
- toHaveAttachment(message, fileName) {
262
- const names = (message.attachments ?? []).map((one) => one.fileName);
263
- const pass = fileName === undefined ? names.length > 0 : names.includes(fileName);
264
- return {
265
- pass,
266
- name: 'toHaveAttachment',
267
- message: () =>
268
- `expected ${fileName ?? 'an attachment'}, the message carries ${names.length ? names.join(', ') : 'none'} (inline images are never counted)`,
269
- };
270
- },
271
- });
272
-
273
- export { expect };
274
- export { FacteurTimeout } from '@facteur-eu/sdk';