@basaltkit/testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# @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.
+
+## What this module solves
+
+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.
+
+Everything works with any test runner (Vitest, Jest, node:test…), because nothing here depends on the runner.
+
+## Installation
+
+```bash
+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`.
+
+## Get started in 5 minutes
+
+1. Create a simple route and a test. In `tests/health.test.ts`:
+
+```typescript
+import { describe, expect, it } from 'vitest'
+import { fastifyPlugin, route } from '@basaltkit/fastify'
+import { createTestApp } from '@basaltkit/testing'
+
+const health = route({
+  method: 'GET',
+  url: '/health',
+  async handler() {
+    return { ok: true }
+  },
+})
+
+describe('health', () => {
+  it('responds 200 with ok: true', async () => {
+    const app = await createTestApp({
+      plugins: [fastifyPlugin({ routes: [health] })],
+    })
+
+    const response = await app.get('/health')
+    expect(response.statusCode).toBe(200)
+    expect(response.json()).toEqual({ ok: true })
+
+    await app.shutdown() // always shut down the app at the end
+  })
+})
+```
+
+2. Run the test:
+
+```bash
+pnpm vitest run
+```
+
+There's no port, no network, no separate server starting up — the request is injected directly into Fastify (Fastify's own `inject` mechanism).
+
+## Usage guide
+
+### Fluent HTTP requests
+
+`TestApp` has one method per HTTP verb. For verbs with a body (`post`, `put`, `patch`), the second argument is the payload:
+
+```typescript
+const created = await app.post('/projects', { name: 'First' })
+expect(created.statusCode).toBe(201)
+const id = created.json().id
+
+await app.patch(`/projects/${id}`, { name: 'Renamed' })
+await app.delete(`/projects/${id}`)
+```
+
+The response is a Fastify `LightMyRequestResponse`: use `.statusCode`, `.json()`, `.body`, `.headers`.
+
+### 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.**
+
+```typescript
+import { ctx } from '@basaltkit/core'
+import { fastifyPlugin, route } from '@basaltkit/fastify'
+import { createTestApp } from '@basaltkit/testing'
+
+const whoami = route({
+  method: 'GET',
+  url: '/whoami',
+  async handler() {
+    const { user, tenant } = ctx()
+    return { user: user ?? null, tenant: tenant ?? null }
+  },
+})
+
+const app = await createTestApp({ plugins: [fastifyPlugin({ routes: [whoami] })] })
+
+// defaults for every subsequent request (chainable)
+app.actingAs({ id: 'u1', email: 'ada@example.com' }).asTenant('acme')
+const me = await app.get('/whoami')
+// → { user: { id: 'u1', email: 'ada@example.com' }, tenant: { id: 'acme' } }
+
+// override for a single request only
+const other = await app.get('/whoami', { tenant: 'globex' })
+// → tenant: { id: 'globex' }
+
+await app.shutdown()
+```
+
+### Fake mail with assertions — `fakeMailer`
+
+Records "sent" emails in memory instead of sending them:
+
+```typescript
+import { describe, expect, it } from 'vitest'
+import { z } from 'zod'
+import { defineMail, MAILER } from '@basaltkit/mailer'
+import { createTestApp, fakeMailer } from '@basaltkit/testing'
+
+const WelcomeEmail = defineMail({
+  name: 'welcome',
+  schema: z.object({ name: z.string() }),
+  subject: ({ name }) => `Welcome, ${name}!`,
+  text: ({ name }) => `Hello ${name}`,
+})
+
+it('sends the welcome email', async () => {
+  const mail = fakeMailer()
+  const app = await createTestApp({ plugins: [mail.plugin] })
+
+  mail.assertNothingSent()
+  const mailer = app.container.get(MAILER)
+  await mailer.send(WelcomeEmail, { name: 'Ada' }, { to: 'ada@example.com' })
+
+  const sent = mail.assertSent(WelcomeEmail, (m) => m.to.includes('ada@example.com'))
+  expect(sent.subject).toBe('Welcome, Ada!')
+
+  await app.shutdown()
+})
+```
+
+`assertSent` returns the first matching message (so you can check the subject, recipients, etc.) and throws `MailAssertionError` if nothing matches; `assertNothingSent` throws if anything was sent. The `mail.sent` array has everything, in order.
+
+### Fake queue — `fakeQueue`
+
+Captures job dispatches **without running them**; `drain()` runs the accumulated jobs through the real handlers:
+
+```typescript
+import { expect, it } from 'vitest'
+import { z } from 'zod'
+import { defineJob } from '@basaltkit/queue'
+import { createTestApp, fakeQueue } from '@basaltkit/testing'
+
+const SendWelcome = defineJob({
+  name: 'email.welcome',
+  schema: z.object({ userId: z.string() }),
+  handle: ({ userId }) => console.log('processing', userId),
+})
+
+it('dispatches the welcome job', async () => {
+  const queue = fakeQueue({ jobs: [SendWelcome] })
+  const app = await createTestApp({ plugins: [queue.plugin] })
+
+  await SendWelcome.dispatch({ userId: 'u-1' })
+
+  const captured = queue.assertDispatched(SendWelcome)
+  expect(captured.queue).toBe('default')
+  expect(captured.payload).toEqual({ userId: 'u-1' })
+
+  // nothing has run yet; now run the real handlers:
+  expect(await queue.drain()).toBe(1)
+
+  await app.shutdown()
+})
+```
+
+### Time travel — `time`
+
+Shifts "now" (`Date.now()` and `new Date()` with no arguments) without depending on the test runner. Explicit dates (`new Date('2026-01-01')`) aren't affected.
+
+```typescript
+import { afterEach, expect, it } from 'vitest'
+import { time } from '@basaltkit/testing'
+
+afterEach(() => time.restore()) // ALWAYS call this in afterEach
+
+it('the trial expires after 15 days', () => {
+  time.travel('15d')                        // advances 15 days (accumulates)
+  time.travelTo(new Date('2030-06-01'))     // or pin an exact date
+  expect(new Date().toISOString().slice(0, 10)).toBe('2030-06-01')
+})
+```
+
+The duration format (`'15d'`, `'2h'`, …) is `@basaltkit/core`'s `DurationInput` (`parseDuration`).
+
+## API reference
+
+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`.
+
+| Parameter | Type | Required? | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | `CreateAppOptions` | No | `{}` | Options for `createApp`; your `plugins` are added after the impersonation plugin |
+
+### `TestApp` class
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `app` | `BasaltApp` | The underlying application |
+| `container` | `Container` (getter) | Dependency container — `app.container.get(TOKEN)` |
+| `server` | `FastifyInstance` (getter) | The Fastify server (token `FASTIFY`) |
+| `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 |
+| `get(url, options?)` | same | GET |
+| `post(url, payload?, options?)` | same | POST with body |
+| `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) |
+
+`TestActor`: `{ id: string; email?: string; [key: string]: unknown }`.
+
+`TestRequestOptions`:
+
+| Field | Type | Required? | Default | Description |
+| --- | --- | --- | --- | --- |
+| `payload` | `unknown` | No | — | Request body |
+| `headers` | `Record<string, string>` | No | — | Extra headers |
+| `user` | `TestActor` | No | `actingAs` default | User for this request only |
+| `tenant` | `string \| { id: string; … }` | No | `asTenant` default | Tenant for this request only |
+
+### `fakeMailer(options?): FakeMailer`
+
+| Parameter | Type | Required? | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options` | `MailerOptions` | No | `{ from: 'test@basalt.dev' }` | Options for the real `Mailer` (sender, etc.) |
+
+`FakeMailer`:
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `plugin` | Basalt plugin | Registers the fake mailer — pass it in `createTestApp({ plugins: [mail.plugin, …] })` |
+| `sent` | `ResolvedMail[]` | Everything "sent", in order |
+| `assertSent(mail, predicate?)` | `(MailDefinition \| string, (m: ResolvedMail) => boolean) => ResolvedMail` | Returns the first match; throws `MailAssertionError` if none |
+| `assertNothingSent()` | `() => void` | Throws `MailAssertionError` if anything was sent |
+
+`FAKE_MAILER` — token `createToken<FakeMailer>('testing:mailer')`. *(Advanced.)*
+
+### `fakeQueue(options?): FakeQueue`
+
+| Parameter | Type | Required? | Default | Description |
+| --- | --- | --- | --- | --- |
+| `options.jobs` | `JobDefinition[]` | No | — | Jobs to register in `queuePlugin` (required for `drain()` to run the handlers) |
+
+`FakeQueue`:
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `plugin` | `queuePlugin(...)` | Registers the fake queue in the test application |
+| `dispatched` | `CapturedJob[]` | All dispatches, in order |
+| `assertDispatched(job, predicate?)` | `(JobDefinition \| string, (c: CapturedJob) => boolean) => CapturedJob` | Returns the first match; throws `QueueAssertionError` if none |
+| `assertNothingDispatched()` | `() => void` | Throws `QueueAssertionError` if anything was dispatched |
+| `drain()` | `() => Promise<number>` | Runs the accumulated jobs through the real handlers; returns how many ran |
+
+`CapturedJob`: `{ queue: string; job: string; payload: unknown; context: unknown; options: AddJobOptions }`.
+
+### `time`
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `time.travel(duration)` | `(duration: DurationInput) => void` | Advances the clock (accumulates with previous calls) |
+| `time.travelTo(date)` | `(date: Date) => void` | Pins "now" to an exact date |
+| `time.restore()` | `() => void` | Undoes the patch and resets the offset to zero — always call in `afterEach` |
+
+### Errors
+
+- `MailAssertionError` — code `TEST_MAIL_ASSERTION` (extends `BasaltError`).
+- `QueueAssertionError` — code `TEST_QUEUE_ASSERTION` (extends `BasaltError`).
+
+## Common errors and solutions (FAQ)
+
+**The test hangs and Vitest doesn't finish.**
+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.
+
+**`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.
+
+**`drain()` returns 0 or the handlers don't run.**
+Pass the jobs when creating the fake queue: `fakeQueue({ jobs: [MyJob] })`. Without the registration, the runner doesn't know which handler to call.
+
+**A time travel "contaminated" subsequent tests.**
+The `Date` patch is global. Call `time.restore()` in `afterEach` — even if only one test travels in time.
+
+**Can I use `actingAs` in production?**
+No. The impersonation plugin reads headers (`x-test-user`) without any validation — it's exclusively for tests and only exists inside `createTestApp`.
+
+## 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/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.

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+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 };

package/dist/index.js

@@ -0,0 +1,253 @@
+// 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
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@basaltkit/testing",
+  "version": "1.0.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",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "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"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "zod": "^3.24.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/testing"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/testing#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "testing"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}