@mailstest/playwright 0.0.0-stage → 0.1.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 +365 -2
- package/dist/client-BkgYBSna.d.ts +415 -0
- package/dist/client-Bq5lAfzY.js +651 -0
- package/dist/client.d.ts +2 -0
- package/dist/client.js +1 -0
- package/dist/fixtures.d.ts +144 -0
- package/dist/fixtures.js +152 -0
- package/dist/index.d.ts +20 -0
- package/dist/index.js +202 -0
- package/package.json +79 -3
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { i as InboxHandle } from "./client-BkgYBSna.js";
|
|
2
|
+
import { Fixtures } from "@playwright/test";
|
|
3
|
+
/** The domain of a fixture address when the suite names none: reserved by RFC 2606, so nothing real is ever reached. */
|
|
4
|
+
export declare const DEFAULT_ADDRESS_DOMAIN = "example.com";
|
|
5
|
+
/**
|
|
6
|
+
* How long the one request the fixture makes — the teardown's clear — may take
|
|
7
|
+
* before the fixture gives up on it. A server that accepts the connection and
|
|
8
|
+
* never answers would otherwise hold the worker on a teardown nothing bounds;
|
|
9
|
+
* the ordinary request path installs no timer for this verb, so the bound is
|
|
10
|
+
* the fixture's to set.
|
|
11
|
+
*/
|
|
12
|
+
export declare const RUN_ACT_TIMEOUT_MS = 10000;
|
|
13
|
+
/**
|
|
14
|
+
* The fixture's own timeout. A test-scoped fixture's teardown shares one fresh
|
|
15
|
+
* slot with the suite's `afterEach` hooks, so without a timeout of its own it
|
|
16
|
+
* spends a budget someone else's hook can exhaust. A fixture's slot is also ONE
|
|
17
|
+
* object across both phases (the runner spreads the setup's description into
|
|
18
|
+
* the teardown's, so `slot.elapsed` accumulates). Setup sends nothing and
|
|
19
|
+
* teardown sends one bounded request: two bounds is the longest path, and
|
|
20
|
+
* covers it with room for the runner's own bookkeeping.
|
|
21
|
+
*/
|
|
22
|
+
export declare const FIXTURE_TIMEOUT_MS: number;
|
|
23
|
+
export interface MailstestConfig {
|
|
24
|
+
/** Origin of the mailstest deployment. Required. */
|
|
25
|
+
baseUrl: string;
|
|
26
|
+
/** A workspace API key, from the suite's secret store. Required. */
|
|
27
|
+
apiKey: string;
|
|
28
|
+
/** The app's inbox — the one every test shares. Required. */
|
|
29
|
+
inboxId: string;
|
|
30
|
+
/** Domain of the address each test gets. Defaults to example.com; for an app that refuses it at sign-up. */
|
|
31
|
+
addressDomain?: string;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* The option this package adds to a suite's Playwright configuration. A
|
|
35
|
+
* TypeScript `defineConfig` types its `use` block, and a fixture declared in
|
|
36
|
+
* another module does not widen it — so a suite writes
|
|
37
|
+
* `defineConfig<MailstestOptions>({ use: { mailstestConfig: … } })` and the
|
|
38
|
+
* documented setup compiles.
|
|
39
|
+
*/
|
|
40
|
+
export interface MailstestOptions {
|
|
41
|
+
mailstestConfig: MailstestConfig;
|
|
42
|
+
}
|
|
43
|
+
/** What a test destructures as `mailstest`. Carries no key material. */
|
|
44
|
+
export interface MailstestRun {
|
|
45
|
+
/** The app's inbox. Its unscoped reads and clear refuse: read through `inbox.recipient(address)`. */
|
|
46
|
+
readonly inbox: InboxHandle;
|
|
47
|
+
/** The address no other test shares — the one the app under test sends to. */
|
|
48
|
+
readonly address: string;
|
|
49
|
+
}
|
|
50
|
+
/** What `provisionRun` answers: the run the fixture yields plus what the teardown needs. */
|
|
51
|
+
export interface ProvisionedRun {
|
|
52
|
+
run: MailstestRun;
|
|
53
|
+
/**
|
|
54
|
+
* The teardown's one act, BOUND to the client the fixture made and captured
|
|
55
|
+
* before the test is handed anything. `run.inbox` is the test's to
|
|
56
|
+
* substitute methods on; capturing the function ends that family — what
|
|
57
|
+
* teardown calls was fixed before anything else could reach it.
|
|
58
|
+
*/
|
|
59
|
+
clear: (options: {
|
|
60
|
+
signal: AbortSignal;
|
|
61
|
+
}) => Promise<unknown>;
|
|
62
|
+
address: string;
|
|
63
|
+
/** Scrubs the key from arbitrary text. A closure, never a field: the secret stays as unreachable here as inside a client. */
|
|
64
|
+
redact(text: string): string;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Raised when a teardown act fails for a reason other than the key or the
|
|
68
|
+
* inbox being gone. Carries every failed act, so one error reports a whole
|
|
69
|
+
* teardown rather than the first thing that broke.
|
|
70
|
+
*
|
|
71
|
+
* The carried errors are REDACTED COPIES, never the originals: a client
|
|
72
|
+
* redacts a response only of the one secret it holds, so a body a server
|
|
73
|
+
* echoed could still carry an inbox's SMTP password when the run key's client
|
|
74
|
+
* raised it. Since a reporter serializes the whole error — this property
|
|
75
|
+
* included — the redaction has to reach the copies, not only the message
|
|
76
|
+
* composed above them.
|
|
77
|
+
*/
|
|
78
|
+
export declare class MailstestTeardownError extends Error {
|
|
79
|
+
readonly failures: {
|
|
80
|
+
act: string;
|
|
81
|
+
error: unknown;
|
|
82
|
+
}[];
|
|
83
|
+
constructor(failures: {
|
|
84
|
+
act: string;
|
|
85
|
+
error: unknown;
|
|
86
|
+
}[], redact: (text: string) => string);
|
|
87
|
+
}
|
|
88
|
+
/** Raised before any request when the suite left the fixture unconfigured. */
|
|
89
|
+
export declare class MailstestConfigError extends Error {
|
|
90
|
+
constructor(message: string);
|
|
91
|
+
}
|
|
92
|
+
/**
|
|
93
|
+
* `t-<title slug>-<10 hex>@<domain>`. The slug is the title folded to ASCII
|
|
94
|
+
* lowercase words and cut so the local part stays inside the 64 characters
|
|
95
|
+
* SMTP allows (2 + 51 + 1 + 10); the random tail is what makes two tests with
|
|
96
|
+
* one title, or one test on two workers, different addresses.
|
|
97
|
+
*/
|
|
98
|
+
export declare function composeAddress(title: string, domain?: string): string;
|
|
99
|
+
/**
|
|
100
|
+
* Composes the test's address and hands back the app's inbox beside it. Sends
|
|
101
|
+
* no request: a misconfigured suite fails here, before anything is spent, and
|
|
102
|
+
* a worker killed after this point has left nothing behind.
|
|
103
|
+
*/
|
|
104
|
+
export declare function provisionRun(config: MailstestConfig, options: {
|
|
105
|
+
name: string;
|
|
106
|
+
actTimeoutMs?: number;
|
|
107
|
+
},
|
|
108
|
+
/**
|
|
109
|
+
* The transport the client uses. A parameter of the seam, never a field of
|
|
110
|
+
* `mailstestConfig`: that config IS the suite-facing Playwright option, and
|
|
111
|
+
* a fetch it could carry would be a test-only path on the shipped surface.
|
|
112
|
+
* Only a direct caller of this function — the package's unit tests, and a
|
|
113
|
+
* test body driving a run itself — passes one; the fixture below never
|
|
114
|
+
* does.
|
|
115
|
+
*/
|
|
116
|
+
fetchImpl?: typeof fetch): Promise<ProvisionedRun>;
|
|
117
|
+
/**
|
|
118
|
+
* The run's one act: clear the address's mail, bounded. A refused key and an
|
|
119
|
+
* inbox already gone leave the test's result untouched; anything else is
|
|
120
|
+
* raised as one `MailstestTeardownError`.
|
|
121
|
+
*/
|
|
122
|
+
export declare function teardownRun(provisioned: ProvisionedRun,
|
|
123
|
+
/**
|
|
124
|
+
* The bound. A parameter of the seam rather than a suite-facing setting, for
|
|
125
|
+
* the reason the transport is one — only the package's own unit lane needs a
|
|
126
|
+
* value other than the shipped constant.
|
|
127
|
+
*/
|
|
128
|
+
{ actTimeoutMs }?: {
|
|
129
|
+
actTimeoutMs?: number;
|
|
130
|
+
}): Promise<void>;
|
|
131
|
+
/**
|
|
132
|
+
* The fixtures a suite composes onto its own `test`:
|
|
133
|
+
*
|
|
134
|
+
* import { test as base } from '@playwright/test';
|
|
135
|
+
* import { mailstestFixtures } from '@mailstest/playwright/fixtures';
|
|
136
|
+
* export const test = base.extend(mailstestFixtures);
|
|
137
|
+
*
|
|
138
|
+
* `mailstestConfig` is an option fixture, so the suite's configuration `use`
|
|
139
|
+
* section sets it once; `test.use` sets it per file as it sets any fixture.
|
|
140
|
+
*/
|
|
141
|
+
export declare const mailstestFixtures: Fixtures<{
|
|
142
|
+
mailstestConfig: MailstestConfig;
|
|
143
|
+
mailstest: MailstestRun;
|
|
144
|
+
}>;
|
package/dist/fixtures.js
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
import { c as markFixtureHandle, i as createClient, o as redactSecret, t as MailstestApiError } from "./client-Bq5lAfzY.js";
|
|
2
|
+
// src/fixtures.ts
|
|
3
|
+
/** The domain of a fixture address when the suite names none: reserved by RFC 2606, so nothing real is ever reached. */
|
|
4
|
+
const DEFAULT_ADDRESS_DOMAIN = "example.com";
|
|
5
|
+
/**
|
|
6
|
+
* How long the one request the fixture makes — the teardown's clear — may take
|
|
7
|
+
* before the fixture gives up on it. A server that accepts the connection and
|
|
8
|
+
* never answers would otherwise hold the worker on a teardown nothing bounds;
|
|
9
|
+
* the ordinary request path installs no timer for this verb, so the bound is
|
|
10
|
+
* the fixture's to set.
|
|
11
|
+
*/
|
|
12
|
+
const RUN_ACT_TIMEOUT_MS = 1e4;
|
|
13
|
+
/**
|
|
14
|
+
* The fixture's own timeout. A test-scoped fixture's teardown shares one fresh
|
|
15
|
+
* slot with the suite's `afterEach` hooks, so without a timeout of its own it
|
|
16
|
+
* spends a budget someone else's hook can exhaust. A fixture's slot is also ONE
|
|
17
|
+
* object across both phases (the runner spreads the setup's description into
|
|
18
|
+
* the teardown's, so `slot.elapsed` accumulates). Setup sends nothing and
|
|
19
|
+
* teardown sends one bounded request: two bounds is the longest path, and
|
|
20
|
+
* covers it with room for the runner's own bookkeeping.
|
|
21
|
+
*/
|
|
22
|
+
const FIXTURE_TIMEOUT_MS = 2 * RUN_ACT_TIMEOUT_MS;
|
|
23
|
+
/**
|
|
24
|
+
* Raised when a teardown act fails for a reason other than the key or the
|
|
25
|
+
* inbox being gone. Carries every failed act, so one error reports a whole
|
|
26
|
+
* teardown rather than the first thing that broke.
|
|
27
|
+
*
|
|
28
|
+
* The carried errors are REDACTED COPIES, never the originals: a client
|
|
29
|
+
* redacts a response only of the one secret it holds, so a body a server
|
|
30
|
+
* echoed could still carry an inbox's SMTP password when the run key's client
|
|
31
|
+
* raised it. Since a reporter serializes the whole error — this property
|
|
32
|
+
* included — the redaction has to reach the copies, not only the message
|
|
33
|
+
* composed above them.
|
|
34
|
+
*/
|
|
35
|
+
var MailstestTeardownError = class extends Error {
|
|
36
|
+
failures;
|
|
37
|
+
constructor(failures, redact) {
|
|
38
|
+
super(redact(`mailstest run teardown failed: ${failures.map((f) => `${f.act} (${f.error instanceof Error ? f.error.message : String(f.error)})`).join("; ")}`));
|
|
39
|
+
this.name = "MailstestTeardownError";
|
|
40
|
+
this.failures = failures.map((f) => ({
|
|
41
|
+
act: f.act,
|
|
42
|
+
error: redactError(f.error, redact)
|
|
43
|
+
}));
|
|
44
|
+
}
|
|
45
|
+
};
|
|
46
|
+
/**
|
|
47
|
+
* A copy of `error` carrying no secret the redactor knows. A typed API error
|
|
48
|
+
* keeps its status, its body and its URL — everything a caller debugs with —
|
|
49
|
+
* with each of them scrubbed; anything else becomes a plain error over its
|
|
50
|
+
* scrubbed text.
|
|
51
|
+
*/
|
|
52
|
+
function redactError(error, redact) {
|
|
53
|
+
if (error instanceof MailstestApiError) return new MailstestApiError(error.status, redact(error.body), redact(error.url));
|
|
54
|
+
const copy = new Error(redact(error instanceof Error ? error.message : String(error)));
|
|
55
|
+
copy.name = error instanceof Error ? error.name : "Error";
|
|
56
|
+
return copy;
|
|
57
|
+
}
|
|
58
|
+
function redactorFor(secrets) {
|
|
59
|
+
const present = secrets.filter((s) => typeof s === "string" && s.length > 0);
|
|
60
|
+
return (text) => present.reduce((acc, secret) => redactSecret(acc, secret), text);
|
|
61
|
+
}
|
|
62
|
+
/** Raised before any request when the suite left the fixture unconfigured. */
|
|
63
|
+
var MailstestConfigError = class extends Error {
|
|
64
|
+
constructor(message) {
|
|
65
|
+
super(message);
|
|
66
|
+
this.name = "MailstestConfigError";
|
|
67
|
+
}
|
|
68
|
+
};
|
|
69
|
+
/**
|
|
70
|
+
* `t-<title slug>-<10 hex>@<domain>`. The slug is the title folded to ASCII
|
|
71
|
+
* lowercase words and cut so the local part stays inside the 64 characters
|
|
72
|
+
* SMTP allows (2 + 51 + 1 + 10); the random tail is what makes two tests with
|
|
73
|
+
* one title, or one test on two workers, different addresses.
|
|
74
|
+
*/
|
|
75
|
+
function composeAddress(title, domain = DEFAULT_ADDRESS_DOMAIN) {
|
|
76
|
+
return `t-${title.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").slice(0, 51).replace(/^-+|-+$/g, "") || "test"}-${crypto.randomUUID().replaceAll("-", "").slice(0, 10)}@${domain}`;
|
|
77
|
+
}
|
|
78
|
+
function assertConfigured(config) {
|
|
79
|
+
if (!config) throw new MailstestConfigError("mailstestConfig is not set — give the suite `use: { mailstestConfig: { baseUrl, apiKey, inboxId } }`.");
|
|
80
|
+
if (!config.baseUrl) throw new MailstestConfigError("mailstestConfig.baseUrl is required.");
|
|
81
|
+
if (!config.apiKey) throw new MailstestConfigError("mailstestConfig.apiKey is required.");
|
|
82
|
+
if (!config.inboxId) throw new MailstestConfigError("mailstestConfig.inboxId is required — the app inbox's id, shown in its credential reveal.");
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Composes the test's address and hands back the app's inbox beside it. Sends
|
|
86
|
+
* no request: a misconfigured suite fails here, before anything is spent, and
|
|
87
|
+
* a worker killed after this point has left nothing behind.
|
|
88
|
+
*/
|
|
89
|
+
async function provisionRun(config, options, fetchImpl) {
|
|
90
|
+
assertConfigured(config);
|
|
91
|
+
const inbox = createClient({
|
|
92
|
+
baseUrl: config.baseUrl,
|
|
93
|
+
apiKey: config.apiKey,
|
|
94
|
+
fetchImpl
|
|
95
|
+
}).inbox(config.inboxId);
|
|
96
|
+
markFixtureHandle(inbox);
|
|
97
|
+
const address = composeAddress(options.name, config.addressDomain);
|
|
98
|
+
return {
|
|
99
|
+
run: Object.freeze({
|
|
100
|
+
inbox,
|
|
101
|
+
address
|
|
102
|
+
}),
|
|
103
|
+
clear: inbox.recipient(address).clear,
|
|
104
|
+
address,
|
|
105
|
+
redact: redactorFor([config.apiKey])
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
function isGoneAlready(error) {
|
|
109
|
+
if (!(error instanceof MailstestApiError)) return false;
|
|
110
|
+
if (error.status === 401) return true;
|
|
111
|
+
if (error.status !== 404) return false;
|
|
112
|
+
try {
|
|
113
|
+
return JSON.parse(error.body)?.error === "not-found";
|
|
114
|
+
} catch {
|
|
115
|
+
return false;
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* The run's one act: clear the address's mail, bounded. A refused key and an
|
|
120
|
+
* inbox already gone leave the test's result untouched; anything else is
|
|
121
|
+
* raised as one `MailstestTeardownError`.
|
|
122
|
+
*/
|
|
123
|
+
async function teardownRun(provisioned, { actTimeoutMs = RUN_ACT_TIMEOUT_MS } = {}) {
|
|
124
|
+
try {
|
|
125
|
+
await provisioned.clear({ signal: AbortSignal.timeout(actTimeoutMs) });
|
|
126
|
+
} catch (error) {
|
|
127
|
+
if (isGoneAlready(error)) return;
|
|
128
|
+
throw new MailstestTeardownError([{
|
|
129
|
+
act: `clear mail of ${provisioned.address}`,
|
|
130
|
+
error
|
|
131
|
+
}], provisioned.redact);
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* The fixtures a suite composes onto its own `test`:
|
|
136
|
+
*
|
|
137
|
+
* import { test as base } from '@playwright/test';
|
|
138
|
+
* import { mailstestFixtures } from '@mailstest/playwright/fixtures';
|
|
139
|
+
* export const test = base.extend(mailstestFixtures);
|
|
140
|
+
*
|
|
141
|
+
* `mailstestConfig` is an option fixture, so the suite's configuration `use`
|
|
142
|
+
* section sets it once; `test.use` sets it per file as it sets any fixture.
|
|
143
|
+
*/
|
|
144
|
+
const mailstestFixtures = {
|
|
145
|
+
mailstestConfig: [void 0, { option: true }],
|
|
146
|
+
mailstest: [async ({ mailstestConfig }, use, testInfo) => {
|
|
147
|
+
const provisioned = await provisionRun(mailstestConfig, { name: testInfo.title });
|
|
148
|
+
await use(provisioned.run);
|
|
149
|
+
await teardownRun(provisioned);
|
|
150
|
+
}, { timeout: FIXTURE_TIMEOUT_MS }]
|
|
151
|
+
};
|
|
152
|
+
export { DEFAULT_ADDRESS_DOMAIN, FIXTURE_TIMEOUT_MS, MailstestConfigError, MailstestTeardownError, RUN_ACT_TIMEOUT_MS, composeAddress, mailstestFixtures, provisionRun, teardownRun };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { C as MessageParts, S as MessageLink, T as extractLinks, _ as buildV1Url, a as InboxIssuance, b as redactSecret, c as MailstestClient, d as MessageCodes, f as MessageDetail, g as WaitResult, h as RecipientHandle, i as InboxHandle, l as MailstestClientOptions, m as MessageSummary, n as ApiKeyReveal, o as InboxSummary, p as MessageLinks, r as InboxCredentials, s as MailstestApiError, t as ApiKeyIssuance, u as MailstestScopeError, v as createClient, w as extractCodes, x as MessageCode, y as parseFilename } from "./client-BkgYBSna.js";
|
|
2
|
+
interface ReceiveEmailCriteria {
|
|
3
|
+
/** The envelope recipient the mail was delivered to — a plain string, matched case-insensitively by the server's scope. Reads go through `inbox.recipient(to)`, so it is never tested here. */
|
|
4
|
+
to?: string;
|
|
5
|
+
subject?: string | RegExp;
|
|
6
|
+
from?: string | RegExp;
|
|
7
|
+
bodyContains?: string;
|
|
8
|
+
}
|
|
9
|
+
export declare const expect: import("@playwright/test").Expect<{
|
|
10
|
+
toReceiveEmail(inbox: InboxHandle, criteria: ReceiveEmailCriteria, options?: {
|
|
11
|
+
timeout?: number;
|
|
12
|
+
}): Promise<{
|
|
13
|
+
pass: true;
|
|
14
|
+
message: () => string;
|
|
15
|
+
} | {
|
|
16
|
+
pass: false;
|
|
17
|
+
message: () => string;
|
|
18
|
+
}>;
|
|
19
|
+
}>;
|
|
20
|
+
export { ApiKeyIssuance, ApiKeyReveal, InboxCredentials, InboxHandle, InboxIssuance, InboxSummary, MailstestApiError, MailstestClient, MailstestClientOptions, MailstestScopeError, type MessageCode, MessageCodes, MessageDetail, type MessageLink, MessageLinks, type MessageParts, MessageSummary, type ReceiveEmailCriteria, RecipientHandle, WaitResult, buildV1Url, createClient, extractCodes, extractLinks, parseFilename, redactSecret };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
import { a as parseFilename, i as createClient, l as extractCodes, n as MailstestScopeError, o as redactSecret, r as buildV1Url, s as isFixtureHandle, t as MailstestApiError, u as extractLinks } from "./client-Bq5lAfzY.js";
|
|
2
|
+
import { expect as expect$1 } from "@playwright/test";
|
|
3
|
+
// src/criteria.ts
|
|
4
|
+
function testStateless(re, value) {
|
|
5
|
+
return (re.global || re.sticky ? new RegExp(re.source, re.flags) : re).test(value);
|
|
6
|
+
}
|
|
7
|
+
function matchesValue(value, criterion) {
|
|
8
|
+
if (criterion === void 0) return true;
|
|
9
|
+
if (value === null) return false;
|
|
10
|
+
return typeof criterion === "string" ? value === criterion : testStateless(criterion, value);
|
|
11
|
+
}
|
|
12
|
+
function summaryMatches(summary, criteria) {
|
|
13
|
+
return matchesValue(summary.subject, criteria.subject) && matchesValue(summary.senderAddress, criteria.from);
|
|
14
|
+
}
|
|
15
|
+
function bodyMatches(detail, criteria) {
|
|
16
|
+
if (criteria.bodyContains === void 0) return true;
|
|
17
|
+
const { bodyContains } = criteria;
|
|
18
|
+
return (detail.text ?? "").includes(bodyContains) || (detail.html ?? "").includes(bodyContains);
|
|
19
|
+
}
|
|
20
|
+
function describeCriteria(criteria) {
|
|
21
|
+
const parts = [];
|
|
22
|
+
if (criteria.to !== void 0) parts.push(`to ${criteria.to}`);
|
|
23
|
+
if (criteria.subject !== void 0) parts.push(`subject ${String(criteria.subject)}`);
|
|
24
|
+
if (criteria.from !== void 0) parts.push(`from ${String(criteria.from)}`);
|
|
25
|
+
if (criteria.bodyContains !== void 0) parts.push(`bodyContains "${criteria.bodyContains}"`);
|
|
26
|
+
return parts.join(", ");
|
|
27
|
+
}
|
|
28
|
+
// src/matcher.ts
|
|
29
|
+
/**
|
|
30
|
+
* One candidate against every criterion. `signal`, when given, is the walk's
|
|
31
|
+
* own deadline-bound AbortSignal — it bounds the detail read the same way the
|
|
32
|
+
* page fetch is already bounded, so a stalled candidate read cannot hang the
|
|
33
|
+
* assertion past its timeout; an abort caught here reports 'expired' rather
|
|
34
|
+
* than propagating. A 404 on any read is a vanished candidate (cleared or
|
|
35
|
+
* ring-evicted mid-scan).
|
|
36
|
+
*/
|
|
37
|
+
async function evaluate(inbox, summary, criteria, signal) {
|
|
38
|
+
try {
|
|
39
|
+
return summaryMatches(summary, criteria) && (criteria.bodyContains === void 0 || bodyMatches(await inbox.getMessage(summary.id, { signal }), criteria)) ? { kind: "match" } : { kind: "reject" };
|
|
40
|
+
} catch (err) {
|
|
41
|
+
if (err instanceof MailstestApiError && err.status === 404) return { kind: "gone" };
|
|
42
|
+
const abortLike = err instanceof MailstestApiError && err.status === 0 || err instanceof Error && err.name === "AbortError";
|
|
43
|
+
if (signal?.aborted && abortLike) return { kind: "expired" };
|
|
44
|
+
throw err;
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
async function receiveEmail(inbox, criteria, opts) {
|
|
48
|
+
if (criteria.to === void 0 && isFixtureHandle(inbox)) throw new MailstestScopeError("mailstest: toReceiveEmail on the run fixture's inbox needs `to` (the fixture's address) — without it the assertion would see other tests' mail");
|
|
49
|
+
const reader = criteria.to === void 0 ? inbox : inbox.recipient(criteria.to);
|
|
50
|
+
const now = opts.now ?? (() => performance.now());
|
|
51
|
+
const deadline = now() + opts.timeout;
|
|
52
|
+
const observed = /* @__PURE__ */ new Map();
|
|
53
|
+
const fail = () => ({
|
|
54
|
+
pass: false,
|
|
55
|
+
observed: [...observed.values()]
|
|
56
|
+
});
|
|
57
|
+
const scan = async (batch) => {
|
|
58
|
+
const ac = new AbortController();
|
|
59
|
+
const remaining = deadline - now();
|
|
60
|
+
const timer = remaining > 0 ? setTimeout(() => ac.abort(), remaining) : void 0;
|
|
61
|
+
if (remaining <= 0) ac.abort();
|
|
62
|
+
try {
|
|
63
|
+
for (const candidate of batch) {
|
|
64
|
+
if (now() > deadline) return "expired";
|
|
65
|
+
const v = await evaluate(inbox, candidate, criteria, ac.signal);
|
|
66
|
+
if (v.kind === "expired") return "expired";
|
|
67
|
+
if (v.kind === "match") return now() > deadline ? "expired" : candidate;
|
|
68
|
+
if (v.kind === "reject") observed.set(candidate.id, candidate);
|
|
69
|
+
else if (v.kind === "gone") observed.delete(candidate.id);
|
|
70
|
+
}
|
|
71
|
+
return;
|
|
72
|
+
} finally {
|
|
73
|
+
clearTimeout(timer);
|
|
74
|
+
}
|
|
75
|
+
};
|
|
76
|
+
const scanPages = async (watchId) => {
|
|
77
|
+
const ac = new AbortController();
|
|
78
|
+
const remaining = deadline - now();
|
|
79
|
+
const timer = remaining > 0 ? setTimeout(() => ac.abort(), remaining) : void 0;
|
|
80
|
+
if (remaining <= 0) ac.abort();
|
|
81
|
+
let newestId;
|
|
82
|
+
let sawWatchId = false;
|
|
83
|
+
let cursor;
|
|
84
|
+
try {
|
|
85
|
+
for (;;) {
|
|
86
|
+
let page;
|
|
87
|
+
try {
|
|
88
|
+
page = await reader.listMessagesPage({
|
|
89
|
+
cursor,
|
|
90
|
+
signal: ac.signal
|
|
91
|
+
});
|
|
92
|
+
} catch (err) {
|
|
93
|
+
const abortLike = err instanceof MailstestApiError && err.status === 0 || err instanceof Error && err.name === "AbortError";
|
|
94
|
+
if (ac.signal.aborted && abortLike) return {
|
|
95
|
+
match: void 0,
|
|
96
|
+
expired: true,
|
|
97
|
+
newestId,
|
|
98
|
+
sawWatchId
|
|
99
|
+
};
|
|
100
|
+
throw err;
|
|
101
|
+
}
|
|
102
|
+
for (const candidate of page.messages) {
|
|
103
|
+
if (newestId === void 0) newestId = candidate.id;
|
|
104
|
+
if (watchId !== void 0 && candidate.id === watchId) sawWatchId = true;
|
|
105
|
+
if (now() > deadline) return {
|
|
106
|
+
match: void 0,
|
|
107
|
+
expired: true,
|
|
108
|
+
newestId,
|
|
109
|
+
sawWatchId
|
|
110
|
+
};
|
|
111
|
+
const v = await evaluate(inbox, candidate, criteria, ac.signal);
|
|
112
|
+
if (v.kind === "expired") return {
|
|
113
|
+
match: void 0,
|
|
114
|
+
expired: true,
|
|
115
|
+
newestId,
|
|
116
|
+
sawWatchId
|
|
117
|
+
};
|
|
118
|
+
if (v.kind === "match") {
|
|
119
|
+
if (now() > deadline) return {
|
|
120
|
+
match: void 0,
|
|
121
|
+
expired: true,
|
|
122
|
+
newestId,
|
|
123
|
+
sawWatchId
|
|
124
|
+
};
|
|
125
|
+
return {
|
|
126
|
+
match: candidate,
|
|
127
|
+
expired: false,
|
|
128
|
+
newestId,
|
|
129
|
+
sawWatchId
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
if (v.kind === "reject") observed.set(candidate.id, candidate);
|
|
133
|
+
else if (v.kind === "gone") observed.delete(candidate.id);
|
|
134
|
+
}
|
|
135
|
+
if (page.nextCursor === null) return {
|
|
136
|
+
match: void 0,
|
|
137
|
+
expired: false,
|
|
138
|
+
newestId,
|
|
139
|
+
sawWatchId
|
|
140
|
+
};
|
|
141
|
+
cursor = page.nextCursor;
|
|
142
|
+
}
|
|
143
|
+
} finally {
|
|
144
|
+
clearTimeout(timer);
|
|
145
|
+
}
|
|
146
|
+
};
|
|
147
|
+
const initial = await scanPages();
|
|
148
|
+
if (initial.expired) return fail();
|
|
149
|
+
if (initial.match) return {
|
|
150
|
+
pass: true,
|
|
151
|
+
message: initial.match
|
|
152
|
+
};
|
|
153
|
+
let since = initial.newestId;
|
|
154
|
+
for (;;) {
|
|
155
|
+
const remaining = deadline - now();
|
|
156
|
+
if (remaining <= 0) return fail();
|
|
157
|
+
const startedEmpty = since === void 0;
|
|
158
|
+
const r = await reader.waitForEmail({
|
|
159
|
+
timeout: remaining,
|
|
160
|
+
since
|
|
161
|
+
});
|
|
162
|
+
if (r.timedOut || r.message === null) return fail();
|
|
163
|
+
if (startedEmpty) {
|
|
164
|
+
const returned = r.message;
|
|
165
|
+
const reconciled = await scanPages(returned.id);
|
|
166
|
+
if (reconciled.expired) return fail();
|
|
167
|
+
if (reconciled.match) return {
|
|
168
|
+
pass: true,
|
|
169
|
+
message: reconciled.match
|
|
170
|
+
};
|
|
171
|
+
if (!reconciled.sawWatchId) {
|
|
172
|
+
const only = await scan([returned]);
|
|
173
|
+
if (only === "expired") return fail();
|
|
174
|
+
if (only) return {
|
|
175
|
+
pass: true,
|
|
176
|
+
message: only
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
since = reconciled.newestId ?? returned.id;
|
|
180
|
+
continue;
|
|
181
|
+
}
|
|
182
|
+
const next = await scan([r.message]);
|
|
183
|
+
if (next === "expired") return fail();
|
|
184
|
+
if (next) return {
|
|
185
|
+
pass: true,
|
|
186
|
+
message: next
|
|
187
|
+
};
|
|
188
|
+
since = r.message.id;
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
// src/index.ts
|
|
192
|
+
const expect = expect$1.extend({ async toReceiveEmail(inbox, criteria, options) {
|
|
193
|
+
const outcome = await receiveEmail(inbox, criteria, { timeout: options?.timeout ?? 3e4 });
|
|
194
|
+
return outcome.pass ? {
|
|
195
|
+
pass: true,
|
|
196
|
+
message: () => inbox.redactSecrets(`expected inbox ${inbox.id} not to receive a matching email, but "${outcome.message.subject}" matched`)
|
|
197
|
+
} : {
|
|
198
|
+
pass: false,
|
|
199
|
+
message: () => inbox.redactSecrets(`expected inbox ${inbox.id} to receive an email matching ${describeCriteria(criteria)} within the timeout; observed instead: ${outcome.observed.length === 0 ? "no mail" : outcome.observed.map((m) => `"${m.subject}" from ${m.senderAddress}`).join(", ")}` + (criteria.to === void 0 ? "" : `; the same mail in the dashboard: ${inbox.recipient(criteria.to).dashboardUrl}`))
|
|
200
|
+
};
|
|
201
|
+
} });
|
|
202
|
+
export { MailstestApiError, MailstestScopeError, buildV1Url, createClient, expect, extractCodes, extractLinks, parseFilename, redactSecret };
|
package/package.json
CHANGED
|
@@ -1,6 +1,82 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mailstest/playwright",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Catch the email your app sends in a Playwright test and assert on it: an address per test, a blocking wait, one matcher",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/mailstest/playwright.git"
|
|
9
|
+
},
|
|
10
|
+
"homepage": "https://github.com/mailstest/playwright#readme",
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/mailstest/playwright/issues"
|
|
13
|
+
},
|
|
14
|
+
"keywords": [
|
|
15
|
+
"playwright",
|
|
16
|
+
"email-testing",
|
|
17
|
+
"magic-link",
|
|
18
|
+
"otp",
|
|
19
|
+
"e2e",
|
|
20
|
+
"ci",
|
|
21
|
+
"resend",
|
|
22
|
+
"sendgrid"
|
|
23
|
+
],
|
|
24
|
+
"type": "module",
|
|
25
|
+
"engines": {
|
|
26
|
+
"node": "^20.19.0 || >=22.12.0"
|
|
27
|
+
},
|
|
28
|
+
"exports": {
|
|
29
|
+
".": {
|
|
30
|
+
"types": "./dist/index.d.ts",
|
|
31
|
+
"default": "./dist/index.js"
|
|
32
|
+
},
|
|
33
|
+
"./client": {
|
|
34
|
+
"types": "./dist/client.d.ts",
|
|
35
|
+
"default": "./dist/client.js"
|
|
36
|
+
},
|
|
37
|
+
"./fixtures": {
|
|
38
|
+
"types": "./dist/fixtures.d.ts",
|
|
39
|
+
"default": "./dist/fixtures.js"
|
|
40
|
+
}
|
|
41
|
+
},
|
|
42
|
+
"files": [
|
|
43
|
+
"dist"
|
|
44
|
+
],
|
|
45
|
+
"publishConfig": {
|
|
46
|
+
"access": "public"
|
|
47
|
+
},
|
|
48
|
+
"dependencies": {
|
|
49
|
+
"zod": "^4.6.7"
|
|
50
|
+
},
|
|
51
|
+
"peerDependencies": {
|
|
52
|
+
"@playwright/test": "^1.64.0"
|
|
53
|
+
},
|
|
54
|
+
"peerDependenciesMeta": {
|
|
55
|
+
"@playwright/test": {
|
|
56
|
+
"optional": true
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
"devDependencies": {
|
|
60
|
+
"@playwright/test": "1.64.1",
|
|
61
|
+
"@types/node": "26.6.6",
|
|
62
|
+
"tsdown": "0.23.5",
|
|
63
|
+
"tsx": "4.23.15",
|
|
64
|
+
"typescript": "7.0.2"
|
|
65
|
+
},
|
|
66
|
+
"scripts": {
|
|
67
|
+
"typecheck": "tsc --noEmit",
|
|
68
|
+
"test": "node --import tsx --test 'src/**/*.test.ts'",
|
|
69
|
+
"build": "tsdown"
|
|
70
|
+
},
|
|
71
|
+
"types": "./dist/index.d.ts",
|
|
72
|
+
"typesVersions": {
|
|
73
|
+
"*": {
|
|
74
|
+
"client": [
|
|
75
|
+
"dist/client.d.ts"
|
|
76
|
+
],
|
|
77
|
+
"fixtures": [
|
|
78
|
+
"dist/fixtures.d.ts"
|
|
79
|
+
]
|
|
80
|
+
}
|
|
81
|
+
}
|
|
6
82
|
}
|