@btravstack/testing 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benoit TRAVERS
+
+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,99 @@
+<!-- doctest: prelude
+import { TestRuntimePort } from "@btravstack/testing";
+import { Env } from "@btravstack/config";
+import { Port, type Module, type Scope } from "@btravstack/di";
+class Logger extends Port("Logger")<{
+  readonly info: (message: string) => void;
+  readonly lines: () => readonly string[];
+}> {}
+declare const OrderApi: Module<
+  InstanceType<typeof TestRuntimePort> | Logger,
+  never,
+  Env | Scope
+>;
+declare const RequestModule: Module<never, never, Logger>;
+-->
+
+# @btravstack/testing
+
+> Test the applications [`@btravstack/core`](../core) boots. A `test.extend`
+> fixture that starts a module with a test's defaults and stops every app it
+> started when the test ends, a tap that hands back the very services a booted
+> graph holds, an in-memory runtime, a clock that moves on demand — the way
+> `@nestjs/testing` is to NestJS, and kept out of the kernel so a production
+> bundle never pulls the fakes in.
+
+📖 **[Documentation](https://btravstack.github.io/btravstack/how-to/test-an-application)** ·
+[Reference](https://btravstack.github.io/btravstack/reference/testing) ·
+[API Reference](https://btravstack.github.io/btravstack/api/testing/)
+
+```sh
+pnpm add -D @btravstack/testing @btravstack/core @btravstack/config @btravstack/di unthrown
+```
+
+`@btravstack/core`, `@btravstack/config`, `@btravstack/di` and `unthrown` are
+peer dependencies; the package depends on nothing else — not even `vitest`:
+`bootFixture` is a plain `(ctx, use) => Promise<void>` function, which is
+vitest's fixture protocol, so no import is needed to hand it to `test.extend`.
+Node `>=20`.
+
+## A booted application, as a fixture
+
+```ts
+import { bootFixture, tapped, type Boot } from "@btravstack/testing";
+import { expect, test } from "vitest";
+
+const it = test.extend<{ boot: Boot }>({
+  boot: bootFixture({ env: { PORT: "0", HOST: "127.0.0.1" } }),
+});
+
+it("serves on an ephemeral port", async ({ boot }) => {
+  const app = boot(OrderApi, { unit: RequestModule });
+
+  await expect(app.runtimeInfo()).toBeOkWith(
+    expect.objectContaining({ port: expect.any(Number) }),
+  );
+});
+
+it("holds the very logger the use cases write to", async ({ boot }) => {
+  const tap = tapped(OrderApi, [Logger]);
+  await boot(tap.module, { unit: RequestModule }).runtimeInfo();
+
+  const [logger] = tap.services();
+  expect(logger.lines()).toEqual([]);
+});
+```
+
+`boot` is `start` as a test hands it out: the same signature, the same
+compile-time gate, minus `signals` — always off — with `probes: false` unless
+a call asks for a port, `preDrainDelayMs: 0` and a silent `onEvent` as
+defaults, each overridable by the fixture's `defaults` and again per call.
+When the test ends every app it started is stopped, on every exit path, a
+failing assertion included; a **`Defect`** on `exited` fails the test even
+when the test never looked at it, while a modeled `Err` — a startup failure
+the test may be asserting — passes through.
+
+`tapped(module, [Port, …])` composes one more provider around `module`,
+depending on those ports, and remembers what it was built with: `services()`
+answers the very instances the running graph holds once it is built — after
+`runtimeInfo()` resolves, say — and throws before. The gate refuses a port
+`module` does not export.
+
+## What it ships
+
+- **`bootFixture(defaults?)`** — the fixture above; `Boot` and `BootDefaults`
+  are its types.
+- **`tapped(module, ports)`** → `{ module, services() }` — read services out
+  of a booted application.
+- **`testRuntime(name?)`** / **`TestRuntimePort`** — an in-memory `Runtime`
+  with `submit()` to hold a unit open across a drain, and a `module` that
+  provides it where a starter would.
+- **`createFakeClock(start?)`** — a `Clock` for `StartOptions.clock` whose
+  time moves only on `advance(ms)`.
+
+The teardown rule: a `Defect` on `exited` fails the test, a modeled `Err` does
+not.
+
+## License
+
+[MIT](./LICENSE) © Benoit TRAVERS

package/dist/index.cjs

@@ -0,0 +1,226 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _btravstack_core = require("@btravstack/core");
+let node_timers_promises = require("node:timers/promises");
+let unthrown = require("unthrown");
+let _btravstack_di = require("@btravstack/di");
+//#region src/boot-fixture.ts
+/**
+* A `test.extend` fixture that hands the test a {@link Boot} and stops every
+* application it started once the test is over — on every exit path, a failing
+* assertion included, which is what `test.extend`'s teardown is for.
+*
+* ```ts
+* export const it = test.extend<{ boot: Boot }>({
+*   boot: bootFixture({ env: { PORT: "0", HOST: "127.0.0.1" } }),
+* });
+*
+* it("answers", async ({ boot }) => {
+*   const app = boot(OrderApi, { unit: RequestModule });
+*   …
+* });
+* ```
+*
+* The defaults are a test's: `signals: false` always (process-wide handlers
+* would fight across a file), `probes: false`, `preDrainDelayMs: 0` and a silent
+* `onEvent` — each overridable by `defaults` and again per call.
+*
+* Teardown is `stop()`, then `exited` is examined: a **`Defect`** fails the test
+* even when the test never looked at `exited`, while a modeled `Err` passes
+* through, since a startup failure is an outcome a test may be asserting.
+*/
+const bootFixture = (defaults = {}) => async ({}, use) => {
+	const started = [];
+	const boot = ((module, options = {}) => {
+		const app = (0, _btravstack_core.start)(module, {
+			preDrainDelayMs: 0,
+			onEvent: () => {},
+			probes: false,
+			...defaults,
+			...options,
+			signals: false
+		});
+		started.push(app);
+		return app;
+	});
+	await use(boot);
+	for (const app of started) {
+		app.stop();
+		const exit = await app.exited;
+		if (exit.isDefect()) throw exit.cause;
+	}
+};
+//#endregion
+//#region src/fake-clock.ts
+const flush = () => (0, node_timers_promises.setTimeout)(0);
+/**
+* A {@link Clock} whose time only moves when a test says so.
+*
+* Pass it as `StartOptions.clock` to drive the drain's pre-drain delay and
+* deadline explicitly, instead of waiting out the real 5s/20s defaults.
+*
+* @example
+* ```ts
+* const clock = createFakeClock();
+* const app = start(AppModule, { runtime, clock });
+*
+* app.requestDrain();
+* await clock.advance(5_000); // the pre-drain delay
+* await clock.advance(20_000); // the drain deadline
+* ```
+*/
+const createFakeClock = (start = 0) => {
+	let now = start;
+	let sleepers = [];
+	return {
+		now: () => now,
+		sleep: (ms, signal) => (0, unthrown.fromSafePromise)(new Promise((resolve) => {
+			if (ms <= 0 || signal?.aborted === true) {
+				resolve();
+				return;
+			}
+			const sleeper = {
+				due: now + ms,
+				resolve
+			};
+			sleepers = [...sleepers, sleeper];
+			signal?.addEventListener("abort", () => {
+				sleepers = sleepers.filter((pending) => pending !== sleeper);
+				resolve();
+			}, { once: true });
+		})),
+		advance: (ms) => (0, unthrown.fromSafePromise)((async () => {
+			await flush();
+			now += ms;
+			const due = sleepers.filter((sleeper) => sleeper.due <= now);
+			sleepers = sleepers.filter((sleeper) => sleeper.due > now);
+			for (const sleeper of due) sleeper.resolve();
+			await flush();
+		})())
+	};
+};
+//#endregion
+//#region src/overridden.ts
+/**
+* The real composition root, with named providers substituted — the testing half
+* of "swapping an adapter is composing a different module", for the seam
+* composition cannot reach: nothing can be layered over a graph that already
+* provides a port, so the alternative was a parallel root that drifted silently.
+*
+* Each override is an ordinary `Provider(Port)(...)`, so the service type is
+* checked against the port at that call. At run time an override REPLACES the
+* base provider — the base is never constructed — and an override for a port the
+* tree no longer provides is a `WiringDefect` ("nothing to override"), which is
+* what turns fixture drift into a loud failure.
+*
+* It replaces ONE provider, never a subsystem: the replaced provider's siblings
+* still construct, so swapping a whole adapter stack remains a different module
+* composed in its place.
+*
+* An override's own deps deliberately do NOT widen the returned `Needs`: they
+* resolve from the graph's INTERNALS, and typing them into `N` would force a
+* root to re-export internals to be overridable. They are checked at build
+* instead, by `plan`'s missing-provider defect.
+*/
+const overridden = (module, overrides) => (0, _btravstack_di.Module)("Overridden")({
+	imports: [module],
+	provides: overrides.map((override) => (0, _btravstack_di.overrideProvider)(override)),
+	exports: [module]
+});
+//#endregion
+//#region src/tapped.ts
+const tapped = (module, ports) => {
+	let services;
+	const tap = (0, _btravstack_di.Provider)(Tap)(Object.fromEntries(ports.map((port, index) => [index, port])), { sync: (built) => {
+		services = ports.map((_, index) => built[index]);
+		return {};
+	} });
+	return {
+		module: (0, _btravstack_di.Module)("Tapped")({
+			imports: [module],
+			provides: [tap],
+			exports: [module]
+		}),
+		services: () => {
+			if (services === void 0) throw new Error("[testing] tapped(...).services() read before the graph was built");
+			return services;
+		}
+	};
+};
+var Tap = class extends (0, _btravstack_di.Port)("@btravstack/testing/Tap") {};
+//#endregion
+//#region src/test-runtime.ts
+/** The in-memory runtime's port: what `TestRuntime.module` provides, and what a test composition exports. */
+var TestRuntimePort = class extends _btravstack_core.RuntimePort {};
+const testRuntime = (name = "test") => {
+	let run;
+	let accepting = false;
+	let serving;
+	let submitted = 0;
+	let onStarted;
+	const started = new Promise((resolve) => {
+		onStarted = resolve;
+	});
+	const make = () => ({
+		info: { name },
+		drain: (signal) => {
+			accepting = false;
+			return (0, unthrown.OkAsync)();
+		},
+		stop: () => {
+			accepting = false;
+			return (0, unthrown.OkAsync)();
+		}
+	});
+	const runtime = {
+		name,
+		module: (0, _btravstack_di.Module)("TestRuntime")({
+			provides: [(0, _btravstack_di.Provider)(TestRuntimePort)({ sync: () => runtime })],
+			exports: [TestRuntimePort]
+		}),
+		resolves: [],
+		start: (host) => {
+			run = host.run;
+			accepting = true;
+			serving = make();
+			onStarted();
+			return (0, unthrown.OkAsync)(serving);
+		},
+		started: () => serving !== void 0,
+		untilStarted: () => (0, unthrown.fromSafePromise)(started),
+		accepting: () => accepting,
+		serving: () => {
+			if (serving === void 0) throw new Error("[test-runtime] not started");
+			return serving;
+		},
+		submit: () => {
+			if (run === void 0 || !accepting) throw new Error("[test-runtime] not accepting work");
+			submitted += 1;
+			let settle;
+			const held = new Promise((resolve) => {
+				settle = resolve;
+			});
+			const forwarded = new AbortController();
+			const result = run({
+				kind: "test",
+				id: `${submitted}`
+			}, (_ctx, signal) => {
+				if (signal.aborted) forwarded.abort(signal.reason);
+				else signal.addEventListener("abort", () => forwarded.abort(signal.reason), { once: true });
+				return held;
+			});
+			return {
+				settle,
+				result,
+				signal: forwarded.signal
+			};
+		}
+	};
+	return runtime;
+};
+//#endregion
+exports.TestRuntimePort = TestRuntimePort;
+exports.bootFixture = bootFixture;
+exports.createFakeClock = createFakeClock;
+exports.overridden = overridden;
+exports.tapped = tapped;
+exports.testRuntime = testRuntime;

package/dist/index.d.cts

@@ -0,0 +1,170 @@
+import { Env } from "@btravstack/config";
+import { Clock, RunningApp, Runtime, RuntimeInfoOf, RuntimePort, Serving, StartGate, StartOptions } from "@btravstack/core";
+import { AnyPort, Module, Provider, Scope, ServiceOf } from "@btravstack/di";
+import { AsyncResult, Result } from "unthrown";
+//#region src/boot-fixture.d.ts
+/**
+ * `start`, as a test hands it out: the same signature and the same phantom
+ * gate, minus `signals` (always off) — every application it starts is stopped
+ * when the test ends.
+ */
+type Boot = <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: Omit<StartOptions<UnitX, UnitNeeds>, "signals">) => RunningApp<E, RuntimeInfoOf<X>>;
+/** What every `boot` in the fixture starts with; a call's own options win. */
+type BootDefaults = Omit<StartOptions, "signals" | "unit">;
+/**
+ * A `test.extend` fixture that hands the test a {@link Boot} and stops every
+ * application it started once the test is over — on every exit path, a failing
+ * assertion included, which is what `test.extend`'s teardown is for.
+ *
+ * ```ts
+ * export const it = test.extend<{ boot: Boot }>({
+ *   boot: bootFixture({ env: { PORT: "0", HOST: "127.0.0.1" } }),
+ * });
+ *
+ * it("answers", async ({ boot }) => {
+ *   const app = boot(OrderApi, { unit: RequestModule });
+ *   …
+ * });
+ * ```
+ *
+ * The defaults are a test's: `signals: false` always (process-wide handlers
+ * would fight across a file), `probes: false`, `preDrainDelayMs: 0` and a silent
+ * `onEvent` — each overridable by `defaults` and again per call.
+ *
+ * Teardown is `stop()`, then `exited` is examined: a **`Defect`** fails the test
+ * even when the test never looked at `exited`, while a modeled `Err` passes
+ * through, since a startup failure is an outcome a test may be asserting.
+ */
+declare const bootFixture: (defaults?: BootDefaults) => ({}: object, use: (boot: Boot) => Promise<void>) => Promise<void>;
+//#endregion
+//#region src/fake-clock.d.ts
+type FakeClock = Clock & {
+  /**
+   * Move the clock forward, resolving every sleep whose deadline has passed.
+   *
+   * The returned `AsyncResult` settles once the code under test has had a
+   * chance to react — so `await clock.advance(5_000)` leaves the application
+   * where the elapsed time takes it, with no extra flushing at the call site.
+   */
+  readonly advance: (ms: number) => AsyncResult<void, never>;
+};
+/**
+ * A {@link Clock} whose time only moves when a test says so.
+ *
+ * Pass it as `StartOptions.clock` to drive the drain's pre-drain delay and
+ * deadline explicitly, instead of waiting out the real 5s/20s defaults.
+ *
+ * @example
+ * ```ts
+ * const clock = createFakeClock();
+ * const app = start(AppModule, { runtime, clock });
+ *
+ * app.requestDrain();
+ * await clock.advance(5_000); // the pre-drain delay
+ * await clock.advance(20_000); // the drain deadline
+ * ```
+ */
+declare const createFakeClock: (start?: number) => FakeClock;
+//#endregion
+//#region src/overridden.d.ts
+/** One override's error channel, unioned across the tuple by `overridden`. */
+type ErrorsOf<O extends readonly AnyProviderFor[]> = O[number] extends Provider<never, infer E, unknown> ? E : never;
+/** The widest provider `overridden` accepts — variance makes every real one assignable. */
+type AnyProviderFor = Provider<never, unknown, unknown>;
+/**
+ * The real composition root, with named providers substituted — the testing half
+ * of "swapping an adapter is composing a different module", for the seam
+ * composition cannot reach: nothing can be layered over a graph that already
+ * provides a port, so the alternative was a parallel root that drifted silently.
+ *
+ * Each override is an ordinary `Provider(Port)(...)`, so the service type is
+ * checked against the port at that call. At run time an override REPLACES the
+ * base provider — the base is never constructed — and an override for a port the
+ * tree no longer provides is a `WiringDefect` ("nothing to override"), which is
+ * what turns fixture drift into a loud failure.
+ *
+ * It replaces ONE provider, never a subsystem: the replaced provider's siblings
+ * still construct, so swapping a whole adapter stack remains a different module
+ * composed in its place.
+ *
+ * An override's own deps deliberately do NOT widen the returned `Needs`: they
+ * resolve from the graph's INTERNALS, and typing them into `N` would force a
+ * root to re-export internals to be overridable. They are checked at build
+ * instead, by `plan`'s missing-provider defect.
+ */
+declare const overridden: <X, E, N, const O extends readonly AnyProviderFor[]>(module: Module<X, E, N>, overrides: O) => Module<X, E | ErrorsOf<O>, N>;
+//#endregion
+//#region src/tapped.d.ts
+/** The services behind `ports`, in order — what `tapped(...).services()` answers once the graph is built. */
+type ServicesOf<P extends readonly AnyPort[]> = { readonly [K in keyof P]: ServiceOf<InstanceType<P[K]>>; };
+/**
+ * Read services out of a booted application.
+ *
+ * `start` hands the application context to the runtime alone, so a test that
+ * wants the very `Logger` the use cases write to — not a fresh one — has no
+ * `ctx.get` to reach it with. `tapped` composes one more provider around
+ * `module`, depending on `ports`, and remembers what it was built with:
+ *
+ * ```ts
+ * const tap = tapped(OrderApi, [Logger]);
+ * const app = boot(tap.module);
+ * await client.orders.place({ id: "o-1", quantity: 2 });
+ * const [logger] = tap.services();
+ * expect(logger.lines()).toContain(…);
+ * ```
+ *
+ * The returned module exports exactly what `module` exports, so the kernel still
+ * finds the runtime. `services()` is loud before the graph has been built:
+ * reading a tap nobody booted is a bug in the test, and an `undefined` a
+ * careless assertion could swallow is worse than a throw. The gate refuses a
+ * port `module` does not export — an application-scope service is the only thing
+ * there is to tap.
+ */
+type TapGate<P extends readonly AnyPort[], X> = [Exclude<InstanceType<P[number]>, X>] extends [never] ? unknown : {
+  readonly "NOT EXPORTED — tap only what the module exports": Exclude<InstanceType<P[number]>, X>;
+};
+declare const tapped: <X, E, N, const P extends readonly AnyPort[]>(module: Module<X, E, N>, ports: P & TapGate<P, X>) => {
+  readonly module: Module<X, E, N>;
+  readonly services: () => ServicesOf<P>;
+};
+//#endregion
+//#region src/test-runtime.d.ts
+type SubmittedUnit<T, E> = {
+  readonly settle: (result: Result<T, E>) => void;
+  readonly result: AsyncResult<T, E>;
+  readonly signal: AbortSignal;
+};
+/**
+ * What `testRuntime` publishes on `Serving.info` — its own name, the one thing
+ * an in-memory runtime genuinely knows about itself.
+ */
+type TestRuntimeInfo = {
+  readonly name: string;
+};
+/** The in-memory runtime's port: what `TestRuntime.module` provides, and what a test composition exports. */
+declare class TestRuntimePort extends RuntimePort<Runtime<never, TestRuntimeInfo>> {}
+type TestRuntime = Runtime<never, TestRuntimeInfo> & {
+  /**
+   * A module providing this very runtime on `TestRuntimePort`: import it next
+   * to the module under test, export the port, and `start` finds it.
+   *
+   * It provides THIS object, so a wrapper built by spreading copies the module
+   * too and that module still boots the inner runtime — a wrapper needs a module
+   * of its own.
+   */
+  readonly module: Module<TestRuntimePort, never, never>;
+  readonly started: () => boolean;
+  /** Resolves the first time the kernel calls `start` — `start` itself stays pending until shutdown. */
+  readonly untilStarted: () => AsyncResult<void, never>;
+  /**
+   * Whether the runtime would still take new work — false once `drain` or
+   * `stop` has been called, so a test can observe WHEN the kernel told it to
+   * stop accepting.
+   */
+  readonly accepting: () => boolean;
+  readonly serving: () => Serving<TestRuntimeInfo>;
+  readonly submit: <T = string, E = never>() => SubmittedUnit<T, E>;
+};
+declare const testRuntime: (name?: string) => TestRuntime;
+//#endregion
+export { type Boot, type BootDefaults, type FakeClock, type ServicesOf, type SubmittedUnit, type TestRuntime, type TestRuntimeInfo, TestRuntimePort, bootFixture, createFakeClock, overridden, tapped, testRuntime };

package/dist/index.d.mts

@@ -0,0 +1,170 @@
+import { Clock, RunningApp, Runtime, RuntimeInfoOf, RuntimePort, Serving, StartGate, StartOptions } from "@btravstack/core";
+import { AsyncResult, Result } from "unthrown";
+import { AnyPort, Module, Provider, Scope, ServiceOf } from "@btravstack/di";
+import { Env } from "@btravstack/config";
+//#region src/boot-fixture.d.ts
+/**
+ * `start`, as a test hands it out: the same signature and the same phantom
+ * gate, minus `signals` (always off) — every application it starts is stopped
+ * when the test ends.
+ */
+type Boot = <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: Omit<StartOptions<UnitX, UnitNeeds>, "signals">) => RunningApp<E, RuntimeInfoOf<X>>;
+/** What every `boot` in the fixture starts with; a call's own options win. */
+type BootDefaults = Omit<StartOptions, "signals" | "unit">;
+/**
+ * A `test.extend` fixture that hands the test a {@link Boot} and stops every
+ * application it started once the test is over — on every exit path, a failing
+ * assertion included, which is what `test.extend`'s teardown is for.
+ *
+ * ```ts
+ * export const it = test.extend<{ boot: Boot }>({
+ *   boot: bootFixture({ env: { PORT: "0", HOST: "127.0.0.1" } }),
+ * });
+ *
+ * it("answers", async ({ boot }) => {
+ *   const app = boot(OrderApi, { unit: RequestModule });
+ *   …
+ * });
+ * ```
+ *
+ * The defaults are a test's: `signals: false` always (process-wide handlers
+ * would fight across a file), `probes: false`, `preDrainDelayMs: 0` and a silent
+ * `onEvent` — each overridable by `defaults` and again per call.
+ *
+ * Teardown is `stop()`, then `exited` is examined: a **`Defect`** fails the test
+ * even when the test never looked at `exited`, while a modeled `Err` passes
+ * through, since a startup failure is an outcome a test may be asserting.
+ */
+declare const bootFixture: (defaults?: BootDefaults) => ({}: object, use: (boot: Boot) => Promise<void>) => Promise<void>;
+//#endregion
+//#region src/fake-clock.d.ts
+type FakeClock = Clock & {
+  /**
+   * Move the clock forward, resolving every sleep whose deadline has passed.
+   *
+   * The returned `AsyncResult` settles once the code under test has had a
+   * chance to react — so `await clock.advance(5_000)` leaves the application
+   * where the elapsed time takes it, with no extra flushing at the call site.
+   */
+  readonly advance: (ms: number) => AsyncResult<void, never>;
+};
+/**
+ * A {@link Clock} whose time only moves when a test says so.
+ *
+ * Pass it as `StartOptions.clock` to drive the drain's pre-drain delay and
+ * deadline explicitly, instead of waiting out the real 5s/20s defaults.
+ *
+ * @example
+ * ```ts
+ * const clock = createFakeClock();
+ * const app = start(AppModule, { runtime, clock });
+ *
+ * app.requestDrain();
+ * await clock.advance(5_000); // the pre-drain delay
+ * await clock.advance(20_000); // the drain deadline
+ * ```
+ */
+declare const createFakeClock: (start?: number) => FakeClock;
+//#endregion
+//#region src/overridden.d.ts
+/** One override's error channel, unioned across the tuple by `overridden`. */
+type ErrorsOf<O extends readonly AnyProviderFor[]> = O[number] extends Provider<never, infer E, unknown> ? E : never;
+/** The widest provider `overridden` accepts — variance makes every real one assignable. */
+type AnyProviderFor = Provider<never, unknown, unknown>;
+/**
+ * The real composition root, with named providers substituted — the testing half
+ * of "swapping an adapter is composing a different module", for the seam
+ * composition cannot reach: nothing can be layered over a graph that already
+ * provides a port, so the alternative was a parallel root that drifted silently.
+ *
+ * Each override is an ordinary `Provider(Port)(...)`, so the service type is
+ * checked against the port at that call. At run time an override REPLACES the
+ * base provider — the base is never constructed — and an override for a port the
+ * tree no longer provides is a `WiringDefect` ("nothing to override"), which is
+ * what turns fixture drift into a loud failure.
+ *
+ * It replaces ONE provider, never a subsystem: the replaced provider's siblings
+ * still construct, so swapping a whole adapter stack remains a different module
+ * composed in its place.
+ *
+ * An override's own deps deliberately do NOT widen the returned `Needs`: they
+ * resolve from the graph's INTERNALS, and typing them into `N` would force a
+ * root to re-export internals to be overridable. They are checked at build
+ * instead, by `plan`'s missing-provider defect.
+ */
+declare const overridden: <X, E, N, const O extends readonly AnyProviderFor[]>(module: Module<X, E, N>, overrides: O) => Module<X, E | ErrorsOf<O>, N>;
+//#endregion
+//#region src/tapped.d.ts
+/** The services behind `ports`, in order — what `tapped(...).services()` answers once the graph is built. */
+type ServicesOf<P extends readonly AnyPort[]> = { readonly [K in keyof P]: ServiceOf<InstanceType<P[K]>>; };
+/**
+ * Read services out of a booted application.
+ *
+ * `start` hands the application context to the runtime alone, so a test that
+ * wants the very `Logger` the use cases write to — not a fresh one — has no
+ * `ctx.get` to reach it with. `tapped` composes one more provider around
+ * `module`, depending on `ports`, and remembers what it was built with:
+ *
+ * ```ts
+ * const tap = tapped(OrderApi, [Logger]);
+ * const app = boot(tap.module);
+ * await client.orders.place({ id: "o-1", quantity: 2 });
+ * const [logger] = tap.services();
+ * expect(logger.lines()).toContain(…);
+ * ```
+ *
+ * The returned module exports exactly what `module` exports, so the kernel still
+ * finds the runtime. `services()` is loud before the graph has been built:
+ * reading a tap nobody booted is a bug in the test, and an `undefined` a
+ * careless assertion could swallow is worse than a throw. The gate refuses a
+ * port `module` does not export — an application-scope service is the only thing
+ * there is to tap.
+ */
+type TapGate<P extends readonly AnyPort[], X> = [Exclude<InstanceType<P[number]>, X>] extends [never] ? unknown : {
+  readonly "NOT EXPORTED — tap only what the module exports": Exclude<InstanceType<P[number]>, X>;
+};
+declare const tapped: <X, E, N, const P extends readonly AnyPort[]>(module: Module<X, E, N>, ports: P & TapGate<P, X>) => {
+  readonly module: Module<X, E, N>;
+  readonly services: () => ServicesOf<P>;
+};
+//#endregion
+//#region src/test-runtime.d.ts
+type SubmittedUnit<T, E> = {
+  readonly settle: (result: Result<T, E>) => void;
+  readonly result: AsyncResult<T, E>;
+  readonly signal: AbortSignal;
+};
+/**
+ * What `testRuntime` publishes on `Serving.info` — its own name, the one thing
+ * an in-memory runtime genuinely knows about itself.
+ */
+type TestRuntimeInfo = {
+  readonly name: string;
+};
+/** The in-memory runtime's port: what `TestRuntime.module` provides, and what a test composition exports. */
+declare class TestRuntimePort extends RuntimePort<Runtime<never, TestRuntimeInfo>> {}
+type TestRuntime = Runtime<never, TestRuntimeInfo> & {
+  /**
+   * A module providing this very runtime on `TestRuntimePort`: import it next
+   * to the module under test, export the port, and `start` finds it.
+   *
+   * It provides THIS object, so a wrapper built by spreading copies the module
+   * too and that module still boots the inner runtime — a wrapper needs a module
+   * of its own.
+   */
+  readonly module: Module<TestRuntimePort, never, never>;
+  readonly started: () => boolean;
+  /** Resolves the first time the kernel calls `start` — `start` itself stays pending until shutdown. */
+  readonly untilStarted: () => AsyncResult<void, never>;
+  /**
+   * Whether the runtime would still take new work — false once `drain` or
+   * `stop` has been called, so a test can observe WHEN the kernel told it to
+   * stop accepting.
+   */
+  readonly accepting: () => boolean;
+  readonly serving: () => Serving<TestRuntimeInfo>;
+  readonly submit: <T = string, E = never>() => SubmittedUnit<T, E>;
+};
+declare const testRuntime: (name?: string) => TestRuntime;
+//#endregion
+export { type Boot, type BootDefaults, type FakeClock, type ServicesOf, type SubmittedUnit, type TestRuntime, type TestRuntimeInfo, TestRuntimePort, bootFixture, createFakeClock, overridden, tapped, testRuntime };

package/dist/index.mjs

@@ -0,0 +1,220 @@
+import { RuntimePort, start } from "@btravstack/core";
+import { setTimeout } from "node:timers/promises";
+import { OkAsync, fromSafePromise } from "unthrown";
+import { Module, Port, Provider, overrideProvider } from "@btravstack/di";
+//#region src/boot-fixture.ts
+/**
+* A `test.extend` fixture that hands the test a {@link Boot} and stops every
+* application it started once the test is over — on every exit path, a failing
+* assertion included, which is what `test.extend`'s teardown is for.
+*
+* ```ts
+* export const it = test.extend<{ boot: Boot }>({
+*   boot: bootFixture({ env: { PORT: "0", HOST: "127.0.0.1" } }),
+* });
+*
+* it("answers", async ({ boot }) => {
+*   const app = boot(OrderApi, { unit: RequestModule });
+*   …
+* });
+* ```
+*
+* The defaults are a test's: `signals: false` always (process-wide handlers
+* would fight across a file), `probes: false`, `preDrainDelayMs: 0` and a silent
+* `onEvent` — each overridable by `defaults` and again per call.
+*
+* Teardown is `stop()`, then `exited` is examined: a **`Defect`** fails the test
+* even when the test never looked at `exited`, while a modeled `Err` passes
+* through, since a startup failure is an outcome a test may be asserting.
+*/
+const bootFixture = (defaults = {}) => async ({}, use) => {
+	const started = [];
+	const boot = ((module, options = {}) => {
+		const app = start(module, {
+			preDrainDelayMs: 0,
+			onEvent: () => {},
+			probes: false,
+			...defaults,
+			...options,
+			signals: false
+		});
+		started.push(app);
+		return app;
+	});
+	await use(boot);
+	for (const app of started) {
+		app.stop();
+		const exit = await app.exited;
+		if (exit.isDefect()) throw exit.cause;
+	}
+};
+//#endregion
+//#region src/fake-clock.ts
+const flush = () => setTimeout(0);
+/**
+* A {@link Clock} whose time only moves when a test says so.
+*
+* Pass it as `StartOptions.clock` to drive the drain's pre-drain delay and
+* deadline explicitly, instead of waiting out the real 5s/20s defaults.
+*
+* @example
+* ```ts
+* const clock = createFakeClock();
+* const app = start(AppModule, { runtime, clock });
+*
+* app.requestDrain();
+* await clock.advance(5_000); // the pre-drain delay
+* await clock.advance(20_000); // the drain deadline
+* ```
+*/
+const createFakeClock = (start = 0) => {
+	let now = start;
+	let sleepers = [];
+	return {
+		now: () => now,
+		sleep: (ms, signal) => fromSafePromise(new Promise((resolve) => {
+			if (ms <= 0 || signal?.aborted === true) {
+				resolve();
+				return;
+			}
+			const sleeper = {
+				due: now + ms,
+				resolve
+			};
+			sleepers = [...sleepers, sleeper];
+			signal?.addEventListener("abort", () => {
+				sleepers = sleepers.filter((pending) => pending !== sleeper);
+				resolve();
+			}, { once: true });
+		})),
+		advance: (ms) => fromSafePromise((async () => {
+			await flush();
+			now += ms;
+			const due = sleepers.filter((sleeper) => sleeper.due <= now);
+			sleepers = sleepers.filter((sleeper) => sleeper.due > now);
+			for (const sleeper of due) sleeper.resolve();
+			await flush();
+		})())
+	};
+};
+//#endregion
+//#region src/overridden.ts
+/**
+* The real composition root, with named providers substituted — the testing half
+* of "swapping an adapter is composing a different module", for the seam
+* composition cannot reach: nothing can be layered over a graph that already
+* provides a port, so the alternative was a parallel root that drifted silently.
+*
+* Each override is an ordinary `Provider(Port)(...)`, so the service type is
+* checked against the port at that call. At run time an override REPLACES the
+* base provider — the base is never constructed — and an override for a port the
+* tree no longer provides is a `WiringDefect` ("nothing to override"), which is
+* what turns fixture drift into a loud failure.
+*
+* It replaces ONE provider, never a subsystem: the replaced provider's siblings
+* still construct, so swapping a whole adapter stack remains a different module
+* composed in its place.
+*
+* An override's own deps deliberately do NOT widen the returned `Needs`: they
+* resolve from the graph's INTERNALS, and typing them into `N` would force a
+* root to re-export internals to be overridable. They are checked at build
+* instead, by `plan`'s missing-provider defect.
+*/
+const overridden = (module, overrides) => Module("Overridden")({
+	imports: [module],
+	provides: overrides.map((override) => overrideProvider(override)),
+	exports: [module]
+});
+//#endregion
+//#region src/tapped.ts
+const tapped = (module, ports) => {
+	let services;
+	const tap = Provider(Tap)(Object.fromEntries(ports.map((port, index) => [index, port])), { sync: (built) => {
+		services = ports.map((_, index) => built[index]);
+		return {};
+	} });
+	return {
+		module: Module("Tapped")({
+			imports: [module],
+			provides: [tap],
+			exports: [module]
+		}),
+		services: () => {
+			if (services === void 0) throw new Error("[testing] tapped(...).services() read before the graph was built");
+			return services;
+		}
+	};
+};
+var Tap = class extends Port("@btravstack/testing/Tap") {};
+//#endregion
+//#region src/test-runtime.ts
+/** The in-memory runtime's port: what `TestRuntime.module` provides, and what a test composition exports. */
+var TestRuntimePort = class extends RuntimePort {};
+const testRuntime = (name = "test") => {
+	let run;
+	let accepting = false;
+	let serving;
+	let submitted = 0;
+	let onStarted;
+	const started = new Promise((resolve) => {
+		onStarted = resolve;
+	});
+	const make = () => ({
+		info: { name },
+		drain: (signal) => {
+			accepting = false;
+			return OkAsync();
+		},
+		stop: () => {
+			accepting = false;
+			return OkAsync();
+		}
+	});
+	const runtime = {
+		name,
+		module: Module("TestRuntime")({
+			provides: [Provider(TestRuntimePort)({ sync: () => runtime })],
+			exports: [TestRuntimePort]
+		}),
+		resolves: [],
+		start: (host) => {
+			run = host.run;
+			accepting = true;
+			serving = make();
+			onStarted();
+			return OkAsync(serving);
+		},
+		started: () => serving !== void 0,
+		untilStarted: () => fromSafePromise(started),
+		accepting: () => accepting,
+		serving: () => {
+			if (serving === void 0) throw new Error("[test-runtime] not started");
+			return serving;
+		},
+		submit: () => {
+			if (run === void 0 || !accepting) throw new Error("[test-runtime] not accepting work");
+			submitted += 1;
+			let settle;
+			const held = new Promise((resolve) => {
+				settle = resolve;
+			});
+			const forwarded = new AbortController();
+			const result = run({
+				kind: "test",
+				id: `${submitted}`
+			}, (_ctx, signal) => {
+				if (signal.aborted) forwarded.abort(signal.reason);
+				else signal.addEventListener("abort", () => forwarded.abort(signal.reason), { once: true });
+				return held;
+			});
+			return {
+				settle,
+				result,
+				signal: forwarded.signal
+			};
+		}
+	};
+	return runtime;
+};
+//#endregion
+export { TestRuntimePort, bootFixture, createFakeClock, overridden, tapped, testRuntime };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@btravstack/testing",
+  "version": "0.3.0",
+  "description": "Test the applications @btravstack/core boots: an in-memory runtime, a fake clock, a boot fixture that stops what it started, and a tap into a running graph",
+  "keywords": [
+    "dependency-injection",
+    "fixture",
+    "kernel",
+    "testing",
+    "typescript",
+    "unthrown",
+    "vitest"
+  ],
+  "homepage": "https://github.com/btravstack/btravstack#readme",
+  "bugs": {
+    "url": "https://github.com/btravstack/btravstack/issues"
+  },
+  "license": "MIT",
+  "author": "Benoit TRAVERS <benoit.travers.fr@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/btravstack/btravstack.git",
+    "directory": "packages/testing"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@btravstack/tsconfig": "0.2.0",
+    "@types/node": "26.2.0",
+    "@unthrown/vitest": "5.7.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "tsdown": "0.22.14",
+    "typescript": "7.0.2",
+    "unthrown": "5.7.0",
+    "vitest": "4.1.11",
+    "@btravstack/config": "0.3.0",
+    "@btravstack/core": "0.3.0",
+    "@btravstack/di": "0.3.0"
+  },
+  "peerDependencies": {
+    "unthrown": "^5.0.0",
+    "@btravstack/core": "^0.3.0",
+    "@btravstack/di": "^0.3.0",
+    "@btravstack/config": "^0.3.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsdown src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}