@routecraft/testing 0.6.0-canary.8 → 0.6.0

package/dist/index.d.cts

@@ -1,21 +1,53 @@
-import { AdapterOverride, AdapterSourceCall, AdapterSendCall, SourceOverrideBehavior, SendOverrideHandler, Source, CraftContext, CraftClient, RoutecraftError, CraftConfig, EventName, EventHandler, StoreRegistry, RouteDefinition, RouteBuilder, Destination, Processor, Exchange, logger } from '@routecraft/routecraft';
-import { vi } from 'vitest';
+import { AdapterOverride, AdapterSourceCall, AdapterSendCall, SourceOverrideBehavior, SendOverrideHandler, Source, CraftContext, CraftClient, RoutecraftError, CraftConfig, EventName, EventHandler, StoreRegistry, RouteDefinition, AnyRouteBuilder, Destination, Enricher, Processor, Exchange, ExchangeHeaders, SourceFixture, logger, OnParseError, SourceMeta, Subscription } from '@routecraft/routecraft';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
- * Spy logger with vi.fn() methods for assertions (e.g. expect(t.logger.info).toHaveBeenCalledWith(...)).
+ * Minimal runner-agnostic spy function. Records calls in the jest-compatible
+ * `mock.calls` shape so assertions like
+ * `expect(t.logger.warn.mock.calls.some(...))` work under bun:test, Vitest,
+ * and node:test without this package importing any runner.
+ *
+ * Runner mocks (`vi.fn` from Vitest, `mock` from bun:test) are structurally
+ * assignable to this interface, so they can be injected via {@link SpyFactory}
+ * when full matcher support (`expect(fn).toHaveBeenCalledWith(...)`) is
+ * wanted.
+ */
+interface SpyFn {
+    (...args: unknown[]): unknown;
+    mock: {
+        calls: unknown[][];
+    };
+    mockImplementation(impl: (...args: unknown[]) => unknown): SpyFn;
+    mockClear(): void;
+}
+/**
+ * Factory producing spy functions. Defaults to the built-in {@link createSpyFn};
+ * pass your runner's mock factory (`vi.fn`, or `mock` from bun:test) to get
+ * native mocks that work with the runner's `expect` matchers.
+ */
+type SpyFactory = () => SpyFn;
+/**
+ * Create a built-in spy function. Dependency-free; records calls in
+ * `fn.mock.calls` and supports `mockImplementation` / `mockClear`.
+ */
+declare function createSpyFn(): SpyFn;
+/**
+ * Spy logger with spy methods for assertions (e.g.
+ * `t.logger.info.mock.calls` under any runner, or
+ * `expect(t.logger.info).toHaveBeenCalledWith(...)` when built from an
+ * injected runner mock factory).
  */
 type SpyLogger = {
-    info: ReturnType<typeof vi.fn>;
-    debug: ReturnType<typeof vi.fn>;
-    warn: ReturnType<typeof vi.fn>;
-    error: ReturnType<typeof vi.fn>;
-    trace: ReturnType<typeof vi.fn>;
-    fatal: ReturnType<typeof vi.fn>;
-    child: ReturnType<typeof vi.fn>;
+    info: SpyFn;
+    debug: SpyFn;
+    warn: SpyFn;
+    error: SpyFn;
+    trace: SpyFn;
+    fatal: SpyFn;
+    child: SpyFn;
 };
-declare function createSpyLogger(): SpyLogger;
-declare function createNoopSpyLogger(): SpyLogger;
+declare function createSpyLogger(fn?: SpyFactory): SpyLogger;
+declare function createNoopSpyLogger(fn?: SpyFactory): SpyLogger;
 
 /**
  * Brand symbol stamped on the handles returned by `mockAdapter()`.
@@ -50,9 +82,13 @@ interface MockAdapterBehavior<M = unknown> {
      */
     source?: SourceOverrideBehavior<M>;
     /**
-     * Destination-role behaviour. Used when the adapter is passed to `.to()`,
-     * `.enrich()`, or `.tap()`. Receives the exchange and a meta object with
-     * the construction args; returning a value replaces the body upstream.
+     * Destination/enricher-role behaviour. Used when the adapter is passed to
+     * `.to()`, `.enrich()`, or `.tap()`. Receives the exchange and a meta
+     * object with the construction args. The handler's return value follows
+     * the step's slot resolution: a fetch-resolved step (`.enrich()`, or a
+     * fetch-only adapter in `.to()`) uses it as the fetched value (replacing
+     * the body by default), while a send-resolved `.to()` discards it (send
+     * is void) and `.tap()` always discards.
      */
     send?: SendOverrideHandler;
 }
@@ -80,7 +116,7 @@ interface AdapterMock {
  * - An adapter factory (e.g. `mail`, `http`, `mcp`). The mock matches every
  *   adapter instance produced by that factory. Requires the factory to stamp
  *   its adapters via `tagAdapter()`.
- * - An adapter class (e.g. `MailSourceAdapter`, `HttpDestinationAdapter`).
+ * - An adapter class (e.g. `MailSourceAdapter`, `HttpEnricherAdapter`).
  *   The mock matches any adapter whose `constructor === target`. Works for
  *   every adapter without opt-in tagging, including third-party ones.
  *
@@ -104,7 +140,7 @@ interface AdapterMock {
  *
  * const mailMock = mockAdapter(mail, {
  *   source: [{ uid: 1, from: "a@b", subject: "hi", ... }],
- *   send: async () => ({ messageId: "<fake>" }),
+ *   send: async () => undefined,
  * });
  *
  * // Class form (works for any adapter, including third-party ones)
@@ -128,6 +164,13 @@ declare function mockAdapter<T extends ((...args: never[]) => unknown) | (new (.
 interface TestContextOptions {
     /** Timeout in ms for waiting for all routes to emit routeStarted. Default 200. */
     routesReadyTimeoutMs?: number;
+    /**
+     * Mock factory used to build the spy logger. Defaults to the built-in
+     * runner-agnostic spy. Pass your runner's factory (`vi.fn` from Vitest, or
+     * `mock` from bun:test) to get native mocks that work with the runner's
+     * `expect` matchers, e.g. `testContext({ fn: vi.fn })`.
+     */
+    fn?: SpyFactory;
 }
 /**
  * Options for TestContext.test().
@@ -143,13 +186,13 @@ interface TestOptions {
 /**
  * Test-friendly wrapper around CraftContext. Runs the real context but manages
  * lifecycle (start, wait routes ready, drain, stop) and collects errors.
- * t.logger is a spy logger (vi.fn() methods) for asserting on log calls.
+ * t.logger is a spy logger for asserting on log calls.
  */
 declare class TestContext {
     readonly ctx: CraftContext;
     /** Client for dispatching messages to direct endpoints in tests. */
     readonly client: CraftClient;
-    /** Spy logger; e.g. expect(t.logger.info).toHaveBeenCalledWith(...) */
+    /** Spy logger; e.g. t.logger.info.mock.calls, or expect(t.logger.info).toHaveBeenCalledWith(...) with an injected runner mock factory */
     readonly logger: SpyLogger;
     readonly errors: RoutecraftError[];
     private readonly routesReadyTimeoutMs;
@@ -162,23 +205,23 @@ declare class TestContext {
     });
     /**
      * Build a promise that resolves once every route has emitted
-     * `route:*:started`, or rejects on `context:error` or the configured
+     * `route:started`, or rejects on `context:error` or the configured
      * routes-ready timeout. Shared by {@link startAndWaitReady} and {@link test}.
      */
     private awaitRoutesReady;
     /**
-     * Start context and resolve once every route has emitted `route:*:started`.
+     * Start context and resolve once every route has emitted `route:started`.
      * Does not drain or stop. Does not await `ctx.start()` completion, which
      * lets this method work with long-running sources (direct, mcp, HTTP, etc.)
      * whose subscribe blocks until the route is aborted. The start promise is
      * stored internally and awaited by {@link stop} for clean shutdown.
      *
-     * Use with {@link CraftClient.send} (via `t.client`) for direct endpoints,
+     * Use with {@link CraftClient.sendDirect} (via `t.client`) for direct endpoints,
      * or drive sources directly via the context store, then call `drain()` /
      * `stop()` when done.
      *
      * If `ctx.start()` rejects (synchronously or before any route emits
-     * `route:*:started`), the rejection surfaces here via the
+     * `route:started`), the rejection surfaces here via the
      * `context:error` listener installed by `awaitRoutesReady`. A no-op
      * catch is attached to `startedPromise` as a safety net so that a
      * slow rejection does not trigger an `unhandledRejection` before
@@ -205,6 +248,8 @@ declare class TestContextBuilder {
     private builder;
     private routesReadyTimeoutMs;
     private adapterOverrides;
+    private readonly spyFactory;
+    constructor(options?: TestContextOptions);
     /** Override timeout for waiting for routes to start (ms). Used by tests that assert timeout behavior. */
     routesReadyTimeout(ms: number): this;
     /**
@@ -218,18 +263,27 @@ declare class TestContextBuilder {
     on<K extends EventName>(event: K, handler: EventHandler<K>): this;
     once<K extends EventName>(event: K, handler: EventHandler<K>): this;
     store<K extends keyof StoreRegistry>(key: K, value: StoreRegistry[K]): this;
-    routes(routes: RouteDefinition[] | RouteBuilder<unknown>[] | RouteDefinition | RouteBuilder<unknown>): this;
+    routes(routes: RouteDefinition[] | AnyRouteBuilder[] | RouteDefinition | AnyRouteBuilder): this;
     build(): Promise<TestContext>;
 }
 /**
  * Create a test context builder. Use .routes(...).build(), await the result, then await t.test().
  *
+ * Runner-agnostic by default: the spy logger uses a built-in spy that records
+ * calls in the jest-compatible `mock.calls` shape. Pass `{ fn }` with your
+ * runner's mock factory (`vi.fn` from Vitest, `mock` from bun:test) when you
+ * want `expect(t.logger.info).toHaveBeenCalledWith(...)` matcher support.
+ *
  * @example
  * const builder = testContext();
  * const t = await builder.routes(myRoutes).build();
  * await t.test();
+ *
+ * @example
+ * // Vitest, with native matcher support:
+ * const t = await testContext({ fn: vi.fn }).routes(myRoutes).build();
  */
-declare function testContext(): TestContextBuilder;
+declare function testContext(options?: TestContextOptions): TestContextBuilder;
 
 interface PseudoOptions {
     runtime?: "throw" | "noop";
@@ -243,7 +297,7 @@ interface PseudoKeyedOptions extends PseudoOptions {
  */
 type PseudoAdapter<R> = {
     adapterId: string;
-} & Source<R> & Destination<any, R> & Processor<any, R>;
+} & Source<R> & Destination<any> & Enricher<any, R> & Processor<any, R>;
 /** @internal */
 type PseudoFactory<Opts> = <R = unknown>(opts: Opts) => PseudoAdapter<R>;
 /** @internal */
@@ -256,8 +310,10 @@ declare function pseudo<Opts extends Record<string, unknown> = Record<string, un
 
 /**
  * A spy adapter that records all exchanges passing through it.
- * Implements both {@link Destination} and {@link Processor} so it can be used
- * with `.to()`, `.enrich()`, `.tap()`, and `.process()`.
+ * Implements {@link Destination} (send), {@link Enricher} (fetch), and
+ * {@link Processor} so it can be used with `.to()`, `.tap()`, `.enrich()`,
+ * and `.process()`. The fetch face returns the current body, so a bare
+ * `.enrich(spy())` observes without changing the body.
  */
 type SpyAdapter<T = unknown> = {
     /** Stable identifier for this adapter. */
@@ -276,7 +332,7 @@ type SpyAdapter<T = unknown> = {
     lastReceived(): Exchange<T>;
     /** Array of just the body values from received exchanges. */
     receivedBodies(): T[];
-} & Destination<any, void> & Processor<any, T>;
+} & Destination<any> & Enricher<any, T> & Processor<any, T>;
 /**
  * Creates a spy adapter that records all exchanges for test assertions.
  *
@@ -299,6 +355,37 @@ type SpyAdapter<T = unknown> = {
  */
 declare function spy<T = unknown>(): SpyAdapter<T>;
 
+/**
+ * Wrap a message body with the headers a real source would have attached, for
+ * use as a `mockAdapter(..., { source: [...] })` fixture.
+ *
+ * Envelope-carrying sources (mail, http) split each incoming message into a
+ * payload on `exchange.body` and metadata on `routecraft.<adapter>.*` headers.
+ * A bare fixture array only sets the body, so a route that reads those headers
+ * cannot be exercised through the mock. `sourceMessage(body, headers)` lets the
+ * mock reproduce that split.
+ *
+ * @example
+ * ```typescript
+ * const mailMock = mockAdapter(mail, {
+ *   source: [
+ *     sourceMessage(
+ *       { text: "Tracking: ABC123" },
+ *       {
+ *         "routecraft.mail.from": "noreply@acme.test",
+ *         "routecraft.mail.subject": "Your order has shipped",
+ *       },
+ *     ),
+ *   ],
+ * });
+ * ```
+ *
+ * @param body - The body the source would deliver on the exchange
+ * @param headers - Headers the source would attach (omit for a body-only fixture)
+ * @returns A branded fixture recognised by the source-mock dispatcher
+ */
+declare function sourceMessage<M>(body: M, headers?: ExchangeHeaders): SourceFixture<M>;
+
 /**
  * Structural shape of a fn-like spec for testing. Does not import
  * `FnOptions` from `@routecraft/ai` so this package stays free of
@@ -357,6 +444,43 @@ interface TestFnOptions {
  */
 declare function testFn<TIn, TOut>(spec: TestFnSpec<TIn, TOut>, input: unknown, options?: TestFnOptions): Promise<TOut>;
 
+/**
+ * Options for {@link testSubscription}. The `handler` mirrors the message
+ * fields the engine receives, flattened into positional arguments so test
+ * assertions read naturally.
+ */
+interface TestSubscriptionOptions<T = unknown> {
+    /** Context handed to the source (store access, logger). */
+    context: CraftContext;
+    /** Receives each emitted message; its return value resolves `emit`. */
+    handler: (message: T, headers?: ExchangeHeaders, parse?: (raw: unknown) => unknown | Promise<unknown>, parseFailureMode?: OnParseError) => Promise<unknown> | unknown;
+    /** Abort to stop the source; `complete()` calls its `abort`. */
+    abortController?: AbortController;
+    /** Called when the source signals readiness. */
+    onReady?: () => void;
+    /** Source meta; defaults to `{ routeId: "test" }`. */
+    meta?: SourceMeta;
+}
+/**
+ * Build a {@link Subscription} for driving a source adapter directly in a
+ * unit test, without a running route. Wire-up mirrors the engine: `emit`
+ * forwards to `handler`, `ready` to `onReady`, `complete` aborts the
+ * controller, and `signal` observes it.
+ *
+ * @example
+ * ```typescript
+ * const received: unknown[] = [];
+ * await adapter.subscribe(
+ *   testSubscription({
+ *     context: t.ctx,
+ *     handler: (message) => void received.push(message),
+ *     abortController,
+ *   }),
+ * );
+ * ```
+ */
+declare function testSubscription<T = unknown>(options: TestSubscriptionOptions<T>): Subscription<T>;
+
 /**
  * Load a JSON fixture file and return the parsed value.
  *
@@ -365,18 +489,32 @@ declare function testFn<TIn, TOut>(spec: TestFnSpec<TIn, TOut>, input: unknown,
  */
 declare function fixture<T = unknown>(path: string): T;
 /**
- * Fixture entry must have a `name` field used as the vitest test name.
+ * Fixture entry must have a `name` field used as the test name.
  */
 interface FixtureWithName {
     name: string;
     [key: string]: unknown;
 }
 /**
- * Load a JSON array fixture and run one vitest test per entry. Each entry must have a `name` field (used as the test name).
+ * A test runner's `test` function, as accepted by {@link fixtureEach}.
+ * Both `test` from bun:test and `test` from Vitest satisfy this shape.
+ */
+type FixtureTestFn = (name: string, fn: () => void | Promise<void>) => unknown;
+/**
+ * Load a JSON array fixture and run one test per entry. Each entry must have
+ * a `name` field (used as the test name). Runner-agnostic: pass your runner's
+ * `test` function (bun:test, Vitest, node:test).
  *
  * @param path Path to a JSON file that parses to an array
+ * @param test The runner's `test` function used to register each entry
  * @param run Callback invoked per entry; use for assertions. Receives the fixture entry.
+ *
+ * @example
+ * import { test } from "bun:test";
+ * fixtureEach("./cases.json", test, (entry) => {
+ *   expect(run(entry.input)).toEqual(entry.expected);
+ * });
  */
-declare function fixtureEach<T extends FixtureWithName>(path: string, run: (entry: T) => void | Promise<void>): void;
+declare function fixtureEach<T extends FixtureWithName>(path: string, test: FixtureTestFn, run: (entry: T) => void | Promise<void>): void;
 
-export { type AdapterMock, type FixtureWithName, type MockAdapterBehavior, type PseudoKeyedOptions, type PseudoOptions, type SpyAdapter, type SpyLogger, TestContext, TestContextBuilder, type TestContextOptions, type TestFnHandlerContext, type TestFnOptions, type TestFnSpec, type TestOptions, createNoopSpyLogger, createSpyLogger, fixture, fixtureEach, mockAdapter, pseudo, spy, testContext, testFn };
+export { type AdapterMock, type FixtureTestFn, type FixtureWithName, type MockAdapterBehavior, type PseudoKeyedOptions, type PseudoOptions, type SpyAdapter, type SpyFactory, type SpyFn, type SpyLogger, TestContext, TestContextBuilder, type TestContextOptions, type TestFnHandlerContext, type TestFnOptions, type TestFnSpec, type TestOptions, type TestSubscriptionOptions, createNoopSpyLogger, createSpyFn, createSpyLogger, fixture, fixtureEach, mockAdapter, pseudo, sourceMessage, spy, testContext, testFn, testSubscription };