playwright-facteur 1.0.0 → 3.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 +81 -57
- package/dist/checks.d.ts +11 -0
- package/dist/checks.js +27 -0
- package/dist/fixtures.d.ts +34 -0
- package/dist/fixtures.js +80 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.js +3 -0
- package/dist/matchers.d.ts +23 -0
- package/dist/matchers.js +67 -0
- package/dist/report.d.ts +15 -0
- package/dist/report.js +16 -0
- package/dist/tag.d.ts +27 -0
- package/dist/tag.js +34 -0
- package/dist/wait.d.ts +7 -0
- package/dist/wait.js +14 -0
- package/package.json +67 -48
- package/index.d.mts +0 -57
- package/index.mjs +0 -274
package/README.md
CHANGED
|
@@ -1,89 +1,113 @@
|
|
|
1
1
|
# playwright-facteur
|
|
2
2
|
|
|
3
|
-
Receive email in your Playwright tests, and
|
|
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
|
-
|
|
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
|
-
|
|
14
|
-
expect(message).toHaveOtp();
|
|
7
|
+
## Install
|
|
15
8
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
});
|
|
9
|
+
```sh
|
|
10
|
+
npm install --save-dev playwright-facteur @playwright/test
|
|
19
11
|
```
|
|
20
12
|
|
|
21
|
-
|
|
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
|
-
|
|
32
|
-
**Settings → API keys**.
|
|
33
|
-
|
|
34
|
-
## What you get
|
|
20
|
+
## Write a test
|
|
35
21
|
|
|
36
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
50
|
-
await expect(inbox).
|
|
51
|
-
|
|
52
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
67
|
-
sub-address isolates a test as well as a whole inbox would.
|
|
48
|
+
An `inbox` has:
|
|
68
49
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
-
|
|
58
|
+
## What isolates one test from another
|
|
74
59
|
|
|
75
|
-
|
|
76
|
-
|
|
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
|
+
The plugin searches for the mail every second. A wait lasts as long as what is left of the test's own timeout, less two seconds, with five minutes at most. A key may send 600 requests a minute: past that, the plugin waits the `Retry-After` of the `429` and goes on, so a suite with many workers slows down instead of failing. 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
|
-
|
|
80
|
-
|
|
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.
|
|
92
|
+
|
|
93
|
+
## Environment
|
|
94
|
+
|
|
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`. |
|
|
101
|
+
|
|
102
|
+
## Versions
|
|
103
|
+
|
|
104
|
+
This package follows semantic versioning. A change that breaks your code only ships in a new major version. It is tested with Playwright 1.60 and accepts any later 1.x release. Playwright 2 will need a new major version of this package.
|
|
105
|
+
|
|
106
|
+
## Support and security
|
|
81
107
|
|
|
82
|
-
|
|
108
|
+
Version 3.x receives security fixes until 15 November 2031, five years after 3.0.0 was released. Versions 2.0.0, 1.0.0 and 0.0.0 receive none: they target an API that no longer exists. Upgrade to 3.x.
|
|
83
109
|
|
|
84
|
-
|
|
85
|
-
sized from your worker count, so the surplus waits its turn instead of coming back as a
|
|
86
|
-
`429`.
|
|
110
|
+
To report a vulnerability, email security@facteur.eu or use the private reporting of the repository, never a public issue. The [security policy](https://github.com/Aliud-Corp/facteur-sdk/blob/main/SECURITY.md) says what happens next. Each [release](https://github.com/Aliud-Corp/facteur-sdk/releases) carries the software bill of materials (CycloneDX) of its version.
|
|
87
111
|
|
|
88
112
|
## Licence
|
|
89
113
|
|
package/dist/checks.d.ts
ADDED
|
@@ -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 {};
|
package/dist/fixtures.js
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
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.
|
|
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) => {
|
|
18
|
+
await use(new Facteur());
|
|
19
|
+
},
|
|
20
|
+
{ scope: 'worker' },
|
|
21
|
+
],
|
|
22
|
+
// The inbox of the worker. `FACTEUR_INBOX` names an existing one, which is what a plan with a single inbox needs.
|
|
23
|
+
// Without it, the worker opens an inbox (in `FACTEUR_WORKSPACE`, or the default workspace) and deletes it at the end.
|
|
24
|
+
facteurInbox: [
|
|
25
|
+
async ({ facteur }, use, workerInfo) => {
|
|
26
|
+
const existing = process.env.FACTEUR_INBOX;
|
|
27
|
+
if (existing) {
|
|
28
|
+
const found = (await facteur.inboxes.list()).find((one) => one.id === existing);
|
|
29
|
+
if (!found) {
|
|
30
|
+
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.`);
|
|
31
|
+
}
|
|
32
|
+
await use(found);
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
const opened = await facteur.inboxes.create({
|
|
36
|
+
name: `playwright ${runId} w${workerInfo.workerIndex}`,
|
|
37
|
+
workspace: process.env.FACTEUR_WORKSPACE,
|
|
38
|
+
});
|
|
39
|
+
try {
|
|
40
|
+
await use(opened);
|
|
41
|
+
}
|
|
42
|
+
finally {
|
|
43
|
+
await facteur.inboxes.delete(opened.id).catch(() => undefined);
|
|
44
|
+
}
|
|
45
|
+
},
|
|
46
|
+
{ scope: 'worker' },
|
|
47
|
+
],
|
|
48
|
+
inbox: async ({ facteur, facteurInbox }, use, testInfo) => {
|
|
49
|
+
const tag = tagFor({ titlePath: testInfo.titlePath, title: testInfo.title, parallelIndex: testInfo.parallelIndex, retry: testInfo.retry, runId });
|
|
50
|
+
const startedAt = Date.now();
|
|
51
|
+
const inboxId = facteurInbox.id;
|
|
52
|
+
let latest = null;
|
|
53
|
+
await use({
|
|
54
|
+
id: inboxId,
|
|
55
|
+
domain: facteurInbox.domain,
|
|
56
|
+
tag,
|
|
57
|
+
get latest() {
|
|
58
|
+
return latest;
|
|
59
|
+
},
|
|
60
|
+
address: (local = 'test') => addressFor(facteurInbox, tag, { local }),
|
|
61
|
+
async waitFor(criteria = {}) {
|
|
62
|
+
const { timeout, ...search } = criteria;
|
|
63
|
+
const wait = boundedWait(testInfo, startedAt, timeout);
|
|
64
|
+
// `+<tag>@` and not the bare tag: a tag that is the start of another tag does not match it.
|
|
65
|
+
const found = await facteur.messages.waitFor({ ...search, inbox: inboxId, sentTo: `+${tag}@`, timeout: wait });
|
|
66
|
+
// The search carries the bodies and the headers, as the read of one message does: no second call.
|
|
67
|
+
latest = found;
|
|
68
|
+
await attach(testInfo, found);
|
|
69
|
+
return found;
|
|
70
|
+
},
|
|
71
|
+
messages: () => facteur.inboxes.messages(inboxId, { limit: 20 }),
|
|
72
|
+
});
|
|
73
|
+
},
|
|
74
|
+
});
|
|
75
|
+
/** The message, in the report: its JSON and the source of its HTML body, never a rendered page (see `reportAttachments`). */
|
|
76
|
+
async function attach(testInfo, message) {
|
|
77
|
+
for (const { name, contentType, body } of reportAttachments(message)) {
|
|
78
|
+
await testInfo.attach(name, { contentType, body });
|
|
79
|
+
}
|
|
80
|
+
}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -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 client searches every second until a message matches or the time runs out; the API holds nothing
|
|
9
|
+
* open. 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
|
+
}>;
|
package/dist/matchers.js
ADDED
|
@@ -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 client searches every second until a message matches or the time runs out; the API holds nothing
|
|
30
|
+
* open. 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
|
+
});
|
package/dist/report.d.ts
ADDED
|
@@ -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 longest wait the plugin keeps searching for, when the test has no timeout of its own: five minutes. */
|
|
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,70 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
"
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
"
|
|
22
|
-
|
|
23
|
-
|
|
2
|
+
"name": "playwright-facteur",
|
|
3
|
+
"version": "3.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": "^3.0.0"
|
|
53
|
+
},
|
|
54
|
+
"peerDependencies": {
|
|
55
|
+
"@playwright/test": ">=1.60.0 <2"
|
|
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.12"
|
|
66
|
+
},
|
|
67
|
+
"overrides": {
|
|
68
|
+
"minimatch": "11.0.8"
|
|
24
69
|
}
|
|
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
70
|
}
|
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';
|