playwright-facteur 0.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/LICENSE +21 -0
- package/README.md +101 -2
- package/dist/checks.d.ts +11 -0
- package/dist/checks.js +27 -0
- package/dist/fixtures.d.ts +34 -0
- package/dist/fixtures.js +83 -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 +65 -5
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Facteur
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,5 +1,104 @@
|
|
|
1
1
|
# playwright-facteur
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
5
|
+
Needs `@playwright/test` 1.60.0 or later, and Node 22 or later. It builds on `@facteur-eu/sdk`.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --save-dev playwright-facteur @playwright/test
|
|
11
|
+
```
|
|
12
|
+
|
|
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:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
export FACTEUR_API_KEY=fk_...
|
|
17
|
+
export FACTEUR_INBOX=<the id of the inbox>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Write a test
|
|
21
|
+
|
|
22
|
+
Import `test` and `expect` from `playwright-facteur` instead of `@playwright/test`.
|
|
23
|
+
|
|
24
|
+
```ts
|
|
25
|
+
import { expect, test } from 'playwright-facteur'
|
|
26
|
+
|
|
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()
|
|
31
|
+
|
|
32
|
+
await expect(inbox).toReceiveEmail({ subject: 'confirmation code' })
|
|
33
|
+
await expect(inbox).toHaveLinkTo('/confirm')
|
|
34
|
+
await page.getByLabel('Code').fill(inbox.latest!.otp!)
|
|
35
|
+
})
|
|
36
|
+
```
|
|
37
|
+
|
|
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.
|
|
39
|
+
|
|
40
|
+
## Fixtures
|
|
41
|
+
|
|
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`. |
|
|
47
|
+
|
|
48
|
+
An `inbox` has:
|
|
49
|
+
|
|
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. |
|
|
57
|
+
|
|
58
|
+
## What isolates one test from another
|
|
59
|
+
|
|
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).
|
|
74
|
+
```
|
|
75
|
+
|
|
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
|
+
## Licence
|
|
103
|
+
|
|
104
|
+
MIT.
|
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,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
|
+
}
|
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 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
|
+
}>;
|
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 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
|
+
});
|
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 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,7 +1,67 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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"
|
|
66
|
+
}
|
|
7
67
|
}
|