@routecraft/testing 0.3.0-canary.1

package/README.md

@@ -0,0 +1,71 @@
+# @routecraft/testing
+
+Test utilities for RouteCraft routes. Use with [Vitest](https://vitest.dev) to run route lifecycles and assert on logs and errors.
+
+## Installation
+
+```bash
+npm install @routecraft/testing
+```
+
+or
+
+```bash
+pnpm add -D @routecraft/testing
+```
+
+Install as a **devDependency** and ensure `vitest` (>=4) and `@routecraft/routecraft` are available.
+
+## Quick Start
+
+```typescript
+import { describe, it, expect, afterEach } from "vitest";
+import { testContext, type TestContext } from "@routecraft/testing";
+import { craft, simple, log } from "@routecraft/routecraft";
+
+describe("my route", () => {
+  let t: TestContext;
+
+  afterEach(async () => {
+    if (t) await t.stop();
+  });
+
+  it("runs and logs", async () => {
+    const route = craft()
+      .id("example")
+      .from(simple("hello"))
+      .to(log());
+
+    t = await testContext().routes(route).build();
+    await t.test();
+
+    expect(t.logger.info).toHaveBeenCalled();
+  });
+});
+```
+
+## API
+
+- **`testContext()`** — Returns a builder. Call `.routes(...).build()` to get a `TestContext`.
+- **`TestContext`** — Wrapper around `CraftContext` with:
+  - **`ctx`** — The underlying context.
+  - **`logger`** — A spy logger (Vitest `vi.fn()` methods) for asserting on log calls.
+  - **`errors`** — Collected route errors.
+  - **`test()`** — Runs start → wait for routes ready → drain → stop. Assert after `await t.test()`.
+  - **`stop()`** / **`drain()`** — Lifecycle helpers.
+- **`TestContextOptions`** — Options (e.g. `routesReadyTimeoutMs`).
+- **`SpyLogger`** — Type for the spy logger on `t.logger`.
+
+## Documentation
+
+For testing patterns and examples, see [routecraft.dev](https://routecraft.dev).
+
+## License
+
+Apache-2.0
+
+## Links
+
+- [Documentation](https://routecraft.dev)
+- [GitHub Repository](https://github.com/routecraftjs/routecraft)
+- [Issue Tracker](https://github.com/routecraftjs/routecraft/issues)

package/dist/index.cjs

@@ -0,0 +1,2 @@
+'use strict';var vitest=require('vitest'),routecraft=require('@routecraft/routecraft');var v=200;function L(){let r={info:vitest.vi.fn(),debug:vitest.vi.fn(),warn:vitest.vi.fn(),error:vitest.vi.fn(),trace:vitest.vi.fn(),fatal:vitest.vi.fn(),child:vitest.vi.fn()};return r.child.mockImplementation(()=>r),r}function x(){let r=vitest.vi.fn(),e=vitest.vi.fn(),t={info:r,debug:r,warn:r,error:r,trace:r,fatal:r,child:e};return e.mockImplementation(()=>t),t}var f=class{ctx;logger;errors=[];routesReadyTimeoutMs;restoreLoggerChild;constructor(e,t){this.ctx=e,this.logger=t?.spyLogger??x(),t?.restoreLoggerChild&&(this.restoreLoggerChild=t.restoreLoggerChild),this.routesReadyTimeoutMs=t?.routesReadyTimeoutMs??v,e.on("error",n=>{let i=n.details.error;this.errors.push(routecraft.isRouteCraftError(i)?i:routecraft.error("RC9901",i));});}async test(){let e=this.ctx,t=e.getRoutes().length,n=t===0?Promise.resolve():new Promise((y,l)=>{let p=0,s=false,a=setTimeout(()=>{s||(d(),l(new Error("Timeout waiting for routes to start")));},this.routesReadyTimeoutMs),c=e.on("routeStarted",()=>{s||(p++,p>=t&&(d(),y()));}),h=e.on("error",m=>{s||(d(),l(m.details.error));});function d(){s||(s=true,c(),h(),a!==void 0&&(clearTimeout(a),a=void 0));}}),i=e.start();try{await n,await e.drain();}finally{await e.stop(),await i,this.restoreLoggerChild?.();}}drain(){return this.ctx.drain()}stop(){return this.ctx.stop()}},g=class{builder=new routecraft.ContextBuilder;routesReadyTimeoutMs;routesReadyTimeout(e){return this.routesReadyTimeoutMs=e,this}with(e){return this.builder.with(e),this}on(e,t){return this.builder.on(e,t),this}store(e,t){return this.builder.store(e,t),this}routes(e){return this.builder.routes(e),this}async build(){let e=L(),t=routecraft.logger.child.bind(routecraft.logger);routecraft.logger.child=vitest.vi.fn(()=>e);let n=await this.builder.build(),i={...this.routesReadyTimeoutMs!==void 0?{routesReadyTimeoutMs:this.routesReadyTimeoutMs}:{},spyLogger:e,restoreLoggerChild:()=>{routecraft.logger.child=t;}};return new f(n,i)}};function E(){return new g}exports.TestContext=f;exports.TestContextBuilder=g;exports.testContext=E;//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["DEFAULT_ROUTES_READY_TIMEOUT_MS","createSpyLogger","spy","vi","createNoopSpyLogger","noop","childFn","noopLogger","TestContext","ctx","options","payload","err","isRouteCraftError","rcError","total","allReady","resolve","reject","ready","settled","timeoutId","cleanup","offRouteStarted","offError","started","TestContextBuilder","ContextBuilder","ms","config","event","handler","key","value","routes","spyLogger","originalChild","logger","testContext"],"mappings":"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","file":"index.cjs","sourcesContent":["import { vi } from \"vitest\";\nimport type {\n  CraftContext,\n  CraftConfig,\n  StoreRegistry,\n} from \"@routecraft/routecraft\";\nimport {\n  ContextBuilder,\n  isRouteCraftError,\n  RouteCraftError,\n  error as rcError,\n  logger,\n} from \"@routecraft/routecraft\";\nimport type { EventName, EventHandler } from \"@routecraft/routecraft\";\nimport type { RouteDefinition, RouteBuilder } from \"@routecraft/routecraft\";\n\nconst DEFAULT_ROUTES_READY_TIMEOUT_MS = 200;\n\nfunction createSpyLogger(): SpyLogger {\n  const spy: SpyLogger = {\n    info: vi.fn(),\n    debug: vi.fn(),\n    warn: vi.fn(),\n    error: vi.fn(),\n    trace: vi.fn(),\n    fatal: vi.fn(),\n    child: vi.fn(),\n  };\n  spy.child.mockImplementation(() => spy);\n  return spy;\n}\n\nfunction createNoopSpyLogger(): SpyLogger {\n  const noop = vi.fn();\n  const childFn = vi.fn();\n  const noopLogger: SpyLogger = {\n    info: noop,\n    debug: noop,\n    warn: noop,\n    error: noop,\n    trace: noop,\n    fatal: noop,\n    child: childFn,\n  };\n  childFn.mockImplementation(() => noopLogger);\n  return noopLogger;\n}\n\nexport interface TestContextOptions {\n  /** Timeout in ms for waiting for all routes to emit routeStarted. Default 200. */\n  routesReadyTimeoutMs?: number;\n}\n\n/**\n * Spy logger with vi.fn() methods for assertions (e.g. expect(t.logger.info).toHaveBeenCalledWith(...)).\n */\nexport type SpyLogger = {\n  info: ReturnType<typeof vi.fn>;\n  debug: ReturnType<typeof vi.fn>;\n  warn: ReturnType<typeof vi.fn>;\n  error: ReturnType<typeof vi.fn>;\n  trace: ReturnType<typeof vi.fn>;\n  fatal: ReturnType<typeof vi.fn>;\n  child: ReturnType<typeof vi.fn>;\n};\n\n/**\n * Test-friendly wrapper around CraftContext. Runs the real context but manages\n * lifecycle (start → wait routes ready → drain → stop) and collects errors.\n * t.logger is a spy logger (vi.fn() methods) for asserting on log calls.\n */\nexport class TestContext {\n  readonly ctx: CraftContext;\n  /** Spy logger; e.g. expect(t.logger.info).toHaveBeenCalledWith(...) */\n  readonly logger: SpyLogger;\n  readonly errors: RouteCraftError[] = [];\n  private readonly routesReadyTimeoutMs: number;\n\n  private restoreLoggerChild?: () => void;\n\n  constructor(\n    ctx: CraftContext,\n    options?: TestContextOptions & {\n      spyLogger?: SpyLogger;\n      restoreLoggerChild?: () => void;\n    },\n  ) {\n    this.ctx = ctx;\n    this.logger = options?.spyLogger ?? createNoopSpyLogger();\n    if (options?.restoreLoggerChild)\n      this.restoreLoggerChild = options.restoreLoggerChild;\n    this.routesReadyTimeoutMs =\n      options?.routesReadyTimeoutMs ?? DEFAULT_ROUTES_READY_TIMEOUT_MS;\n    ctx.on(\"error\", (payload) => {\n      const err = payload.details.error;\n      this.errors.push(\n        isRouteCraftError(err)\n          ? (err as RouteCraftError)\n          : rcError(\"RC9901\", err),\n      );\n    });\n  }\n\n  /**\n   * Start context, wait for all routes ready, drain in-flight, then stop.\n   * Assert after this returns (mocks, t.errors, t.ctx.getStore() all valid).\n   */\n  async test(): Promise<void> {\n    const ctx = this.ctx;\n    const total = ctx.getRoutes().length;\n    const allReady =\n      total === 0\n        ? Promise.resolve()\n        : new Promise<void>((resolve, reject) => {\n            let ready = 0;\n            let settled = false;\n            let timeoutId: ReturnType<typeof setTimeout> | undefined =\n              setTimeout(() => {\n                if (settled) return;\n                cleanup();\n                reject(new Error(\"Timeout waiting for routes to start\"));\n              }, this.routesReadyTimeoutMs);\n\n            const offRouteStarted = ctx.on(\"routeStarted\", () => {\n              if (settled) return;\n              ready++;\n              if (ready >= total) {\n                cleanup();\n                resolve();\n              }\n            });\n            const offError = ctx.on(\"error\", (payload) => {\n              if (settled) return;\n              cleanup();\n              reject(payload.details.error);\n            });\n\n            function cleanup(): void {\n              if (settled) return;\n              settled = true;\n              offRouteStarted();\n              offError();\n              if (timeoutId !== undefined) {\n                clearTimeout(timeoutId);\n                timeoutId = undefined;\n              }\n            }\n          });\n    const started = ctx.start();\n    try {\n      await allReady;\n      await ctx.drain();\n    } finally {\n      await ctx.stop();\n      await started;\n      this.restoreLoggerChild?.();\n    }\n  }\n\n  drain(): Promise<void> {\n    return this.ctx.drain();\n  }\n\n  stop(): Promise<void> {\n    return this.ctx.stop();\n  }\n}\n\n/**\n * Builder that returns TestContext instead of CraftContext.\n * Same API as ContextBuilder (routes, on, with, store).\n */\nexport class TestContextBuilder {\n  private builder = new ContextBuilder();\n  private routesReadyTimeoutMs: number | undefined;\n\n  /** Override timeout for waiting for routes to start (ms). Used by tests that assert timeout behavior. */\n  routesReadyTimeout(ms: number): this {\n    this.routesReadyTimeoutMs = ms;\n    return this;\n  }\n\n  with(config: CraftConfig): this {\n    this.builder.with(config);\n    return this;\n  }\n\n  on<K extends EventName>(event: K, handler: EventHandler<K>): this {\n    this.builder.on(event, handler);\n    return this;\n  }\n\n  store<K extends keyof StoreRegistry>(key: K, value: StoreRegistry[K]): this {\n    this.builder.store(key, value);\n    return this;\n  }\n\n  routes(\n    routes:\n      | RouteDefinition[]\n      | RouteBuilder<unknown>[]\n      | RouteDefinition\n      | RouteBuilder<unknown>,\n  ): this {\n    this.builder.routes(routes);\n    return this;\n  }\n\n  async build(): Promise<TestContext> {\n    const spyLogger = createSpyLogger();\n    const originalChild = logger.child.bind(logger);\n    logger.child = vi.fn(\n      () => spyLogger as unknown as ReturnType<typeof logger.child>,\n    ) as typeof logger.child;\n    const ctx = await this.builder.build();\n    const options: TestContextOptions & {\n      spyLogger: SpyLogger;\n      restoreLoggerChild: () => void;\n    } = {\n      ...(this.routesReadyTimeoutMs !== undefined\n        ? { routesReadyTimeoutMs: this.routesReadyTimeoutMs }\n        : {}),\n      spyLogger,\n      restoreLoggerChild: () => {\n        logger.child = originalChild;\n      },\n    };\n    return new TestContext(ctx, options);\n  }\n}\n\n/**\n * Create a test context builder. Use .routes(...).build(), await the result, then await t.test().\n *\n * @example\n * const builder = testContext();\n * const t = await builder.routes(myRoutes).build();\n * await t.test();\n */\nexport function testContext(): TestContextBuilder {\n  return new TestContextBuilder();\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,69 @@
+import { vi } from 'vitest';
+import { CraftContext, RouteCraftError, CraftConfig, EventName, EventHandler, StoreRegistry, RouteDefinition, RouteBuilder } from '@routecraft/routecraft';
+
+interface TestContextOptions {
+    /** Timeout in ms for waiting for all routes to emit routeStarted. Default 200. */
+    routesReadyTimeoutMs?: number;
+}
+/**
+ * Spy logger with vi.fn() methods for assertions (e.g. expect(t.logger.info).toHaveBeenCalledWith(...)).
+ */
+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>;
+};
+/**
+ * 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.
+ */
+declare class TestContext {
+    readonly ctx: CraftContext;
+    /** Spy logger; e.g. expect(t.logger.info).toHaveBeenCalledWith(...) */
+    readonly logger: SpyLogger;
+    readonly errors: RouteCraftError[];
+    private readonly routesReadyTimeoutMs;
+    private restoreLoggerChild?;
+    constructor(ctx: CraftContext, options?: TestContextOptions & {
+        spyLogger?: SpyLogger;
+        restoreLoggerChild?: () => void;
+    });
+    /**
+     * Start context, wait for all routes ready, drain in-flight, then stop.
+     * Assert after this returns (mocks, t.errors, t.ctx.getStore() all valid).
+     */
+    test(): Promise<void>;
+    drain(): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * Builder that returns TestContext instead of CraftContext.
+ * Same API as ContextBuilder (routes, on, with, store).
+ */
+declare class TestContextBuilder {
+    private builder;
+    private routesReadyTimeoutMs;
+    /** Override timeout for waiting for routes to start (ms). Used by tests that assert timeout behavior. */
+    routesReadyTimeout(ms: number): this;
+    with(config: CraftConfig): this;
+    on<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;
+    build(): Promise<TestContext>;
+}
+/**
+ * Create a test context builder. Use .routes(...).build(), await the result, then await t.test().
+ *
+ * @example
+ * const builder = testContext();
+ * const t = await builder.routes(myRoutes).build();
+ * await t.test();
+ */
+declare function testContext(): TestContextBuilder;
+
+export { type SpyLogger, TestContext, TestContextBuilder, type TestContextOptions, testContext };

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+import { vi } from 'vitest';
+import { CraftContext, RouteCraftError, CraftConfig, EventName, EventHandler, StoreRegistry, RouteDefinition, RouteBuilder } from '@routecraft/routecraft';
+
+interface TestContextOptions {
+    /** Timeout in ms for waiting for all routes to emit routeStarted. Default 200. */
+    routesReadyTimeoutMs?: number;
+}
+/**
+ * Spy logger with vi.fn() methods for assertions (e.g. expect(t.logger.info).toHaveBeenCalledWith(...)).
+ */
+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>;
+};
+/**
+ * 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.
+ */
+declare class TestContext {
+    readonly ctx: CraftContext;
+    /** Spy logger; e.g. expect(t.logger.info).toHaveBeenCalledWith(...) */
+    readonly logger: SpyLogger;
+    readonly errors: RouteCraftError[];
+    private readonly routesReadyTimeoutMs;
+    private restoreLoggerChild?;
+    constructor(ctx: CraftContext, options?: TestContextOptions & {
+        spyLogger?: SpyLogger;
+        restoreLoggerChild?: () => void;
+    });
+    /**
+     * Start context, wait for all routes ready, drain in-flight, then stop.
+     * Assert after this returns (mocks, t.errors, t.ctx.getStore() all valid).
+     */
+    test(): Promise<void>;
+    drain(): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * Builder that returns TestContext instead of CraftContext.
+ * Same API as ContextBuilder (routes, on, with, store).
+ */
+declare class TestContextBuilder {
+    private builder;
+    private routesReadyTimeoutMs;
+    /** Override timeout for waiting for routes to start (ms). Used by tests that assert timeout behavior. */
+    routesReadyTimeout(ms: number): this;
+    with(config: CraftConfig): this;
+    on<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;
+    build(): Promise<TestContext>;
+}
+/**
+ * Create a test context builder. Use .routes(...).build(), await the result, then await t.test().
+ *
+ * @example
+ * const builder = testContext();
+ * const t = await builder.routes(myRoutes).build();
+ * await t.test();
+ */
+declare function testContext(): TestContextBuilder;
+
+export { type SpyLogger, TestContext, TestContextBuilder, type TestContextOptions, testContext };

package/dist/index.js

@@ -0,0 +1,2 @@
+import {vi}from'vitest';import {isRouteCraftError,error,ContextBuilder,logger}from'@routecraft/routecraft';var v=200;function L(){let r={info:vi.fn(),debug:vi.fn(),warn:vi.fn(),error:vi.fn(),trace:vi.fn(),fatal:vi.fn(),child:vi.fn()};return r.child.mockImplementation(()=>r),r}function x(){let r=vi.fn(),e=vi.fn(),t={info:r,debug:r,warn:r,error:r,trace:r,fatal:r,child:e};return e.mockImplementation(()=>t),t}var f=class{ctx;logger;errors=[];routesReadyTimeoutMs;restoreLoggerChild;constructor(e,t){this.ctx=e,this.logger=t?.spyLogger??x(),t?.restoreLoggerChild&&(this.restoreLoggerChild=t.restoreLoggerChild),this.routesReadyTimeoutMs=t?.routesReadyTimeoutMs??v,e.on("error",n=>{let i=n.details.error;this.errors.push(isRouteCraftError(i)?i:error("RC9901",i));});}async test(){let e=this.ctx,t=e.getRoutes().length,n=t===0?Promise.resolve():new Promise((y,l)=>{let p=0,s=false,a=setTimeout(()=>{s||(d(),l(new Error("Timeout waiting for routes to start")));},this.routesReadyTimeoutMs),c=e.on("routeStarted",()=>{s||(p++,p>=t&&(d(),y()));}),h=e.on("error",m=>{s||(d(),l(m.details.error));});function d(){s||(s=true,c(),h(),a!==void 0&&(clearTimeout(a),a=void 0));}}),i=e.start();try{await n,await e.drain();}finally{await e.stop(),await i,this.restoreLoggerChild?.();}}drain(){return this.ctx.drain()}stop(){return this.ctx.stop()}},g=class{builder=new ContextBuilder;routesReadyTimeoutMs;routesReadyTimeout(e){return this.routesReadyTimeoutMs=e,this}with(e){return this.builder.with(e),this}on(e,t){return this.builder.on(e,t),this}store(e,t){return this.builder.store(e,t),this}routes(e){return this.builder.routes(e),this}async build(){let e=L(),t=logger.child.bind(logger);logger.child=vi.fn(()=>e);let n=await this.builder.build(),i={...this.routesReadyTimeoutMs!==void 0?{routesReadyTimeoutMs:this.routesReadyTimeoutMs}:{},spyLogger:e,restoreLoggerChild:()=>{logger.child=t;}};return new f(n,i)}};function E(){return new g}export{f as TestContext,g as TestContextBuilder,E as testContext};//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["DEFAULT_ROUTES_READY_TIMEOUT_MS","createSpyLogger","spy","vi","createNoopSpyLogger","noop","childFn","noopLogger","TestContext","ctx","options","payload","err","isRouteCraftError","rcError","total","allReady","resolve","reject","ready","settled","timeoutId","cleanup","offRouteStarted","offError","started","TestContextBuilder","ContextBuilder","ms","config","event","handler","key","value","routes","spyLogger","originalChild","logger","testContext"],"mappings":"2GAgBA,IAAMA,EAAkC,GAAA,CAExC,SAASC,GAA6B,CACpC,IAAMC,CAAAA,CAAiB,CACrB,IAAA,CAAMC,EAAAA,CAAG,IAAG,CACZ,KAAA,CAAOA,GAAG,EAAA,EAAG,CACb,KAAMA,EAAAA,CAAG,EAAA,EAAG,CACZ,KAAA,CAAOA,EAAAA,CAAG,EAAA,GACV,KAAA,CAAOA,EAAAA,CAAG,IAAG,CACb,KAAA,CAAOA,GAAG,EAAA,EAAG,CACb,KAAA,CAAOA,EAAAA,CAAG,EAAA,EACZ,EACA,OAAAD,CAAAA,CAAI,MAAM,kBAAA,CAAmB,IAAMA,CAAG,CAAA,CAC/BA,CACT,CAEA,SAASE,CAAAA,EAAiC,CACxC,IAAMC,CAAAA,CAAOF,EAAAA,CAAG,IAAG,CACbG,CAAAA,CAAUH,GAAG,EAAA,EAAG,CAChBI,CAAAA,CAAwB,CAC5B,IAAA,CAAMF,CAAAA,CACN,MAAOA,CAAAA,CACP,IAAA,CAAMA,EACN,KAAA,CAAOA,CAAAA,CACP,MAAOA,CAAAA,CACP,KAAA,CAAOA,CAAAA,CACP,KAAA,CAAOC,CACT,CAAA,CACA,OAAAA,CAAAA,CAAQ,kBAAA,CAAmB,IAAMC,CAAU,CAAA,CACpCA,CACT,CAyBO,IAAMC,CAAAA,CAAN,KAAkB,CACd,GAAA,CAEA,MAAA,CACA,OAA4B,EAAC,CACrB,qBAET,kBAAA,CAER,WAAA,CACEC,EACAC,CAAAA,CAIA,CACA,IAAA,CAAK,GAAA,CAAMD,CAAAA,CACX,IAAA,CAAK,OAASC,CAAAA,EAAS,SAAA,EAAaN,GAAoB,CACpDM,CAAAA,EAAS,qBACX,IAAA,CAAK,kBAAA,CAAqBA,CAAAA,CAAQ,kBAAA,CAAA,CACpC,IAAA,CAAK,oBAAA,CACHA,GAAS,oBAAA,EAAwBV,CAAAA,CACnCS,EAAI,EAAA,CAAG,OAAA,CAAUE,GAAY,CAC3B,IAAMC,CAAAA,CAAMD,CAAAA,CAAQ,OAAA,CAAQ,KAAA,CAC5B,KAAK,MAAA,CAAO,IAAA,CACVE,iBAAAA,CAAkBD,CAAG,CAAA,CAChBA,CAAAA,CACDE,MAAQ,QAAA,CAAUF,CAAG,CAC3B,EACF,CAAC,EACH,CAMA,MAAM,IAAA,EAAsB,CAC1B,IAAMH,CAAAA,CAAM,KAAK,GAAA,CACXM,CAAAA,CAAQN,CAAAA,CAAI,SAAA,EAAU,CAAE,MAAA,CACxBO,EACJD,CAAAA,GAAU,CAAA,CACN,QAAQ,OAAA,EAAQ,CAChB,IAAI,OAAA,CAAc,CAACE,CAAAA,CAASC,CAAAA,GAAW,CACrC,IAAIC,EAAQ,CAAA,CACRC,CAAAA,CAAU,MACVC,CAAAA,CACF,UAAA,CAAW,IAAM,CACXD,CAAAA,GACJE,CAAAA,EAAQ,CACRJ,CAAAA,CAAO,IAAI,MAAM,qCAAqC,CAAC,CAAA,EACzD,CAAA,CAAG,IAAA,CAAK,oBAAoB,EAExBK,CAAAA,CAAkBd,CAAAA,CAAI,EAAA,CAAG,cAAA,CAAgB,IAAM,CAC/CW,IACJD,CAAAA,EAAAA,CACIA,CAAAA,EAASJ,IACXO,CAAAA,EAAQ,CACRL,GAAQ,CAAA,EAEZ,CAAC,CAAA,CACKO,CAAAA,CAAWf,CAAAA,CAAI,EAAA,CAAG,QAAUE,CAAAA,EAAY,CACxCS,IACJE,CAAAA,EAAQ,CACRJ,EAAOP,CAAAA,CAAQ,OAAA,CAAQ,KAAK,CAAA,EAC9B,CAAC,CAAA,CAED,SAASW,CAAAA,EAAgB,CACnBF,IACJA,CAAAA,CAAU,IAAA,CACVG,GAAgB,CAChBC,CAAAA,EAAS,CACLH,CAAAA,GAAc,MAAA,GAChB,YAAA,CAAaA,CAAS,CAAA,CACtBA,CAAAA,CAAY,MAAA,CAAA,EAEhB,CACF,CAAC,CAAA,CACDI,EAAUhB,CAAAA,CAAI,KAAA,EAAM,CAC1B,GAAI,CACF,MAAMO,EACN,MAAMP,CAAAA,CAAI,QACZ,CAAA,OAAE,CACA,MAAMA,CAAAA,CAAI,IAAA,EAAK,CACf,MAAMgB,CAAAA,CACN,KAAK,kBAAA,KACP,CACF,CAEA,KAAA,EAAuB,CACrB,OAAO,IAAA,CAAK,GAAA,CAAI,KAAA,EAClB,CAEA,MAAsB,CACpB,OAAO,KAAK,GAAA,CAAI,IAAA,EAClB,CACF,CAAA,CAMaC,CAAAA,CAAN,KAAyB,CACtB,OAAA,CAAU,IAAIC,cAAAA,CACd,oBAAA,CAGR,kBAAA,CAAmBC,CAAAA,CAAkB,CACnC,OAAA,IAAA,CAAK,qBAAuBA,CAAAA,CACrB,IACT,CAEA,IAAA,CAAKC,CAAAA,CAA2B,CAC9B,YAAK,OAAA,CAAQ,IAAA,CAAKA,CAAM,CAAA,CACjB,IACT,CAEA,EAAA,CAAwBC,CAAAA,CAAUC,CAAAA,CAAgC,CAChE,OAAA,IAAA,CAAK,OAAA,CAAQ,GAAGD,CAAAA,CAAOC,CAAO,EACvB,IACT,CAEA,MAAqCC,CAAAA,CAAQC,CAAAA,CAA+B,CAC1E,OAAA,IAAA,CAAK,OAAA,CAAQ,KAAA,CAAMD,EAAKC,CAAK,CAAA,CACtB,IACT,CAEA,MAAA,CACEC,EAKM,CACN,OAAA,IAAA,CAAK,OAAA,CAAQ,MAAA,CAAOA,CAAM,CAAA,CACnB,IACT,CAEA,MAAM,KAAA,EAA8B,CAClC,IAAMC,CAAAA,CAAYlC,GAAgB,CAC5BmC,CAAAA,CAAgBC,MAAAA,CAAO,KAAA,CAAM,IAAA,CAAKA,MAAM,EAC9CA,MAAAA,CAAO,KAAA,CAAQlC,GAAG,EAAA,CAChB,IAAMgC,CACR,CAAA,CACA,IAAM1B,CAAAA,CAAM,MAAM,IAAA,CAAK,OAAA,CAAQ,OAAM,CAC/BC,CAAAA,CAGF,CACF,GAAI,IAAA,CAAK,uBAAyB,MAAA,CAC9B,CAAE,oBAAA,CAAsB,IAAA,CAAK,oBAAqB,CAAA,CAClD,EAAC,CACL,SAAA,CAAAyB,EACA,kBAAA,CAAoB,IAAM,CACxBE,MAAAA,CAAO,KAAA,CAAQD,EACjB,CACF,CAAA,CACA,OAAO,IAAI5B,CAAAA,CAAYC,CAAAA,CAAKC,CAAO,CACrC,CACF,EAUO,SAAS4B,CAAAA,EAAkC,CAChD,OAAO,IAAIZ,CACb","file":"index.js","sourcesContent":["import { vi } from \"vitest\";\nimport type {\n  CraftContext,\n  CraftConfig,\n  StoreRegistry,\n} from \"@routecraft/routecraft\";\nimport {\n  ContextBuilder,\n  isRouteCraftError,\n  RouteCraftError,\n  error as rcError,\n  logger,\n} from \"@routecraft/routecraft\";\nimport type { EventName, EventHandler } from \"@routecraft/routecraft\";\nimport type { RouteDefinition, RouteBuilder } from \"@routecraft/routecraft\";\n\nconst DEFAULT_ROUTES_READY_TIMEOUT_MS = 200;\n\nfunction createSpyLogger(): SpyLogger {\n  const spy: SpyLogger = {\n    info: vi.fn(),\n    debug: vi.fn(),\n    warn: vi.fn(),\n    error: vi.fn(),\n    trace: vi.fn(),\n    fatal: vi.fn(),\n    child: vi.fn(),\n  };\n  spy.child.mockImplementation(() => spy);\n  return spy;\n}\n\nfunction createNoopSpyLogger(): SpyLogger {\n  const noop = vi.fn();\n  const childFn = vi.fn();\n  const noopLogger: SpyLogger = {\n    info: noop,\n    debug: noop,\n    warn: noop,\n    error: noop,\n    trace: noop,\n    fatal: noop,\n    child: childFn,\n  };\n  childFn.mockImplementation(() => noopLogger);\n  return noopLogger;\n}\n\nexport interface TestContextOptions {\n  /** Timeout in ms for waiting for all routes to emit routeStarted. Default 200. */\n  routesReadyTimeoutMs?: number;\n}\n\n/**\n * Spy logger with vi.fn() methods for assertions (e.g. expect(t.logger.info).toHaveBeenCalledWith(...)).\n */\nexport type SpyLogger = {\n  info: ReturnType<typeof vi.fn>;\n  debug: ReturnType<typeof vi.fn>;\n  warn: ReturnType<typeof vi.fn>;\n  error: ReturnType<typeof vi.fn>;\n  trace: ReturnType<typeof vi.fn>;\n  fatal: ReturnType<typeof vi.fn>;\n  child: ReturnType<typeof vi.fn>;\n};\n\n/**\n * Test-friendly wrapper around CraftContext. Runs the real context but manages\n * lifecycle (start → wait routes ready → drain → stop) and collects errors.\n * t.logger is a spy logger (vi.fn() methods) for asserting on log calls.\n */\nexport class TestContext {\n  readonly ctx: CraftContext;\n  /** Spy logger; e.g. expect(t.logger.info).toHaveBeenCalledWith(...) */\n  readonly logger: SpyLogger;\n  readonly errors: RouteCraftError[] = [];\n  private readonly routesReadyTimeoutMs: number;\n\n  private restoreLoggerChild?: () => void;\n\n  constructor(\n    ctx: CraftContext,\n    options?: TestContextOptions & {\n      spyLogger?: SpyLogger;\n      restoreLoggerChild?: () => void;\n    },\n  ) {\n    this.ctx = ctx;\n    this.logger = options?.spyLogger ?? createNoopSpyLogger();\n    if (options?.restoreLoggerChild)\n      this.restoreLoggerChild = options.restoreLoggerChild;\n    this.routesReadyTimeoutMs =\n      options?.routesReadyTimeoutMs ?? DEFAULT_ROUTES_READY_TIMEOUT_MS;\n    ctx.on(\"error\", (payload) => {\n      const err = payload.details.error;\n      this.errors.push(\n        isRouteCraftError(err)\n          ? (err as RouteCraftError)\n          : rcError(\"RC9901\", err),\n      );\n    });\n  }\n\n  /**\n   * Start context, wait for all routes ready, drain in-flight, then stop.\n   * Assert after this returns (mocks, t.errors, t.ctx.getStore() all valid).\n   */\n  async test(): Promise<void> {\n    const ctx = this.ctx;\n    const total = ctx.getRoutes().length;\n    const allReady =\n      total === 0\n        ? Promise.resolve()\n        : new Promise<void>((resolve, reject) => {\n            let ready = 0;\n            let settled = false;\n            let timeoutId: ReturnType<typeof setTimeout> | undefined =\n              setTimeout(() => {\n                if (settled) return;\n                cleanup();\n                reject(new Error(\"Timeout waiting for routes to start\"));\n              }, this.routesReadyTimeoutMs);\n\n            const offRouteStarted = ctx.on(\"routeStarted\", () => {\n              if (settled) return;\n              ready++;\n              if (ready >= total) {\n                cleanup();\n                resolve();\n              }\n            });\n            const offError = ctx.on(\"error\", (payload) => {\n              if (settled) return;\n              cleanup();\n              reject(payload.details.error);\n            });\n\n            function cleanup(): void {\n              if (settled) return;\n              settled = true;\n              offRouteStarted();\n              offError();\n              if (timeoutId !== undefined) {\n                clearTimeout(timeoutId);\n                timeoutId = undefined;\n              }\n            }\n          });\n    const started = ctx.start();\n    try {\n      await allReady;\n      await ctx.drain();\n    } finally {\n      await ctx.stop();\n      await started;\n      this.restoreLoggerChild?.();\n    }\n  }\n\n  drain(): Promise<void> {\n    return this.ctx.drain();\n  }\n\n  stop(): Promise<void> {\n    return this.ctx.stop();\n  }\n}\n\n/**\n * Builder that returns TestContext instead of CraftContext.\n * Same API as ContextBuilder (routes, on, with, store).\n */\nexport class TestContextBuilder {\n  private builder = new ContextBuilder();\n  private routesReadyTimeoutMs: number | undefined;\n\n  /** Override timeout for waiting for routes to start (ms). Used by tests that assert timeout behavior. */\n  routesReadyTimeout(ms: number): this {\n    this.routesReadyTimeoutMs = ms;\n    return this;\n  }\n\n  with(config: CraftConfig): this {\n    this.builder.with(config);\n    return this;\n  }\n\n  on<K extends EventName>(event: K, handler: EventHandler<K>): this {\n    this.builder.on(event, handler);\n    return this;\n  }\n\n  store<K extends keyof StoreRegistry>(key: K, value: StoreRegistry[K]): this {\n    this.builder.store(key, value);\n    return this;\n  }\n\n  routes(\n    routes:\n      | RouteDefinition[]\n      | RouteBuilder<unknown>[]\n      | RouteDefinition\n      | RouteBuilder<unknown>,\n  ): this {\n    this.builder.routes(routes);\n    return this;\n  }\n\n  async build(): Promise<TestContext> {\n    const spyLogger = createSpyLogger();\n    const originalChild = logger.child.bind(logger);\n    logger.child = vi.fn(\n      () => spyLogger as unknown as ReturnType<typeof logger.child>,\n    ) as typeof logger.child;\n    const ctx = await this.builder.build();\n    const options: TestContextOptions & {\n      spyLogger: SpyLogger;\n      restoreLoggerChild: () => void;\n    } = {\n      ...(this.routesReadyTimeoutMs !== undefined\n        ? { routesReadyTimeoutMs: this.routesReadyTimeoutMs }\n        : {}),\n      spyLogger,\n      restoreLoggerChild: () => {\n        logger.child = originalChild;\n      },\n    };\n    return new TestContext(ctx, options);\n  }\n}\n\n/**\n * Create a test context builder. Use .routes(...).build(), await the result, then await t.test().\n *\n * @example\n * const builder = testContext();\n * const t = await builder.routes(myRoutes).build();\n * await t.test();\n */\nexport function testContext(): TestContextBuilder {\n  return new TestContextBuilder();\n}\n"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@routecraft/testing",
+  "version": "0.3.0-canary.1",
+  "description": "Test utilities for RouteCraft routes",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "@routecraft/routecraft": "^0.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@routecraft/routecraft": "*",
+    "vitest": ">=4"
+  },
+  "keywords": [
+    "routecraft",
+    "testing",
+    "vitest",
+    "test-context"
+  ],
+  "author": "routecraftjs",
+  "license": "Apache-2.0",
+  "homepage": "https://routecraft.dev",
+  "bugs": "https://github.com/routecraftjs/routecraft/issues",
+  "repository": "https://github.com/routecraftjs/routecraft",
+  "publishConfig": {
+    "access": "public"
+  }
+}