@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
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Vladimir Panov
|
|
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,3 +1,366 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mailstest/playwright
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Catch the email your app sends in a Playwright test and assert on it: an
|
|
4
|
+
address per test, a blocking wait, one matcher. Mail sent to mailstest is
|
|
5
|
+
captured and never delivered anywhere.
|
|
6
|
+
|
|
7
|
+
## Quickstart
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install -D @mailstest/playwright @playwright/test
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { test as base } from '@playwright/test';
|
|
15
|
+
import { expect } from '@mailstest/playwright';
|
|
16
|
+
import { mailstestFixtures } from '@mailstest/playwright/fixtures';
|
|
17
|
+
|
|
18
|
+
const test = base.extend(mailstestFixtures);
|
|
19
|
+
test.use({ mailstestConfig: { baseUrl: process.env.MAILSTEST_BASE_URL!, apiKey: process.env.MAILSTEST_API_KEY!, inboxId: process.env.MAILSTEST_INBOX_ID! } });
|
|
20
|
+
|
|
21
|
+
test('sign-up sends a confirmation', async ({ page, mailstest }) => {
|
|
22
|
+
await page.goto('/signup'); await page.getByLabel('Email').fill(mailstest.address); await page.getByRole('button', { name: 'Sign up' }).click();
|
|
23
|
+
await expect(mailstest.inbox).toReceiveEmail({ to: mailstest.address, subject: /Confirm/ });
|
|
24
|
+
});
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Set the three `MAILSTEST_*` variables from [Setup](#setup) and run
|
|
28
|
+
`npx playwright test`. Your app sends its confirmation to `mailstest.address`,
|
|
29
|
+
and the assertion passes when that email arrives.
|
|
30
|
+
|
|
31
|
+
## Setup
|
|
32
|
+
|
|
33
|
+
1. **The app's inbox.** Create an inbox in the mailstest dashboard. Its
|
|
34
|
+
credential reveal shows a `.env` snippet: the five `SMTP_*` lines, the
|
|
35
|
+
lines for the Resend and SendGrid SDKs ([Sending paths](#sending-paths)),
|
|
36
|
+
and `MAILSTEST_INBOX_ID`, the inbox's id. Put the sending lines in the
|
|
37
|
+
environment of the app under test. The password is shown once and cannot
|
|
38
|
+
be read again: keep it, or rotate it from the inbox page.
|
|
39
|
+
2. **An API key.** Issue a workspace API key on the dashboard's API Keys
|
|
40
|
+
screen. Its reveal shows `MAILSTEST_BASE_URL`, the address the API answers
|
|
41
|
+
at, and `MAILSTEST_API_KEY`.
|
|
42
|
+
3. **CI secrets.** Put `MAILSTEST_BASE_URL`, `MAILSTEST_API_KEY` and
|
|
43
|
+
`MAILSTEST_INBOX_ID` in your CI secret store.
|
|
44
|
+
|
|
45
|
+
That is the whole setup. Every test shares the one inbox, each under an
|
|
46
|
+
address of its own, so a Free workspace, whose plan covers one inbox, runs any
|
|
47
|
+
number of tests and workers.
|
|
48
|
+
|
|
49
|
+
The SDK needs Node 20.19+ or 22.12+ and `@playwright/test` 1.64 or later. It
|
|
50
|
+
is ESM, and a CommonJS suite loads it with `require`, which Node supports from
|
|
51
|
+
those versions. TypeScript type-checks a CommonJS suite against it under
|
|
52
|
+
`module: commonjs`, or under `nodenext` from TypeScript 5.8. `zod` is its only
|
|
53
|
+
dependency.
|
|
54
|
+
|
|
55
|
+
## The fixture
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
// fixtures.ts
|
|
59
|
+
import { test as base } from '@playwright/test';
|
|
60
|
+
import { mailstestFixtures } from '@mailstest/playwright/fixtures';
|
|
61
|
+
|
|
62
|
+
export const test = base.extend(mailstestFixtures);
|
|
63
|
+
export { expect } from '@mailstest/playwright';
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
```ts
|
|
67
|
+
// playwright.config.ts: the generic is what types the option here
|
|
68
|
+
import { defineConfig } from '@playwright/test';
|
|
69
|
+
import type { MailstestOptions } from '@mailstest/playwright/fixtures';
|
|
70
|
+
|
|
71
|
+
export default defineConfig<MailstestOptions>({
|
|
72
|
+
use: {
|
|
73
|
+
mailstestConfig: {
|
|
74
|
+
baseUrl: process.env.MAILSTEST_BASE_URL!,
|
|
75
|
+
apiKey: process.env.MAILSTEST_API_KEY!,
|
|
76
|
+
inboxId: process.env.MAILSTEST_INBOX_ID!,
|
|
77
|
+
// addressDomain: 'example.org', // example.com unless set
|
|
78
|
+
},
|
|
79
|
+
},
|
|
80
|
+
});
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
// signup.spec.ts
|
|
85
|
+
import { expect, test } from './fixtures';
|
|
86
|
+
|
|
87
|
+
test('sign-up sends a confirmation', async ({ page, mailstest }) => {
|
|
88
|
+
const { inbox, address } = mailstest;
|
|
89
|
+
await signUp(page, address); // the app under test sends to `address`
|
|
90
|
+
await expect(inbox).toReceiveEmail({ to: address, subject: /Confirm your sign-up/ });
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
One test is one address. The fixture sends no request when a test starts: it
|
|
95
|
+
composes `t-<test title>-<random>@example.com`, the title folded to lowercase
|
|
96
|
+
ASCII words, and hands the test the app's inbox beside it.
|
|
97
|
+
|
|
98
|
+
- **The address domain.** Set `addressDomain` for an app that refuses
|
|
99
|
+
`@example.com` at sign-up. The domain only names the address: mailstest
|
|
100
|
+
routes mail by the inbox's credential, never by recipient.
|
|
101
|
+
- **Matching.** `to` is matched against the envelope recipients mailstest
|
|
102
|
+
recorded, so an address the app reaches only by Bcc matches too, and letter
|
|
103
|
+
case does not matter.
|
|
104
|
+
- **Other tests' mail.** The fixture's inbox refuses whatever would reach it:
|
|
105
|
+
`toReceiveEmail` without `to`, and an unscoped list, wait or clear, throw a
|
|
106
|
+
`MailstestScopeError` before any request, naming `to`. Read through the
|
|
107
|
+
address instead ([Address-scoped reads](#address-scoped-reads)).
|
|
108
|
+
- **Teardown.** When the test ends, the fixture clears that address's mail and
|
|
109
|
+
nothing else, in one request bounded at 10 seconds. A refused key or an
|
|
110
|
+
inbox already gone leaves the test's result as it was. Any other failure is
|
|
111
|
+
raised as a `MailstestTeardownError`.
|
|
112
|
+
- **A run that never comes back,** a killed worker or a cancelled build,
|
|
113
|
+
leaves its address's mail in the inbox until the inbox's ring or retention
|
|
114
|
+
removes it ([Limits](#limits)).
|
|
115
|
+
- **Configuration.** `mailstestConfig` is an option fixture: set it once in
|
|
116
|
+
the config's `use`, or per file with `test.use`, as the quickstart does. A
|
|
117
|
+
missing `baseUrl`, `apiKey` or `inboxId` fails the test with a
|
|
118
|
+
`MailstestConfigError` before any request.
|
|
119
|
+
|
|
120
|
+
## Waits and the matcher
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
await expect(inbox).toReceiveEmail(
|
|
124
|
+
{ to: address, subject: /Confirm/, from: 'noreply@example.com', bodyContains: 'confirm' },
|
|
125
|
+
{ timeout: 30_000 },
|
|
126
|
+
);
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
`toReceiveEmail(criteria, { timeout })` passes on the first message that meets
|
|
130
|
+
every criterion: first among the mail already delivered, then among each
|
|
131
|
+
arrival, until the timeout, 30 seconds by default. The criteria are structural
|
|
132
|
+
only, and nothing is fuzzy or model-assisted:
|
|
133
|
+
|
|
134
|
+
| Criterion | Matches |
|
|
135
|
+
|---|---|
|
|
136
|
+
| `to` | a string: any envelope recipient, Bcc included, letter case aside |
|
|
137
|
+
| `subject` | a string, exactly, or a `RegExp` |
|
|
138
|
+
| `from` | the sender's address: a string, exactly, or a `RegExp` |
|
|
139
|
+
| `bodyContains` | a substring of the message's text or HTML part |
|
|
140
|
+
|
|
141
|
+
On a timeout the assertion fails with the criteria, the mail that arrived at
|
|
142
|
+
that address instead, and a link to the dashboard's view of the inbox filtered
|
|
143
|
+
to `to`.
|
|
144
|
+
|
|
145
|
+
`waitForEmail` is the wait the matcher runs on:
|
|
146
|
+
|
|
147
|
+
```ts
|
|
148
|
+
const mine = inbox.recipient(address);
|
|
149
|
+
const first = await mine.waitForEmail({ timeout: 30_000 }); // { timedOut, message }
|
|
150
|
+
if (first.message) {
|
|
151
|
+
const next = await mine.waitForEmail({ since: first.message.id });
|
|
152
|
+
}
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
- **Without `since`,** the wait answers the newest message at once if there is
|
|
156
|
+
one, else the next arrival.
|
|
157
|
+
- **With `since`,** a message id, it answers the first message strictly newer
|
|
158
|
+
than that one: from the backlog at once, else the next arrival. Walking a
|
|
159
|
+
burst this way answers each message once.
|
|
160
|
+
- **Any timeout works.** The API holds one request open for at most 55
|
|
161
|
+
seconds, and the SDK chains as many requests as your timeout needs, with the
|
|
162
|
+
cursor threaded through. A wait the network or a proxy cuts is re-issued
|
|
163
|
+
inside your timeout.
|
|
164
|
+
- **Expiry is a result, not an error:** `{ timedOut: true, message: null }`.
|
|
165
|
+
No mail arriving is an outcome a test can assert on.
|
|
166
|
+
- **A refusal is raised at once** as a `MailstestApiError`: 401 for a revoked
|
|
167
|
+
or expired key; 404 for an unknown inbox or another workspace's; 409 for an
|
|
168
|
+
inbox its plan no longer covers. A key revoked while a wait is open ends
|
|
169
|
+
that wait with a 404 when mail arrives, or with a 401 on the wait's next
|
|
170
|
+
request.
|
|
171
|
+
|
|
172
|
+
## Address-scoped reads
|
|
173
|
+
|
|
174
|
+
`inbox.recipient(address)` is one address's view of the inbox. Every request
|
|
175
|
+
it sends names the address, and every message that comes back is checked for
|
|
176
|
+
it among its `deliveredTo` recipients: a message without it fails the read
|
|
177
|
+
with a `MailstestScopeError` rather than reaching your test.
|
|
178
|
+
|
|
179
|
+
```ts
|
|
180
|
+
const mine = inbox.recipient(address);
|
|
181
|
+
await mine.waitForEmail({ timeout: 30_000 });
|
|
182
|
+
const messages = await mine.listMessages(); // newest first, every page followed
|
|
183
|
+
const onePage = await mine.listMessagesPage(); // { messages, nextCursor }; pass { cursor } for the next
|
|
184
|
+
await mine.clear(); // this address's mail only, pinned included; the fixture does it at teardown
|
|
185
|
+
console.log(mine.dashboardUrl); // the dashboard's view of the inbox filtered to this address
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
## Links and codes
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
const { links } = await inbox.getLinks(messageId); // [{ url, source }]
|
|
192
|
+
const { codes } = await inbox.getCodes(messageId, /\b(\d{6})\b/); // [{ value, source }]
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
- **`getLinks`** answers the links as the message wrote them: the HTML part's
|
|
196
|
+
anchors (`a` and `area` with an `href`) in document order, then the URLs of
|
|
197
|
+
the text part, each once.
|
|
198
|
+
- **`getCodes`** answers what your pattern, a string or a `RegExp` matched
|
|
199
|
+
globally with JavaScript's engine, finds in the subject, then the text part,
|
|
200
|
+
then the HTML part's visible text. A value is the pattern's first capturing
|
|
201
|
+
group when it took part, else the whole match, and each value comes once.
|
|
202
|
+
- **Both are computed in the SDK** from what `getMessage` answers. Nothing is
|
|
203
|
+
fetched, followed or judged. `@mailstest/playwright` exports them as
|
|
204
|
+
`extractLinks(message)` and `extractCodes(message, pattern)` too, for a
|
|
205
|
+
message read over plain HTTP.
|
|
206
|
+
|
|
207
|
+
## Raw and attachments
|
|
208
|
+
|
|
209
|
+
`getRaw(messageId)` answers `{ bytes, filename }`: the message's exact MIME
|
|
210
|
+
bytes as captured, and its download name. The API serves no attachment on its
|
|
211
|
+
own. Read one out of the raw bytes with
|
|
212
|
+
[`postal-mime`](https://www.npmjs.com/package/postal-mime), the parser
|
|
213
|
+
mailstest decodes with:
|
|
214
|
+
|
|
215
|
+
```ts
|
|
216
|
+
import PostalMime from 'postal-mime';
|
|
217
|
+
|
|
218
|
+
const mail = await PostalMime.parse((await inbox.getRaw(messageId)).bytes);
|
|
219
|
+
const pdf = mail.attachments.find((a) => a.filename === 'invoice.pdf');
|
|
220
|
+
// pdf.content is an ArrayBuffer; pdf.mimeType is its content type
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
The other reads and changes of one message are on the inbox too, by id:
|
|
224
|
+
|
|
225
|
+
- **`getMessage(id)`** answers the message decoded once at capture: sender,
|
|
226
|
+
subject, recipients, `deliveredTo`, date, text, HTML, headers and the
|
|
227
|
+
attachment manifest.
|
|
228
|
+
- **`setPinned(id, pinned)`** pins or unpins it, idempotently. A pinned
|
|
229
|
+
message survives both its expiry and ring eviction. Pinning past the
|
|
230
|
+
inbox's cap, a tenth of its ring, fails with a 409.
|
|
231
|
+
- **`deleteMessage(id)`** removes it at once, pinned or not.
|
|
232
|
+
- **`inbox.clear()`** removes the whole inbox's mail and answers the count. It
|
|
233
|
+
resets an inbox a suite owns between runs, and is refused on the fixture's
|
|
234
|
+
inbox.
|
|
235
|
+
|
|
236
|
+
An unknown message id, or one of another workspace's inbox, fails with a 404.
|
|
237
|
+
|
|
238
|
+
## Composing a run by hand
|
|
239
|
+
|
|
240
|
+
A suite that wants an inbox of its own for each run, rather than the app's
|
|
241
|
+
shared one, uses the client directly:
|
|
242
|
+
|
|
243
|
+
```ts
|
|
244
|
+
import { createClient } from '@mailstest/playwright/client';
|
|
245
|
+
|
|
246
|
+
const baseUrl = process.env.MAILSTEST_BASE_URL!;
|
|
247
|
+
const client = createClient({ baseUrl, apiKey: process.env.MAILSTEST_API_KEY! });
|
|
248
|
+
|
|
249
|
+
const run = await client.mintRunKey({ name: `run-${runId}`, expiresIn: 3600 });
|
|
250
|
+
const runClient = createClient({ baseUrl, apiKey: run.key });
|
|
251
|
+
const made = await runClient.createInbox({ name: `run-${runId}`, expiresIn: 3600, maxUses: 20 });
|
|
252
|
+
// point the app under test at smtp.mailstest.com with made.username and made.password
|
|
253
|
+
const inbox = runClient.inbox(made.id);
|
|
254
|
+
|
|
255
|
+
// … and when the run ends:
|
|
256
|
+
await runClient.deleteInbox(made.id, { confirmName: `run-${runId}` });
|
|
257
|
+
await runClient.revokeRunKey(run.id);
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
- **`mintRunKey({ name, expiresIn })`** mints a key that lives `expiresIn`
|
|
261
|
+
seconds, at most 86,400. Only a durable key, one issued in the dashboard,
|
|
262
|
+
mints, and a run key's mint fails with a 403. The key is in this answer and nowhere else.
|
|
263
|
+
- **`createInbox({ name, expiresIn?, maxUses? })`** makes an inbox on the
|
|
264
|
+
key's workspace. Its password is in this answer and nowhere else.
|
|
265
|
+
- `expiresIn`, 1 to 86,400 seconds, is how long the inbox may live. Past it
|
|
266
|
+
the inbox admits no new sender, and mailstest removes it with its mail.
|
|
267
|
+
- `maxUses`, which needs `expiresIn`, is how many authentications its
|
|
268
|
+
credential covers: an SMTP AUTH, or a Resend or SendGrid request that
|
|
269
|
+
captures. A lifetime without it covers one.
|
|
270
|
+
- Omit both for a durable inbox.
|
|
271
|
+
- An inbox counts against the plan's number until it is deleted or removed.
|
|
272
|
+
A workspace that holds as many as its plan covers fails the create with a
|
|
273
|
+
409.
|
|
274
|
+
- **`deleteInbox(id, { confirmName })`** removes an inbox with its credential,
|
|
275
|
+
its mail and the bytes behind it. `confirmName` must equal its name exactly.
|
|
276
|
+
- **`revokeRunKey(id)`** revokes a run key of the workspace, its own or
|
|
277
|
+
another run's. A durable key, another workspace's key and an unknown id
|
|
278
|
+
fail with a 404.
|
|
279
|
+
- **`idempotencyKey`,** up to 64 characters, on `createInbox` or `mintRunKey`:
|
|
280
|
+
a repeat of the identical request within a day answers what the first
|
|
281
|
+
attempt made instead of making a second, so a run recovers when a create
|
|
282
|
+
commits and its answer is lost on the way. That answer is a replay,
|
|
283
|
+
`replayed: true`, with the password or key `null`, since it was shown once.
|
|
284
|
+
Without an idempotency key the answer is always an issuance and is typed as
|
|
285
|
+
one. With one, narrow on `replayed` before reading the secret.
|
|
286
|
+
|
|
287
|
+
`client.listInboxes()` answers the workspace's inboxes with their plan limits,
|
|
288
|
+
and `client.inbox(id)` addresses any of them, the dashboard's included.
|
|
289
|
+
|
|
290
|
+
## Sending paths
|
|
291
|
+
|
|
292
|
+
The app under test reaches the inbox one of three ways, each with the same
|
|
293
|
+
inbox credential, as the credential reveal shows it:
|
|
294
|
+
|
|
295
|
+
| Path | Where | Credential |
|
|
296
|
+
|---|---|---|
|
|
297
|
+
| SMTP | `smtp.mailstest.com`, port 465 with implicit TLS, or 2525 in plaintext | `SMTP_USER` and `SMTP_PASS` |
|
|
298
|
+
| Resend SDK | base URL `RESEND_BASE_URL=https://capture.mailstest.com/`, the trailing slash included | `RESEND_API_KEY=<username>.<password>` |
|
|
299
|
+
| SendGrid SDK | host `https://capture.mailstest.com`, set in code | `SENDGRID_API_KEY=SG.<username>.<password>` |
|
|
300
|
+
|
|
301
|
+
The Resend SDKs read the base URL from `RESEND_BASE_URL`, and the Python one
|
|
302
|
+
from `RESEND_API_URL`. No SendGrid SDK reads its host from the environment. In
|
|
303
|
+
Node, call `sgMail.client.setDefaultRequest('baseUrl', 'https://capture.mailstest.com')`
|
|
304
|
+
after `setApiKey`, which resets it. In TypeScript, whose types for
|
|
305
|
+
`@sendgrid/mail` have no `client`, set the host on `@sendgrid/client` and
|
|
306
|
+
hand it over:
|
|
307
|
+
|
|
308
|
+
```ts
|
|
309
|
+
import client from '@sendgrid/client';
|
|
310
|
+
import sgMail from '@sendgrid/mail';
|
|
311
|
+
|
|
312
|
+
client.setApiKey(process.env.SENDGRID_API_KEY!);
|
|
313
|
+
client.setDefaultRequest('baseUrl', 'https://capture.mailstest.com');
|
|
314
|
+
sgMail.setClient(client);
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
The recipient address routes nothing, so any address works, `@example.com`
|
|
318
|
+
included. A refusal is an SMTP reply code or an HTTP status, never a bounce.
|
|
319
|
+
|
|
320
|
+
## Limits
|
|
321
|
+
|
|
322
|
+
| | Free | Paid plans |
|
|
323
|
+
|---|---|---|
|
|
324
|
+
| Inboxes per workspace | 1 | more |
|
|
325
|
+
| Mail kept per inbox | the latest 100 | more |
|
|
326
|
+
| Each message kept for | 7 days | longer |
|
|
327
|
+
| Largest message | 5 MiB | 10 MiB |
|
|
328
|
+
|
|
329
|
+
- **A message's retention is fixed when it lands.**
|
|
330
|
+
- **A full inbox evicts its oldest mail.** Each new message evicts the oldest
|
|
331
|
+
unpinned one, so a test whose mail is evicted before it reads it times out.
|
|
332
|
+
- **The wait's 55-second limit per request** is handled by the SDK.
|
|
333
|
+
|
|
334
|
+
## Errors and secrets
|
|
335
|
+
|
|
336
|
+
- **`MailstestApiError`** carries `status`, `body` and `url`. A `status` of 0
|
|
337
|
+
means no usable answer came: a reset or refused connection, a DNS failure,
|
|
338
|
+
the SDK's own transport deadline, or an answer whose body could not be read
|
|
339
|
+
or parsed, such as an HTML page a wrong `baseUrl` answers with 200.
|
|
340
|
+
- **`MailstestScopeError`:** a read on the fixture's inbox without `to`, or a
|
|
341
|
+
scoped read answered with mail not delivered to its address.
|
|
342
|
+
- **`MailstestTeardownError`:** a fixture teardown that failed. `failures`
|
|
343
|
+
lists each act with its error.
|
|
344
|
+
- **`MailstestConfigError`:** the fixture's options lack a field.
|
|
345
|
+
- **Secrets.** No error, rejection, matcher failure or output of the SDK
|
|
346
|
+
carries the API key. A client also scrubs every secret it hands out, a
|
|
347
|
+
created inbox's password and a minted key, from the moment it parses it.
|
|
348
|
+
`client.protectSecret(secret)` adds one it never issued.
|
|
349
|
+
- **Headers.** Every request carries the key as `Authorization: Bearer`, and
|
|
350
|
+
names the SDK as `User-Agent: mailstest-playwright/<version> node/<major>`,
|
|
351
|
+
which carries no secret.
|
|
352
|
+
|
|
353
|
+
## Entries
|
|
354
|
+
|
|
355
|
+
| Import | What | Needs |
|
|
356
|
+
|---|---|---|
|
|
357
|
+
| `@mailstest/playwright` | the client, the extract functions and `expect` with `toReceiveEmail` | `@playwright/test` |
|
|
358
|
+
| `@mailstest/playwright/client` | the client alone | `zod` only |
|
|
359
|
+
| `@mailstest/playwright/fixtures` | `mailstestFixtures` and its types | `@playwright/test` |
|
|
360
|
+
|
|
361
|
+
## License and source
|
|
362
|
+
|
|
363
|
+
MIT. [github.com/mailstest/playwright](https://github.com/mailstest/playwright)
|
|
364
|
+
is a one-way mirror of the SDK's source, and each version is published from it
|
|
365
|
+
with npm provenance. Issues are welcome there, and pull requests are not
|
|
366
|
+
merged. Versions follow 0.x semver: a breaking change bumps the minor version.
|