@basaltkit/testing 1.0.0 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Machize Contributors
+Copyright (c) 2026 Basalt Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @basaltkit/testing
 
 Testing kit for Basalt applications: boots the application in memory with `createTestApp`, makes HTTP requests impersonating users and tenants, replaces mail and queue with fake versions that support assertions, and travels through time. You need it whenever you want to write automated tests for your application without real servers, databases, or external services.

package/dist/app.d.ts

@@ -0,0 +1,98 @@
+import { BasaltApp, type Container, type CreateAppOptions } from '@basaltkit/core';
+import type { FastifyInstance, InjectOptions, LightMyRequestResponse } from 'fastify';
+export interface TestActor {
+    id: string;
+    email?: string;
+    [key: string]: unknown;
+}
+export interface TestRequestOptions {
+    payload?: unknown;
+    headers?: Record<string, string>;
+    /** Impersonate a user for this request (overrides actingAs). */
+    user?: TestActor;
+    /** Impersonate a tenant for this request (overrides asTenant). */
+    tenant?: string | {
+        id: string;
+        [key: string]: unknown;
+    };
+}
+/** 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;
+    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;
+    /** Sets the default tenant for subsequent requests. */
+    asTenant(tenant: string | {
+        id: string;
+    }): this;
+    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.
+ *
+ * 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

@@ -0,0 +1,194 @@
+import { createApp, definePlugin, ensureMetadata, BasaltApp, } from '@basaltkit/core';
+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. 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',
+    register({ container }) {
+        const enricher = ({ request, context }) => {
+            const rawUser = request.headers['x-test-user'];
+            if (typeof rawUser === 'string')
+                context.user = JSON.parse(rawUser);
+            const rawTenant = request.headers['x-test-tenant'];
+            if (typeof rawTenant === 'string')
+                context.tenant = JSON.parse(rawTenant);
+        };
+        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;
+    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);
+    }
+    /** Sets the default authenticated user for subsequent requests. */
+    actingAs(user) {
+        this.defaultUser = user;
+        return this;
+    }
+    /** Sets the default tenant for subsequent requests. */
+    asTenant(tenant) {
+        this.defaultTenant = tenant;
+        return this;
+    }
+    async request(method, url, options = {}) {
+        const user = options.user ?? this.defaultUser;
+        const tenant = options.tenant ?? this.defaultTenant;
+        const headers = { ...options.headers };
+        if (user)
+            headers['x-test-user'] = JSON.stringify(user);
+        if (tenant) {
+            headers['x-test-tenant'] = JSON.stringify(typeof tenant === 'string' ? { id: tenant } : tenant);
+        }
+        // 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 } : {}),
+        });
+    }
+    get(url, options) {
+        return this.request('GET', url, options);
+    }
+    post(url, payload, options) {
+        return this.request('POST', url, { ...options, payload });
+    }
+    put(url, payload, options) {
+        return this.request('PUT', url, { ...options, payload });
+    }
+    patch(url, payload, options) {
+        return this.request('PATCH', url, { ...options, payload });
+    }
+    delete(url, options) {
+        return this.request('DELETE', url, options);
+    }
+    async shutdown() {
+        await this.driver?.close?.();
+        return this.app.shutdown();
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function createTestApp(options = {}) {
+    const { adapter = 'fastify', ...appOptions } = options;
+    const app = createApp({
+        ...appOptions,
+        plugins: [impersonationPlugin, ...(appOptions.plugins ?? [])],
+    });
+    await app.boot();
+    const driver = connect(adapter, app.container);
+    return new TestApp(app, driver ? await driver : undefined);
+}

package/dist/index.d.ts

@@ -1,98 +1,4 @@
-import { BasaltApp, Container, CreateAppOptions, definePlugin, BasaltError, DurationInput } from '@basaltkit/core';
-import { FastifyInstance, InjectOptions, LightMyRequestResponse } from 'fastify';
-import { ResolvedMail, MailDefinition, MailerOptions } from '@basaltkit/mailer';
-import { AddJobOptions, queuePlugin, JobDefinition } from '@basaltkit/queue';
-
-interface TestActor {
-    id: string;
-    email?: string;
-    [key: string]: unknown;
-}
-interface TestRequestOptions {
-    payload?: unknown;
-    headers?: Record<string, string>;
-    /** Impersonate a user for this request (overrides actingAs). */
-    user?: TestActor;
-    /** Impersonate a tenant for this request (overrides asTenant). */
-    tenant?: string | {
-        id: string;
-        [key: string]: unknown;
-    };
-}
-declare class TestApp {
-    readonly app: BasaltApp;
-    private defaultUser;
-    private defaultTenant;
-    constructor(app: BasaltApp);
-    get container(): Container;
-    get server(): FastifyInstance;
-    /** Sets the default authenticated user for subsequent requests. */
-    actingAs(user: TestActor): this;
-    /** Sets the default tenant for subsequent requests. */
-    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>;
-    shutdown(): Promise<void>;
-}
-/** Boots an app with the impersonation enricher prepended. */
-declare function createTestApp(options?: CreateAppOptions): Promise<TestApp>;
-
-declare class MailAssertionError extends BasaltError {
-    constructor(message: string);
-}
-interface FakeMailer {
-    /** Register this in createTestApp({ plugins: [mail.plugin, ...] }). */
-    plugin: ReturnType<typeof definePlugin>;
-    /** Everything "sent", in order. */
-    sent: ResolvedMail[];
-    assertSent(mail: MailDefinition<any> | string, predicate?: (message: ResolvedMail) => boolean): ResolvedMail;
-    assertNothingSent(): void;
-}
-/** Mail fake: records instead of sending, with Laravel-style assertions. */
-declare function fakeMailer(options?: MailerOptions): FakeMailer;
-
-declare class QueueAssertionError extends BasaltError {
-    constructor(message: string);
-}
-interface CapturedJob {
-    queue: string;
-    job: string;
-    payload: unknown;
-    context: unknown;
-    options: AddJobOptions;
-}
-interface FakeQueue {
-    /** Register this in createTestApp({ plugins: [queue.plugin, ...] }). */
-    plugin: ReturnType<typeof queuePlugin>;
-    /** Every dispatch, in order — payload and context snapshot included. */
-    dispatched: CapturedJob[];
-    assertDispatched(job: JobDefinition<any> | string, predicate?: (captured: CapturedJob) => boolean): CapturedJob;
-    assertNothingDispatched(): void;
-    /** Executes the captured backlog through the real handlers. */
-    drain(): Promise<number>;
-}
-declare function fakeQueue(options?: {
-    jobs?: JobDefinition<any>[];
-}): FakeQueue;
-
-/**
- * Time travel without a test-runner dependency — works in any runner:
- *
- * time.travel('15d')       // trials expire, meters roll over
- * time.travelTo(new Date('2027-01-01'))
- * time.restore()           // always call in afterEach
- */
-declare const time: {
-    travel(duration: DurationInput): void;
-    travelTo(date: Date): void;
-    /** Undoes the patch and resets the offset. */
-    restore(): void;
-};
-
-export { type CapturedJob, type FakeMailer, type FakeQueue, MailAssertionError, QueueAssertionError, type TestActor, TestApp, type TestRequestOptions, createTestApp, fakeMailer, fakeQueue, time };
+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,253 +1,4 @@
-// src/app.ts
-import {
-  createApp,
-  definePlugin,
-  ensureMetadata
-} from "@basaltkit/core";
-import { FASTIFY } from "@basaltkit/fastify";
-var impersonationPlugin = definePlugin({
-  name: "basalt:testing:impersonation",
-  register({ container }) {
-    const enricher = ({ request, context }) => {
-      const rawUser = request.headers["x-test-user"];
-      if (typeof rawUser === "string") context.user = JSON.parse(rawUser);
-      const rawTenant = request.headers["x-test-tenant"];
-      if (typeof rawTenant === "string") context.tenant = JSON.parse(rawTenant);
-    };
-    ensureMetadata(container).add("http:enrichers", enricher);
-  }
-});
-var TestApp = class {
-  constructor(app) {
-    this.app = app;
-  }
-  app;
-  defaultUser;
-  defaultTenant;
-  get container() {
-    return this.app.container;
-  }
-  get server() {
-    return this.container.get(FASTIFY);
-  }
-  /** Sets the default authenticated user for subsequent requests. */
-  actingAs(user) {
-    this.defaultUser = user;
-    return this;
-  }
-  /** Sets the default tenant for subsequent requests. */
-  asTenant(tenant) {
-    this.defaultTenant = tenant;
-    return this;
-  }
-  async request(method, url, options = {}) {
-    const user = options.user ?? this.defaultUser;
-    const tenant = options.tenant ?? this.defaultTenant;
-    const headers = { ...options.headers };
-    if (user) headers["x-test-user"] = JSON.stringify(user);
-    if (tenant) {
-      headers["x-test-tenant"] = JSON.stringify(typeof tenant === "string" ? { id: tenant } : tenant);
-    }
-    return this.server.inject({
-      method,
-      url,
-      headers,
-      ...options.payload !== void 0 ? { payload: options.payload } : {}
-    });
-  }
-  get(url, options) {
-    return this.request("GET", url, options);
-  }
-  post(url, payload, options) {
-    return this.request("POST", url, { ...options, payload });
-  }
-  put(url, payload, options) {
-    return this.request("PUT", url, { ...options, payload });
-  }
-  patch(url, payload, options) {
-    return this.request("PATCH", url, { ...options, payload });
-  }
-  delete(url, options) {
-    return this.request("DELETE", url, options);
-  }
-  shutdown() {
-    return this.app.shutdown();
-  }
-};
-async function createTestApp(options = {}) {
-  const app = createApp({
-    ...options,
-    plugins: [impersonationPlugin, ...options.plugins ?? []]
-  });
-  await app.boot();
-  return new TestApp(app);
-}
-
-// src/mailer.ts
-import { createToken, definePlugin as definePlugin2, BasaltError } from "@basaltkit/core";
-import {
-  MAILER,
-  Mailer,
-  MemoryMailDriver
-} from "@basaltkit/mailer";
-var MailAssertionError = class extends BasaltError {
-  constructor(message) {
-    super("TEST_MAIL_ASSERTION", message);
-  }
-};
-function fakeMailer(options = { from: "test@basalt.dev" }) {
-  const driver = new MemoryMailDriver();
-  const plugin = definePlugin2({
-    name: "basalt:mailer",
-    register({ container }) {
-      container.singleton(MAILER, () => new Mailer(driver, options));
-    }
-  });
-  return {
-    plugin,
-    sent: driver.sent,
-    assertSent(mail, predicate) {
-      const name = typeof mail === "string" ? mail : mail.name;
-      const matches = driver.sent.filter(
-        (message) => message.mail === name && (predicate ? predicate(message) : true)
-      );
-      if (matches.length === 0) {
-        const seen = driver.sent.map((message) => message.mail).join(", ") || "(nothing)";
-        throw new MailAssertionError(
-          `Expected mail "${name}" to have been sent${predicate ? " matching the predicate" : ""}. Sent: ${seen}`
-        );
-      }
-      return matches[0];
-    },
-    assertNothingSent() {
-      if (driver.sent.length > 0) {
-        throw new MailAssertionError(
-          `Expected no mail, but ${driver.sent.length} message(s) were sent: ${driver.sent.map((message) => message.mail).join(", ")}`
-        );
-      }
-    }
-  };
-}
-var FAKE_MAILER = createToken("testing:mailer");
-
-// src/queue.ts
-import { BasaltError as BasaltError2 } from "@basaltkit/core";
-import {
-  queuePlugin
-} from "@basaltkit/queue";
-var QueueAssertionError = class extends BasaltError2 {
-  constructor(message) {
-    super("TEST_QUEUE_ASSERTION", message);
-  }
-};
-var CapturingQueueDriver = class {
-  captured = [];
-  pending = [];
-  executor;
-  setExecutor(executor) {
-    this.executor = executor;
-  }
-  async add(queue, jobName, data, options) {
-    const envelope = data;
-    this.captured.push({
-      queue,
-      job: jobName,
-      payload: envelope.payload,
-      context: envelope.context,
-      options
-    });
-    this.pending.push({ jobName, data });
-  }
-  async drain() {
-    let ran = 0;
-    while (this.pending.length > 0) {
-      const next = this.pending.shift();
-      await this.executor?.(next.jobName, next.data);
-      ran++;
-    }
-    return ran;
-  }
-  startWorker() {
-  }
-  async close() {
-  }
-};
-function fakeQueue(options = {}) {
-  const driver = new CapturingQueueDriver();
-  const plugin = queuePlugin({
-    driver,
-    ...options.jobs ? { jobs: options.jobs } : {}
-  });
-  return {
-    plugin,
-    dispatched: driver.captured,
-    assertDispatched(job, predicate) {
-      const name = typeof job === "string" ? job : job.name;
-      const matches = driver.captured.filter(
-        (captured) => captured.job === name && (predicate ? predicate(captured) : true)
-      );
-      if (matches.length === 0) {
-        const seen = driver.captured.map((captured) => captured.job).join(", ") || "(nothing)";
-        throw new QueueAssertionError(
-          `Expected job "${name}" to have been dispatched${predicate ? " matching the predicate" : ""}. Dispatched: ${seen}`
-        );
-      }
-      return matches[0];
-    },
-    assertNothingDispatched() {
-      if (driver.captured.length > 0) {
-        throw new QueueAssertionError(
-          `Expected no jobs, but ${driver.captured.length} were dispatched: ${driver.captured.map((captured) => captured.job).join(", ")}`
-        );
-      }
-    },
-    drain: () => driver.drain()
-  };
-}
-
-// src/time.ts
-import { parseDuration } from "@basaltkit/core";
-var RealDate = globalThis.Date;
-var offset = 0;
-var installed = false;
-var ShiftedDate = class extends RealDate {
-  constructor(...args) {
-    if (args.length === 0) super(RealDate.now() + offset);
-    else super(...args);
-  }
-  static now() {
-    return RealDate.now() + offset;
-  }
-};
-function install() {
-  if (installed) return;
-  globalThis.Date = ShiftedDate;
-  installed = true;
-}
-var time = {
-  travel(duration) {
-    install();
-    offset += parseDuration(duration);
-  },
-  travelTo(date) {
-    install();
-    offset = date.getTime() - RealDate.now();
-  },
-  /** Undoes the patch and resets the offset. */
-  restore() {
-    offset = 0;
-    if (installed) {
-      globalThis.Date = RealDate;
-      installed = false;
-    }
-  }
-};
-export {
-  MailAssertionError,
-  QueueAssertionError,
-  TestApp,
-  createTestApp,
-  fakeMailer,
-  fakeQueue,
-  time
-};
+export { createTestApp, TestApp, } from './app.js';
+export { fakeMailer, MailAssertionError } from './mailer.js';
+export { fakeQueue, QueueAssertionError } from './queue.js';
+export { time } from './time.js';

package/dist/mailer.d.ts

@@ -0,0 +1,16 @@
+import { definePlugin, BasaltError } from '@basaltkit/core';
+import { type MailDefinition, type MailerOptions, type ResolvedMail } from '@basaltkit/mailer';
+export declare class MailAssertionError extends BasaltError {
+    constructor(message: string);
+}
+export interface FakeMailer {
+    /** Register this in createTestApp({ plugins: [mail.plugin, ...] }). */
+    plugin: ReturnType<typeof definePlugin>;
+    /** Everything "sent", in order. */
+    sent: ResolvedMail[];
+    assertSent(mail: MailDefinition<any> | string, predicate?: (message: ResolvedMail) => boolean): ResolvedMail;
+    assertNothingSent(): void;
+}
+/** Mail fake: records instead of sending, with Laravel-style assertions. */
+export declare function fakeMailer(options?: MailerOptions): FakeMailer;
+export declare const FAKE_MAILER: import("@basaltkit/core").Token<FakeMailer>;

package/dist/mailer.js

@@ -0,0 +1,38 @@
+import { createToken, definePlugin, BasaltError } from '@basaltkit/core';
+import { MAILER, Mailer, MemoryMailDriver, } from '@basaltkit/mailer';
+export class MailAssertionError extends BasaltError {
+    constructor(message) {
+        super('TEST_MAIL_ASSERTION', message);
+    }
+}
+/** Mail fake: records instead of sending, with Laravel-style assertions. */
+export function fakeMailer(options = { from: 'test@basalt.dev' }) {
+    const driver = new MemoryMailDriver();
+    const plugin = definePlugin({
+        name: 'basalt:mailer',
+        register({ container }) {
+            container.singleton(MAILER, () => new Mailer(driver, options));
+        },
+    });
+    return {
+        plugin,
+        sent: driver.sent,
+        assertSent(mail, predicate) {
+            const name = typeof mail === 'string' ? mail : mail.name;
+            const matches = driver.sent.filter((message) => message.mail === name && (predicate ? predicate(message) : true));
+            if (matches.length === 0) {
+                const seen = driver.sent.map((message) => message.mail).join(', ') || '(nothing)';
+                throw new MailAssertionError(`Expected mail "${name}" to have been sent${predicate ? ' matching the predicate' : ''}. Sent: ${seen}`);
+            }
+            return matches[0];
+        },
+        assertNothingSent() {
+            if (driver.sent.length > 0) {
+                throw new MailAssertionError(`Expected no mail, but ${driver.sent.length} message(s) were sent: ${driver.sent
+                    .map((message) => message.mail)
+                    .join(', ')}`);
+            }
+        },
+    };
+}
+export const FAKE_MAILER = createToken('testing:mailer');

package/dist/queue.d.ts

@@ -0,0 +1,25 @@
+import { BasaltError } from '@basaltkit/core';
+import { queuePlugin, type AddJobOptions, type JobDefinition } from '@basaltkit/queue';
+export declare class QueueAssertionError extends BasaltError {
+    constructor(message: string);
+}
+export interface CapturedJob {
+    queue: string;
+    job: string;
+    payload: unknown;
+    context: unknown;
+    options: AddJobOptions;
+}
+export interface FakeQueue {
+    /** Register this in createTestApp({ plugins: [queue.plugin, ...] }). */
+    plugin: ReturnType<typeof queuePlugin>;
+    /** Every dispatch, in order — payload and context snapshot included. */
+    dispatched: CapturedJob[];
+    assertDispatched(job: JobDefinition<any> | string, predicate?: (captured: CapturedJob) => boolean): CapturedJob;
+    assertNothingDispatched(): void;
+    /** Executes the captured backlog through the real handlers. */
+    drain(): Promise<number>;
+}
+export declare function fakeQueue(options?: {
+    jobs?: JobDefinition<any>[];
+}): FakeQueue;

package/dist/queue.js

@@ -0,0 +1,66 @@
+import { BasaltError } from '@basaltkit/core';
+import { queuePlugin, } from '@basaltkit/queue';
+export class QueueAssertionError extends BasaltError {
+    constructor(message) {
+        super('TEST_QUEUE_ASSERTION', message);
+    }
+}
+/** Captures dispatches without executing them; drain() runs the backlog. */
+class CapturingQueueDriver {
+    captured = [];
+    pending = [];
+    executor;
+    setExecutor(executor) {
+        this.executor = executor;
+    }
+    async add(queue, jobName, data, options) {
+        const envelope = data;
+        this.captured.push({
+            queue,
+            job: jobName,
+            payload: envelope.payload,
+            context: envelope.context,
+            options,
+        });
+        this.pending.push({ jobName, data });
+    }
+    async drain() {
+        let ran = 0;
+        while (this.pending.length > 0) {
+            const next = this.pending.shift();
+            await this.executor?.(next.jobName, next.data);
+            ran++;
+        }
+        return ran;
+    }
+    startWorker() { }
+    async close() { }
+}
+export function fakeQueue(options = {}) {
+    const driver = new CapturingQueueDriver();
+    const plugin = queuePlugin({
+        driver,
+        ...(options.jobs ? { jobs: options.jobs } : {}),
+    });
+    return {
+        plugin,
+        dispatched: driver.captured,
+        assertDispatched(job, predicate) {
+            const name = typeof job === 'string' ? job : job.name;
+            const matches = driver.captured.filter((captured) => captured.job === name && (predicate ? predicate(captured) : true));
+            if (matches.length === 0) {
+                const seen = driver.captured.map((captured) => captured.job).join(', ') || '(nothing)';
+                throw new QueueAssertionError(`Expected job "${name}" to have been dispatched${predicate ? ' matching the predicate' : ''}. Dispatched: ${seen}`);
+            }
+            return matches[0];
+        },
+        assertNothingDispatched() {
+            if (driver.captured.length > 0) {
+                throw new QueueAssertionError(`Expected no jobs, but ${driver.captured.length} were dispatched: ${driver.captured
+                    .map((captured) => captured.job)
+                    .join(', ')}`);
+            }
+        },
+        drain: () => driver.drain(),
+    };
+}

package/dist/time.d.ts

@@ -0,0 +1,14 @@
+import { type DurationInput } from '@basaltkit/core';
+/**
+ * Time travel without a test-runner dependency — works in any runner:
+ *
+ * time.travel('15d')       // trials expire, meters roll over
+ * time.travelTo(new Date('2027-01-01'))
+ * time.restore()           // always call in afterEach
+ */
+export declare const time: {
+    travel(duration: DurationInput): void;
+    travelTo(date: Date): void;
+    /** Undoes the patch and resets the offset. */
+    restore(): void;
+};

package/dist/time.js

@@ -0,0 +1,50 @@
+import { parseDuration } from '@basaltkit/core';
+const RealDate = globalThis.Date;
+let offset = 0;
+let installed = false;
+/**
+ * Patched Date: shifts `now` by the travel offset. Explicit constructor
+ * arguments are untouched — only "current time" moves.
+ */
+class ShiftedDate extends RealDate {
+    constructor(...args) {
+        if (args.length === 0)
+            super(RealDate.now() + offset);
+        else
+            super(...args);
+    }
+    static now() {
+        return RealDate.now() + offset;
+    }
+}
+function install() {
+    if (installed)
+        return;
+    globalThis.Date = ShiftedDate;
+    installed = true;
+}
+/**
+ * Time travel without a test-runner dependency — works in any runner:
+ *
+ * time.travel('15d')       // trials expire, meters roll over
+ * time.travelTo(new Date('2027-01-01'))
+ * time.restore()           // always call in afterEach
+ */
+export const time = {
+    travel(duration) {
+        install();
+        offset += parseDuration(duration);
+    },
+    travelTo(date) {
+        install();
+        offset = date.getTime() - RealDate.now();
+    },
+    /** Undoes the patch and resets the offset. */
+    restore() {
+        offset = 0;
+        if (installed) {
+            globalThis.Date = RealDate;
+            installed = false;
+        }
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/testing",
-  "version": "1.0.0",
+  "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",
@@ -14,18 +14,22 @@
     "dist"
   ],
   "dependencies": {
-    "fastify": "^5.3.0",
-    "@basaltkit/core": "^1.0.0",
-    "@basaltkit/queue": "^1.0.0",
-    "@basaltkit/fastify": "^1.0.0",
-    "@basaltkit/mailer": "^1.0.0"
+    "fastify": "^5.12.1",
+    "@basaltkit/core": "^1.1.2",
+    "@basaltkit/fastify": "^1.6.1",
+    "@basaltkit/mailer": "^1.2.2",
+    "@basaltkit/queue": "^1.2.1"
   },
   "devDependencies": {
-    "@types/node": "^22.15.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
-    "zod": "^3.24.0",
+    "@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": {
@@ -33,18 +37,30 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/testing"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/testing#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/testing#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
     "testing"
   ],
+  "peerDependencies": {
+    "@basaltkit/express": "^1.2.1",
+    "@basaltkit/hono": "^1.2.1"
+  },
+  "peerDependenciesMeta": {
+    "@basaltkit/express": {
+      "optional": true
+    },
+    "@basaltkit/hono": {
+      "optional": true
+    }
+  },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }