@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 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
- # Temporary Holding Version
1
+ # @mailstest/playwright
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.