@basaltkit/testing 1.0.1 → 1.1.0

package/dist/app.d.ts

@@ -16,12 +16,58 @@ export interface TestRequestOptions {
         [key: string]: unknown;
     };
 }
-export declare class TestApp {
+/** Which HTTP adapter drives the test requests. Default: 'fastify'. */
+export type TestAdapterName = 'fastify' | 'express' | 'hono';
+/**
+ * Adapter-neutral response every driver returns. Fastify's inject response
+ * satisfies it structurally (statusCode/headers/body/json()), so suites written
+ * against the default adapter read responses exactly as before; the Express and
+ * Hono drivers build the same shape from a real fetch Response.
+ */
+export interface TestResponse {
+    statusCode: number;
+    headers: Record<string, string | number | string[] | undefined>;
+    body: string;
+    json<T = any>(): T;
+}
+export interface CreateTestAppOptions extends CreateAppOptions {
+    /**
+     * HTTP adapter to drive requests through. Pass the matching adapter plugin
+     * (`fastifyPlugin`/`expressPlugin`/`honoPlugin`) in `plugins` yourself — the
+     * harness only decides how requests are dispatched:
+     *
+     * - 'fastify' (default): in-process via `inject()` — no socket.
+     * - 'express': real `listen(0)` on 127.0.0.1 + fetch (Express has no inject);
+     *   the socket is closed on `shutdown()`.
+     * - 'hono': in-process via `hono.fetch(new Request(…))` — no socket.
+     *
+     * 'express' and 'hono' need `@basaltkit/express` / `@basaltkit/hono`
+     * installed (optional peers of this package); the default needs nothing new.
+     */
+    adapter?: TestAdapterName;
+}
+interface DispatchRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    payload?: unknown;
+}
+/** What a connected adapter driver provides: dispatch + optional teardown. */
+interface ConnectedDriver {
+    dispatch(request: DispatchRequest): Promise<TestResponse>;
+    close?(): Promise<void>;
+}
+export declare class TestApp<Res extends TestResponse = LightMyRequestResponse> {
     readonly app: BasaltApp;
     private defaultUser;
     private defaultTenant;
-    constructor(app: BasaltApp);
+    private driver;
+    constructor(app: BasaltApp, driver?: ConnectedDriver);
     get container(): Container;
+    /**
+     * The raw Fastify instance — only meaningful on the default adapter; on
+     * Express/Hono resolve the `EXPRESS`/`HONO` token from `container` instead.
+     */
     get server(): FastifyInstance;
     /** Sets the default authenticated user for subsequent requests. */
     actingAs(user: TestActor): this;
@@ -29,13 +75,24 @@ export declare class TestApp {
     asTenant(tenant: string | {
         id: string;
     }): this;
-    request(method: NonNullable<InjectOptions['method']>, url: string, options?: TestRequestOptions): Promise<LightMyRequestResponse>;
-    get(url: string, options?: TestRequestOptions): Promise<LightMyRequestResponse>;
-    post(url: string, payload?: unknown, options?: TestRequestOptions): Promise<LightMyRequestResponse>;
-    put(url: string, payload?: unknown, options?: TestRequestOptions): Promise<LightMyRequestResponse>;
-    patch(url: string, payload?: unknown, options?: TestRequestOptions): Promise<LightMyRequestResponse>;
-    delete(url: string, options?: TestRequestOptions): Promise<LightMyRequestResponse>;
+    request(method: NonNullable<InjectOptions['method']>, url: string, options?: TestRequestOptions): Promise<Res>;
+    get(url: string, options?: TestRequestOptions): Promise<Res>;
+    post(url: string, payload?: unknown, options?: TestRequestOptions): Promise<Res>;
+    put(url: string, payload?: unknown, options?: TestRequestOptions): Promise<Res>;
+    patch(url: string, payload?: unknown, options?: TestRequestOptions): Promise<Res>;
+    delete(url: string, options?: TestRequestOptions): Promise<Res>;
     shutdown(): Promise<void>;
 }
-/** Boots an app with the impersonation enricher prepended. */
-export declare function createTestApp(options?: CreateAppOptions): Promise<TestApp>;
+/**
+ * Boots an app with the impersonation enricher prepended.
+ *
+ * Pass `adapter` to drive requests through Express or Hono instead of the
+ * default Fastify inject — the same suite then runs unchanged on any adapter
+ * (the neutral 'http:enrichers'/'http:guards' buckets make impersonation and
+ * guards behave identically).
+ */
+export declare function createTestApp(options?: CreateAppOptions & {
+    adapter?: 'fastify';
+}): Promise<TestApp>;
+export declare function createTestApp(options: CreateTestAppOptions): Promise<TestApp<TestResponse>>;
+export {};

package/dist/app.js

@@ -2,8 +2,9 @@ import { createApp, definePlugin, ensureMetadata, BasaltApp, } from '@basaltkit/
 import { FASTIFY } from '@basaltkit/fastify';
 /**
  * Test-only impersonation: createTestApp prepends an enricher that reads
- * the x-test-user / x-test-tenant headers set by the request helpers.
- * Never register this plugin in a real app.
+ * the x-test-user / x-test-tenant headers set by the request helpers. The
+ * 'http:enrichers' bucket is framework-neutral, so impersonation works
+ * identically on every adapter. Never register this plugin in a real app.
  */
 const impersonationPlugin = definePlugin({
     name: 'basalt:testing:impersonation',
@@ -19,16 +20,115 @@ const impersonationPlugin = definePlugin({
         ensureMetadata(container).add('http:enrichers', enricher);
     },
 });
+// ---- drivers -------------------------------------------------------------
+/** Fastify: light-my-request inject — in-process, no socket, sync-json reply. */
+function connectFastify(container) {
+    const server = container.get(FASTIFY);
+    return {
+        dispatch: ({ method, url, headers, payload }) => server.inject({
+            method: method,
+            url,
+            headers,
+            ...(payload !== undefined ? { payload: payload } : {}),
+        }),
+    };
+}
+/** Serialize a payload the way fastify's inject does: objects become JSON. */
+function bodyInit(method, headers, payload) {
+    if (payload === undefined || method === 'GET' || method === 'HEAD')
+        return { headers };
+    if (typeof payload === 'string')
+        return { headers, body: payload };
+    return { headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(payload) };
+}
+/** Build the neutral response from a fetch Response (Express/Hono drivers). */
+async function toTestResponse(response) {
+    const body = await response.text();
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    const cookies = response.headers.getSetCookie();
+    if (cookies.length > 0)
+        headers['set-cookie'] = cookies;
+    return {
+        statusCode: response.status,
+        headers,
+        body,
+        json: () => JSON.parse(body),
+    };
+}
+/**
+ * Express: unlike Fastify/Hono it has no in-process dispatch, so the driver
+ * listens on an ephemeral 127.0.0.1 port and fetches; `close()` (called by
+ * `TestApp.shutdown()`) tears the socket down.
+ */
+async function connectExpress(container) {
+    const { EXPRESS } = await loadAdapter('express');
+    const server = container.get(EXPRESS).listen(0, '127.0.0.1');
+    await new Promise((resolve, reject) => {
+        server.once('listening', resolve);
+        server.once('error', reject);
+    });
+    const { port } = server.address();
+    const base = `http://127.0.0.1:${port}`;
+    return {
+        dispatch: async ({ method, url, headers, payload }) => toTestResponse(await fetch(`${base}${url}`, { method, ...bodyInit(method, headers, payload) })),
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => (error ? reject(error) : resolve()));
+        }),
+    };
+}
+/** Hono: in-process `hono.fetch(new Request(…))` — no socket. */
+async function connectHono(container) {
+    const { HONO } = await loadAdapter('hono');
+    const hono = container.get(HONO);
+    return {
+        dispatch: async ({ method, url, headers, payload }) => toTestResponse(await hono.fetch(new Request(`http://basalt.test${url}`, { method, ...bodyInit(method, headers, payload) }))),
+    };
+}
+async function loadAdapter(name) {
+    try {
+        return name === 'express' ? await import('@basaltkit/express') : await import('@basaltkit/hono');
+    }
+    catch (error) {
+        throw new Error(`createTestApp({ adapter: '${name}' }) requires @basaltkit/${name} (an optional peer of ` +
+            `@basaltkit/testing) and the ${name} framework itself. Install them as devDependencies.`, { cause: error });
+    }
+}
+/**
+ * Only the non-default adapters connect eagerly (Express must `listen`).
+ * The fastify driver stays lazy — resolved on the first request — so apps
+ * booted without any HTTP plugin (mailer/queue-only tests) keep working
+ * exactly as before.
+ */
+function connect(adapter, container) {
+    switch (adapter) {
+        case 'fastify':
+            return undefined;
+        case 'express':
+            return connectExpress(container);
+        case 'hono':
+            return connectHono(container);
+    }
+}
+// ---- harness -------------------------------------------------------------
 export class TestApp {
     app;
     defaultUser;
     defaultTenant;
-    constructor(app) {
+    driver;
+    constructor(app, driver) {
         this.app = app;
+        this.driver = driver;
     }
     get container() {
         return this.app.container;
     }
+    /**
+     * The raw Fastify instance — only meaningful on the default adapter; on
+     * Express/Hono resolve the `EXPRESS`/`HONO` token from `container` instead.
+     */
     get server() {
         return this.container.get(FASTIFY);
     }
@@ -51,8 +151,11 @@ export class TestApp {
         if (tenant) {
             headers['x-test-tenant'] = JSON.stringify(typeof tenant === 'string' ? { id: tenant } : tenant);
         }
-        return this.server.inject({
-            method,
+        // Instantiating TestApp directly (without createTestApp) keeps the old
+        // fastify-inject behavior — connect lazily on first use.
+        this.driver ??= connectFastify(this.container);
+        return this.driver.dispatch({
+            method: String(method),
             url,
             headers,
             ...(options.payload !== undefined ? { payload: options.payload } : {}),
@@ -73,16 +176,19 @@ export class TestApp {
     delete(url, options) {
         return this.request('DELETE', url, options);
     }
-    shutdown() {
+    async shutdown() {
+        await this.driver?.close?.();
         return this.app.shutdown();
     }
 }
-/** Boots an app with the impersonation enricher prepended. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function createTestApp(options = {}) {
+    const { adapter = 'fastify', ...appOptions } = options;
     const app = createApp({
-        ...options,
-        plugins: [impersonationPlugin, ...(options.plugins ?? [])],
+        ...appOptions,
+        plugins: [impersonationPlugin, ...(appOptions.plugins ?? [])],
     });
     await app.boot();
-    return new TestApp(app);
+    const driver = connect(adapter, app.container);
+    return new TestApp(app, driver ? await driver : undefined);
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createTestApp, TestApp, type TestActor, type TestRequestOptions } from './app.js';
+export { createTestApp, TestApp, type TestActor, type TestRequestOptions, type TestAdapterName, type TestResponse, type CreateTestAppOptions, } from './app.js';
 export { fakeMailer, MailAssertionError, type FakeMailer } from './mailer.js';
 export { fakeQueue, QueueAssertionError, type FakeQueue, type CapturedJob } from './queue.js';
 export { time } from './time.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export { createTestApp, TestApp } from './app.js';
+export { createTestApp, TestApp, } from './app.js';
 export { fakeMailer, MailAssertionError } from './mailer.js';
 export { fakeQueue, QueueAssertionError } from './queue.js';
 export { time } from './time.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/testing",
-  "version": "1.0.1",
+  "version": "1.1.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",
@@ -15,16 +15,21 @@
   ],
   "dependencies": {
     "fastify": "^5.12.1",
-    "@basaltkit/fastify": "^1.6.1",
-    "@basaltkit/queue": "^1.2.1",
     "@basaltkit/core": "^1.1.2",
-    "@basaltkit/mailer": "^1.2.2"
+    "@basaltkit/fastify": "^1.6.1",
+    "@basaltkit/mailer": "^1.2.2",
+    "@basaltkit/queue": "^1.2.1"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",
+    "express": "^5.0.0",
+    "hono": "^4.13.4",
     "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/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -42,6 +47,18 @@
     "typescript",
     "testing"
   ],
+  "peerDependencies": {
+    "@basaltkit/express": "^1.2.1",
+    "@basaltkit/hono": "^1.2.1"
+  },
+  "peerDependenciesMeta": {
+    "@basaltkit/express": {
+      "optional": true
+    },
+    "@basaltkit/hono": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",