@basaltkit/testing 1.1.0 → 1.1.1

package/README.md

@@ -12,7 +12,7 @@ Testing kit for Basalt applications: boots the application in memory with `creat
 
 Testing a "real" web application is a lot of work: you'd have to start the server on a port, authenticate a real user, wait for real emails, and wait days to see a subscription expire. None of this is practical in an automated test, which should run in milliseconds and always produce the same result.
 
-This package solves the problem with four tools. `createTestApp` boots your application and injects HTTP requests directly into the Fastify server, without the network — and lets you "pretend" the request comes from a specific user or tenant (`actingAs` / `asTenant`), without going through login. A mail **fake** (a fake object that replaces a real service during tests), `fakeMailer`, records emails instead of sending them; a queue fake, `fakeQueue`, captures jobs instead of running them — both with Laravel-style assertions (`assertSent`, `assertDispatched`). Finally, `time` shifts the clock (`time.travel('15d')`) so you can test expirations and deadlines without waiting.
+This package solves the problem with four tools. `createTestApp` boots your application and dispatches HTTP requests straight into it — by default in-process through Fastify's `inject()`, with no network at all — and lets you "pretend" the request comes from a specific user or tenant (`actingAs` / `asTenant`), without going through login. Pass `adapter: 'express'` or `adapter: 'hono'` and the *same* suite runs against those adapters instead. A mail **fake** (a fake object that replaces a real service during tests), `fakeMailer`, records emails instead of sending them; a queue fake, `fakeQueue`, captures jobs instead of running them — both with Laravel-style assertions (`assertSent`, `assertDispatched`). Finally, `time` shifts the clock (`time.travel('15d')`) so you can test expirations and deadlines without waiting.
 
 Everything works with any test runner (Vitest, Jest, node:test…), because nothing here depends on the runner.
 
@@ -22,7 +22,7 @@ Everything works with any test runner (Vitest, Jest, node:test…), because noth
 pnpm add -D @basaltkit/testing
 ```
 
-> Note: it depends on `@basaltkit/core`, `@basaltkit/fastify`, `@basaltkit/mailer`, `@basaltkit/queue`, and `fastify`. Projects created with `create-basalt` already include `@basaltkit/testing` in `devDependencies`.
+> Note: it depends on `@basaltkit/core`, `@basaltkit/fastify`, `@basaltkit/mailer`, `@basaltkit/queue`, and `fastify`. `@basaltkit/express` and `@basaltkit/hono` are **optional peers** — you only need them if you pass `adapter: 'express'` / `adapter: 'hono'`. Projects created with `create-basalt` already include `@basaltkit/testing` in `devDependencies`.
 
 ## Get started in 5 minutes
 
@@ -79,11 +79,67 @@ await app.patch(`/projects/${id}`, { name: 'Renamed' })
 await app.delete(`/projects/${id}`)
 ```
 
-The response is a Fastify `LightMyRequestResponse`: use `.statusCode`, `.json()`, `.body`, `.headers`.
+On the default adapter the response is a Fastify `LightMyRequestResponse`; on Express and
+Hono it is a `TestResponse` built from a real `fetch` Response. Both expose the same
+surface — `.statusCode`, `.headers`, `.body`, `.json()` — so assertions are portable.
+(`json()` is synchronous on both: the body is already read.) Multiple `Set-Cookie` headers
+arrive as a `string[]` under `headers['set-cookie']`.
+
+### Running the same suite on every adapter — `adapter`
+
+`createTestApp` doesn't choose your HTTP adapter; **you** still pass the adapter plugin in
+`plugins`. The `adapter` option only tells the harness *how to dispatch* a request:
+
+| `adapter` | How requests are dispatched | Socket? | Extra install |
+|---|---|---|---|
+| `'fastify'` (default) | Fastify's `inject()` — in-process | no | nothing |
+| `'express'` | `listen(0)` on `127.0.0.1` + `fetch` (Express has no in-process inject); the socket is closed by `shutdown()` | yes, ephemeral | `@basaltkit/express` + `express` |
+| `'hono'` | `hono.fetch(new Request(…))` — in-process | no | `@basaltkit/hono` + `hono` |
+
+```ts
+import { expressPlugin } from '@basaltkit/express'
+import { createTestApp } from '@basaltkit/testing'
+
+const app = await createTestApp({
+  adapter: 'express',
+  plugins: [expressPlugin({ routes: [health] })],
+})
+const res = await app.get('/health')   // identical assertions to the Fastify run
+await app.shutdown()                   // also closes the listening socket
+```
+
+The whole point is that the assertions don't change. Impersonation, guards and enrichers
+all go through the framework-neutral `'http:enrichers'` / `'http:guards'` buckets, so they
+behave identically on all three — which makes a parameterized suite the cheapest possible
+proof that your app really is adapter-agnostic:
+
+```ts
+describe.each(['fastify', 'express', 'hono'] as const)('on %s', (adapter) => {
+  it('serves /health', async () => {
+    const app = await createTestApp({ adapter, plugins: [pluginFor(adapter)] })
+    expect((await app.get('/health')).statusCode).toBe(200)
+    await app.shutdown()
+  })
+})
+```
+
+Two details worth knowing. The Fastify driver connects **lazily**, on the first request, so
+an app booted with no HTTP plugin at all (a mailer- or queue-only test) still works. And
+`TestApp.server` returns the raw `FastifyInstance` — meaningful only on the default
+adapter; on Express/Hono resolve `EXPRESS` / `HONO` from `app.container` instead.
+
+If you ask for an adapter whose package isn't installed, you get an actionable error
+naming the two packages to add, not a bare `ERR_MODULE_NOT_FOUND`.
 
 ### Faking users and tenants (impersonation)
 
-`createTestApp` automatically adds a test plugin that reads the special `x-test-user` / `x-test-tenant` headers and populates `ctx().user` / `ctx().tenant` — the same context your application uses in production. **Never register this mechanism in a real application.**
+`createTestApp` **prepends** a test plugin that reads the special `x-test-user` /
+`x-test-tenant` headers and populates `ctx().user` / `ctx().tenant` — the same context your
+application uses in production. It is registered as a `RequestEnricher` in the neutral
+`'http:enrichers'` bucket, which is why it works the same on all three adapters. The
+headers are parsed with **no validation whatsoever**: anyone who can set a header becomes
+anyone. **Never register this mechanism in a real application** — it only exists inside
+`createTestApp`.
 
 ```typescript
 import { ctx } from '@basaltkit/core'
@@ -205,11 +261,17 @@ Exported from `@basaltkit/testing`:
 
 ### `createTestApp(options?): Promise<TestApp>`
 
-Creates the application with `createApp` (the same `CreateAppOptions` as `@basaltkit/core`), prepends the impersonation plugin, calls `boot()`, and returns a `TestApp`.
+Creates the application with `createApp` (the same `CreateAppOptions` as `@basaltkit/core`), prepends the impersonation plugin, calls `boot()`, connects the dispatch driver, and returns a `TestApp`.
 
-| Parameter | Type | Required? | Default | Description |
-| --- | --- | --- | --- | --- |
-| `options` | `CreateAppOptions` | No | `{}` | Options for `createApp`; your `plugins` are added after the impersonation plugin |
+`CreateTestAppOptions extends CreateAppOptions`:
+
+| Option | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `plugins` | `BasaltPlugin[]` | `[]` | Your plugins — **including the HTTP adapter plugin**. They are registered *after* the impersonation plugin. |
+| `config` | `Record<string, unknown>` | `{}` | Raw per-plugin config, keyed by plugin name — same as `createApp`. |
+| `adapter` | `'fastify' \| 'express' \| 'hono'` | `'fastify'` | How requests are dispatched. `'fastify'` uses `inject()` (lazy, no socket); `'express'` listens on an ephemeral `127.0.0.1` port and fetches (closed on `shutdown()`); `'hono'` uses `hono.fetch` in-process. The non-default ones need `@basaltkit/express` / `@basaltkit/hono` installed. |
+
+The return type follows the adapter: `Promise<TestApp>` (Fastify responses) for the default, `Promise<TestApp<TestResponse>>` when you pass an `adapter`.
 
 ### `TestApp` class
 
@@ -217,7 +279,7 @@ Creates the application with `createApp` (the same `CreateAppOptions` as `@basal
 | --- | --- | --- |
 | `app` | `BasaltApp` | The underlying application |
 | `container` | `Container` (getter) | Dependency container — `app.container.get(TOKEN)` |
-| `server` | `FastifyInstance` (getter) | The Fastify server (token `FASTIFY`) |
+| `server` | `FastifyInstance` (getter) | The Fastify server (token `FASTIFY`) — meaningful **only** on the default adapter; on Express/Hono resolve `EXPRESS`/`HONO` from `container` instead |
 | `actingAs(user)` | `(user: TestActor) => this` | Sets the default user for subsequent requests |
 | `asTenant(tenant)` | `(tenant: string \| { id: string }) => this` | Sets the default tenant for subsequent requests |
 | `request(method, url, options?)` | `Promise<LightMyRequestResponse>` | Generic request |
@@ -226,10 +288,12 @@ Creates the application with `createApp` (the same `CreateAppOptions` as `@basal
 | `put(url, payload?, options?)` | same | PUT with body |
 | `patch(url, payload?, options?)` | same | PATCH with body |
 | `delete(url, options?)` | same | DELETE |
-| `shutdown()` | `Promise<void>` | Shuts down the application (call at the end of every test) |
+| `shutdown()` | `Promise<void>` | Closes the driver (the Express socket, when there is one) and then shuts the application down. Call at the end of every test |
 
 `TestActor`: `{ id: string; email?: string; [key: string]: unknown }`.
 
+`TestResponse`: `{ statusCode: number; headers: Record<string, string | number | string[] | undefined>; body: string; json<T>(): T }` — the adapter-neutral response shape. Fastify's `LightMyRequestResponse` satisfies it structurally.
+
 `TestRequestOptions`:
 
 | Field | Type | Required? | Default | Description |
@@ -284,8 +348,14 @@ Creates the application with `createApp` (the same `CreateAppOptions` as `@basal
 
 ### Errors
 
-- `MailAssertionError` — code `TEST_MAIL_ASSERTION` (extends `BasaltError`).
-- `QueueAssertionError` — code `TEST_QUEUE_ASSERTION` (extends `BasaltError`).
+| Error | Code | HTTP | When |
+|---|---|---|---|
+| `MailAssertionError` | `TEST_MAIL_ASSERTION` | — | `assertSent` found no matching mail, or `assertNothingSent` found some. The message lists what *was* sent. |
+| `QueueAssertionError` | `TEST_QUEUE_ASSERTION` | — | `assertDispatched` found no matching job, or `assertNothingDispatched` found some. The message lists what *was* dispatched. |
+| `Error` (plain) | — | — | `createTestApp({ adapter: 'express' \| 'hono' })` when that adapter package isn't installed. The message names both packages to add; the original module error is the `cause`. |
+
+Both assertion errors extend `BasaltError`, so `error.code` is stable. These are test-time
+failures — they never travel over HTTP, so they have no status.
 
 ## Common errors and solutions (FAQ)
 
@@ -293,7 +363,16 @@ Creates the application with `createApp` (the same `CreateAppOptions` as `@basal
 You're missing `await app.shutdown()` at the end of the test. The application keeps resources open until it's shut down.
 
 **`ctx().user` always comes back `undefined` in handlers.**
-Make sure you created the app with `createTestApp` (it's the one that installs impersonation) and that you called `actingAs(...)` before the request — or passed `{ user: ... }` in that request's options. Impersonation works through `@basaltkit/fastify` request enrichers; it needs `fastifyPlugin` registered.
+Make sure you created the app with `createTestApp` (it's the one that installs impersonation) and that you called `actingAs(...)` before the request — or passed `{ user: ... }` in that request's options. Impersonation is a `RequestEnricher` in the neutral `'http:enrichers'` bucket, so it needs *an* adapter plugin registered (`fastifyPlugin`, `expressPlugin` or `honoPlugin`) — enrichers only run inside the route pipeline.
+
+**`createTestApp({ adapter: 'hono' }) requires @basaltkit/hono …`**
+The optional peer isn't installed. Add `@basaltkit/hono` and `hono` (or `@basaltkit/express` and `express`) as devDependencies.
+
+**`app.server` throws `DI_UNKNOWN_TOKEN` on Express or Hono.**
+`server` resolves the `FASTIFY` token. On another adapter, use `app.container.get(EXPRESS)` / `app.container.get(HONO)`.
+
+**The Express run leaves a port open after the suite.**
+`shutdown()` closes it — make sure every test that used `adapter: 'express'` awaits it, including on the failure path.
 
 **`Expected mail "welcome" to have been sent. Sent: (nothing)`**
 The code never actually sent the email, or the `Mailer` used isn't the fake one. Make sure `mail.plugin` is in `createTestApp`'s `plugins` list **before** you resolve `MAILER` from the container.
@@ -310,8 +389,12 @@ No. The impersonation plugin reads headers (`x-test-user`) without any validatio
 ## How it connects to other modules
 
 - **`@basaltkit/core`** — `createTestApp` wraps `createApp`; `time` uses `parseDuration`; the errors extend `BasaltError`.
-- **`@basaltkit/fastify`** — requests are injected into the `FastifyInstance` (token `FASTIFY`); impersonation is a `RequestEnricher` registered in the `http:enrichers` bucket.
+- **`@basaltkit/fastify`** — the default driver injects into the `FastifyInstance` (token `FASTIFY`).
+- **`@basaltkit/express` / `@basaltkit/hono`** — optional peers; `adapter: 'express' | 'hono'` resolves them lazily so the default path never loads them.
+- **`@basaltkit/http`** — impersonation is a `RequestEnricher` in the neutral `http:enrichers` bucket, which is what makes the harness adapter-agnostic.
 - **`@basaltkit/mailer`** — `fakeMailer` registers a real `Mailer` with `MemoryMailDriver`, under the same `MAILER` token the application uses.
 - **`@basaltkit/queue`** — `fakeQueue` uses the real `queuePlugin` with a driver that captures instead of running.
 - **`@basaltkit/generator`** — tests generated by `basalt make:resource` use `createTestApp` from this package.
 - **`create-basalt`** — new projects include `@basaltkit/testing` in `devDependencies` and a ready-to-run startup test.
+
+Guides: [Testing](/guide/testing) · [Adapters](/guide/adapters)

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@basaltkit/testing",
-  "version": "1.1.0",
+  "version": "1.1.1",
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "description": "Testing kit for Basalt apps: createTestApp with user/tenant impersonation, mail and queue fakes with assertions, and time travel.",
   "license": "MIT",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -15,10 +19,10 @@
   ],
   "dependencies": {
     "fastify": "^5.12.1",
-    "@basaltkit/core": "^1.1.2",
-    "@basaltkit/fastify": "^1.6.1",
-    "@basaltkit/mailer": "^1.2.2",
-    "@basaltkit/queue": "^1.2.1"
+    "@basaltkit/core": "^1.3.1",
+    "@basaltkit/fastify": "^1.8.1",
+    "@basaltkit/mailer": "^1.4.1",
+    "@basaltkit/queue": "^1.4.1"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",
@@ -27,9 +31,9 @@
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
     "zod": "^3.24.0 || ^4.0.0",
-    "@basaltkit/express": "^1.2.1",
-    "@basaltkit/hono": "^1.2.1",
-    "@basaltkit/http": "^1.9.1",
+    "@basaltkit/express": "^1.4.1",
+    "@basaltkit/hono": "^1.4.1",
+    "@basaltkit/http": "^1.14.0",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -48,8 +52,8 @@
     "testing"
   ],
   "peerDependencies": {
-    "@basaltkit/express": "^1.2.1",
-    "@basaltkit/hono": "^1.2.1"
+    "@basaltkit/express": "^1.4.1",
+    "@basaltkit/hono": "^1.4.1"
   },
   "peerDependenciesMeta": {
     "@basaltkit/express": {