@nwire/test-kit 0.10.0 → 0.11.0

package/dist/bdd.d.ts

@@ -1,43 +1,125 @@
 /**
- * BDD via `@amiceli/vitest-cucumber` — thin wrapper that hooks the
- * generated steps into our harness lifecycle.
+ * BDD support — thin re-exports of `@amiceli/vitest-cucumber` so test-kit
+ * users have a single dependency for harness + BDD primitives, plus a
+ * `bddHarness({ buildApp })` factory that handles the Background-runs-
+ * before-BeforeEachScenario lifecycle quirk so step files don't have to.
  *
- * Usage (in a *.test.ts file):
+ *   import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+ *   import { bddHarness } from "@nwire/test-kit";
  *
- *   import { feature } from "@nwire/test-kit";
- *   import { harness } from "@nwire/test-kit";
- *   import submissionsApp from "./submissions.app";
+ *   describeFeature(feature, ({ Scenario, Background, AfterEachScenario }) => {
+ *     const ctx = bddHarness({ buildApp });
  *
- *   feature("./avi-submits.feature", async (ctx) => {
- *     ctx.background(async () => { ctx.harness = await harness({ app: submissionsApp }); });
- *     ctx.afterScenario(async () => ctx.harness?.stop());
+ *     AfterEachScenario(async () => { await ctx.reset(); });
  *
- *     ctx.when("Avi submits {answer}", async (answer) => {
- *       await ctx.harness.dispatch(submitAnswer, { studentId: "avi", answer });
+ *     Background(({ Given, And }) => {
+ *       Given("the platform is up", async () => { await ctx.boot(); });
+ *       And("a seed exists", async () => {
+ *         await ctx.boot();
+ *         await ctx.scoped().dispatch(...);
+ *       });
  *     });
- *     ctx.then("event {name} should fire", async (name) => {
- *       await ctx.harness.idle();
- *       expect(ctx.harness.telemetry.count("event.published", (e) => e.event.eventName === name)).toBeGreaterThan(0);
+ *
+ *     Scenario("does the thing", ({ When, Then }) => {
+ *       When("we dispatch", async () => { await ctx.scoped().dispatch(...); });
+ *       Then("we see the result", async () => {
+ *         expect(ctx.harness.telemetry.count(...)).toBeGreaterThan(0);
+ *       });
  *     });
  *   });
  *
- * The wrapper is intentionally tiny — we pass through to the real Gherkin
- * runner. `@amiceli/vitest-cucumber` is a peerDependency.
+ * Lifecycle quirk: in @amiceli/vitest-cucumber@4, `BeforeEachScenario`
+ * fires in the scenario's `beforeAll`, but **Background** steps live in
+ * a separate describe that runs BEFORE the scenario's beforeAll. The
+ * lazy-init pattern (call `ctx.boot()` at the head of every step) keeps
+ * Background + Scenario steps wired to the SAME fresh harness within a
+ * scenario, and `AfterEachScenario(() => ctx.reset())` releases it
+ * between scenarios.
+ *
+ * Step-text reuse: vitest-cucumber binds registrations to feature steps
+ * by the registration text. If a feature uses the same step pattern
+ * twice in one scope (Background or Scenario), each occurrence still
+ * binds to the FIRST matching registration — the second occurrence
+ * reports as "missing". Give each occurrence unique wording in the
+ * .feature file.
+ *
+ * `@amiceli/vitest-cucumber` is a peer dependency — install it in the
+ * consuming project: `pnpm add -D @amiceli/vitest-cucumber`.
+ */
+import type { App } from "@nwire/app";
+import { type Harness } from "./harness.js";
+import { type ScopedHarness, type UserLike } from "./harness-extensions.js";
+/**
+ * Re-export of vitest-cucumber's primary API surface. The package is a
+ * peer dep — we resolve it lazily so test-kit consumers that don't run
+ * BDD tests aren't forced to install it.
+ */
+export declare function loadBddRunner(): Promise<typeof import("@amiceli/vitest-cucumber")>;
+/**
+ * Marker type — `BddContext` was a planning placeholder in 0.10. The
+ * real API is `describeFeature` / `loadFeature` from
+ * `@amiceli/vitest-cucumber`, used directly in step files. This export
+ * is kept for back-compat of the test-kit barrel; consumers should
+ * import `describeFeature` / `loadFeature` directly from
+ * `@amiceli/vitest-cucumber`.
  */
-import type { Harness } from "./harness.js";
 export interface BddContext {
-    /** Filled in by the user's background step. */
-    harness?: Harness;
-    background(fn: () => Promise<void> | void): void;
-    afterScenario(fn: () => Promise<void> | void): void;
-    given(pattern: string, fn: (...args: unknown[]) => Promise<void> | void): void;
-    when(pattern: string, fn: (...args: unknown[]) => Promise<void> | void): void;
-    then(pattern: string, fn: (...args: unknown[]) => Promise<void> | void): void;
-    and(pattern: string, fn: (...args: unknown[]) => Promise<void> | void): void;
+    readonly harness?: Harness;
+}
+/**
+ * Convenience pass-through — equivalent to importing `loadFeature`
+ * directly from `@amiceli/vitest-cucumber` but routed through the
+ * peer-dep loader so the error message is friendlier if the package
+ * is missing.
+ */
+export declare function feature(path: string): Promise<Awaited<ReturnType<typeof import("@amiceli/vitest-cucumber").loadFeature>>>;
+export interface BddHarnessOptions {
+    readonly buildApp: () => App;
+    /** Default user pinned via `asUser` when no scenario overrides it. */
+    readonly defaultUser?: UserLike;
+    /** Tenant prefix used to namespace each scenario's state. Default "t". */
+    readonly tenantPrefix?: string;
+}
+export interface BddHarnessCtx {
+    /** Current harness, or `null` before the first `boot()` in a scenario. */
+    readonly harness: Harness | null;
+    /** The pinned user for `scoped()`. Step files may swap it per scenario. */
+    user: UserLike;
+    /** Tenant string assigned to the current scenario. */
+    readonly tenant: string;
+    /**
+     * Boot the harness if it isn't already. Call at the head of every
+     * Background and Scenario step so Background's first invocation wins
+     * regardless of vitest-cucumber's hook ordering.
+     */
+    boot(): Promise<Harness>;
+    /**
+     * Scoped dispatcher pinned to `user` + `tenant`. Call after `boot()`.
+     * Throws if invoked before any `boot()` ran in the current scenario.
+     */
+    scoped(overrides?: Partial<UserLike>): ScopedHarness;
+    /**
+     * Tear down the current harness. Call from `AfterEachScenario` so the
+     * next scenario starts fresh.
+     */
+    reset(): Promise<void>;
 }
 /**
- * Boot a feature file with steps. Resolves the `@amiceli/vitest-cucumber`
- * runner lazily so test-kit consumers without BDD don't have to install the
- * peer dep.
+ * Construct a BDD lifecycle helper for a feature.
+ *
+ *   const ctx = bddHarness({ buildApp });
+ *
+ *   AfterEachScenario(() => ctx.reset());
+ *
+ *   Background(({ Given }) => {
+ *     Given("the platform is up", () => ctx.boot());
+ *   });
+ *
+ *   Scenario("does X", ({ When, Then }) => {
+ *     When("dispatch happens", async () => {
+ *       await ctx.boot();
+ *       await ctx.scoped().dispatch(...);
+ *     });
+ *   });
  */
-export declare function feature(featurePath: string, define: (ctx: BddContext) => void | Promise<void>): Promise<void>;
+export declare function bddHarness(options: BddHarnessOptions): BddHarnessCtx;

package/dist/bdd.js

@@ -1,66 +1,134 @@
 /**
- * BDD via `@amiceli/vitest-cucumber` — thin wrapper that hooks the
- * generated steps into our harness lifecycle.
+ * BDD support — thin re-exports of `@amiceli/vitest-cucumber` so test-kit
+ * users have a single dependency for harness + BDD primitives, plus a
+ * `bddHarness({ buildApp })` factory that handles the Background-runs-
+ * before-BeforeEachScenario lifecycle quirk so step files don't have to.
  *
- * Usage (in a *.test.ts file):
+ *   import { describeFeature, loadFeature } from "@amiceli/vitest-cucumber";
+ *   import { bddHarness } from "@nwire/test-kit";
  *
- *   import { feature } from "@nwire/test-kit";
- *   import { harness } from "@nwire/test-kit";
- *   import submissionsApp from "./submissions.app";
+ *   describeFeature(feature, ({ Scenario, Background, AfterEachScenario }) => {
+ *     const ctx = bddHarness({ buildApp });
  *
- *   feature("./avi-submits.feature", async (ctx) => {
- *     ctx.background(async () => { ctx.harness = await harness({ app: submissionsApp }); });
- *     ctx.afterScenario(async () => ctx.harness?.stop());
+ *     AfterEachScenario(async () => { await ctx.reset(); });
  *
- *     ctx.when("Avi submits {answer}", async (answer) => {
- *       await ctx.harness.dispatch(submitAnswer, { studentId: "avi", answer });
+ *     Background(({ Given, And }) => {
+ *       Given("the platform is up", async () => { await ctx.boot(); });
+ *       And("a seed exists", async () => {
+ *         await ctx.boot();
+ *         await ctx.scoped().dispatch(...);
+ *       });
  *     });
- *     ctx.then("event {name} should fire", async (name) => {
- *       await ctx.harness.idle();
- *       expect(ctx.harness.telemetry.count("event.published", (e) => e.event.eventName === name)).toBeGreaterThan(0);
+ *
+ *     Scenario("does the thing", ({ When, Then }) => {
+ *       When("we dispatch", async () => { await ctx.scoped().dispatch(...); });
+ *       Then("we see the result", async () => {
+ *         expect(ctx.harness.telemetry.count(...)).toBeGreaterThan(0);
+ *       });
  *     });
  *   });
  *
- * The wrapper is intentionally tiny — we pass through to the real Gherkin
- * runner. `@amiceli/vitest-cucumber` is a peerDependency.
+ * Lifecycle quirk: in @amiceli/vitest-cucumber@4, `BeforeEachScenario`
+ * fires in the scenario's `beforeAll`, but **Background** steps live in
+ * a separate describe that runs BEFORE the scenario's beforeAll. The
+ * lazy-init pattern (call `ctx.boot()` at the head of every step) keeps
+ * Background + Scenario steps wired to the SAME fresh harness within a
+ * scenario, and `AfterEachScenario(() => ctx.reset())` releases it
+ * between scenarios.
+ *
+ * Step-text reuse: vitest-cucumber binds registrations to feature steps
+ * by the registration text. If a feature uses the same step pattern
+ * twice in one scope (Background or Scenario), each occurrence still
+ * binds to the FIRST matching registration — the second occurrence
+ * reports as "missing". Give each occurrence unique wording in the
+ * .feature file.
+ *
+ * `@amiceli/vitest-cucumber` is a peer dependency — install it in the
+ * consuming project: `pnpm add -D @amiceli/vitest-cucumber`.
  */
+import { harness } from "./harness.js";
+import { asUser } from "./harness-extensions.js";
 /**
- * Boot a feature file with steps. Resolves the `@amiceli/vitest-cucumber`
- * runner lazily so test-kit consumers without BDD don't have to install the
- * peer dep.
+ * Re-export of vitest-cucumber's primary API surface. The package is a
+ * peer dep — we resolve it lazily so test-kit consumers that don't run
+ * BDD tests aren't forced to install it.
  */
-export async function feature(featurePath, define) {
-    let cucumber;
+export async function loadBddRunner() {
     try {
-        cucumber = await import("@amiceli/vitest-cucumber");
+        return await import("@amiceli/vitest-cucumber");
     }
     catch {
-        throw new Error("@nwire/test-kit/bdd requires '@amiceli/vitest-cucumber' as a peer dependency. " +
+        throw new Error("@nwire/test-kit BDD helpers require '@amiceli/vitest-cucumber' as a peer dependency. " +
             "Install it: pnpm add -D @amiceli/vitest-cucumber");
     }
-    // Adapter — the package's exact API surface differs slightly across
-    // versions, so we resolve loosely and route step kinds through.
-    const adapter = cucumber;
-    if (!adapter.loadFeature || !adapter.describeFeature) {
-        throw new Error("@amiceli/vitest-cucumber: unexpected API surface. " +
-            "Pin to a version supported by @nwire/test-kit, or drop down to using the package directly.");
-    }
-    // For v1 of this wrapper we just hand the user a thin facade. Users can
-    // also import @amiceli/vitest-cucumber directly for full control.
+}
+/**
+ * Convenience pass-through — equivalent to importing `loadFeature`
+ * directly from `@amiceli/vitest-cucumber` but routed through the
+ * peer-dep loader so the error message is friendlier if the package
+ * is missing.
+ */
+export async function feature(path) {
+    const cucumber = await loadBddRunner();
+    return cucumber.loadFeature(path);
+}
+/**
+ * Construct a BDD lifecycle helper for a feature.
+ *
+ *   const ctx = bddHarness({ buildApp });
+ *
+ *   AfterEachScenario(() => ctx.reset());
+ *
+ *   Background(({ Given }) => {
+ *     Given("the platform is up", () => ctx.boot());
+ *   });
+ *
+ *   Scenario("does X", ({ When, Then }) => {
+ *     When("dispatch happens", async () => {
+ *       await ctx.boot();
+ *       await ctx.scoped().dispatch(...);
+ *     });
+ *   });
+ */
+export function bddHarness(options) {
+    let current = null;
+    let scenarioCounter = 0;
+    let tenant = `${options.tenantPrefix ?? "t"}-0`;
+    let user = options.defaultUser ?? { id: "bdd", tenant };
     const ctx = {
-        harness: undefined,
-        background: () => { },
-        afterScenario: () => { },
-        given: () => { },
-        when: () => { },
-        then: () => { },
-        and: () => { },
+        get harness() {
+            return current;
+        },
+        get user() {
+            return user;
+        },
+        set user(next) {
+            user = next;
+        },
+        get tenant() {
+            return tenant;
+        },
+        async boot() {
+            if (current)
+                return current;
+            const app = options.buildApp();
+            current = await harness({ app });
+            tenant = `${options.tenantPrefix ?? "t"}-${++scenarioCounter}`;
+            user = options.defaultUser ? { ...options.defaultUser, tenant } : { id: "bdd", tenant };
+            return current;
+        },
+        scoped(overrides) {
+            if (!current) {
+                throw new Error("bddHarness.scoped: boot the harness first via ctx.boot() before scoped() runs.");
+            }
+            return asUser(current, { ...user, ...overrides, tenant });
+        },
+        async reset() {
+            if (current) {
+                await current.stop();
+                current = null;
+            }
+        },
     };
-    await define(ctx);
-    // The complete wiring is left as a follow-up: each step pattern needs to
-    // register with the cucumber adapter's per-version API. Today this
-    // function validates the user's intent and surfaces a helpful error if
-    // the BDD dependency is missing — full step-pattern wiring lands in a
-    // follow-up turn when we exercise a real .feature file against the
-    // RealWorld migration.
+    return ctx;
 }

package/dist/harness-extensions.d.ts

@@ -18,7 +18,7 @@
  * They live in a separate file so the in-memory `harness` core stays small
  * and the optional deps (`@nwire/auth`, `@nwire/rbac`, `koa`) stay opt-in.
  */
-import type { ActionDefinition } from "@nwire/forge";
+import { type ActionDefinition } from "@nwire/forge";
 import type { ZodTypeAny } from "@nwire/messages";
 import type { z } from "zod";
 import type { Harness } from "./harness.js";

package/dist/harness-extensions.js

@@ -19,6 +19,7 @@
  * and the optional deps (`@nwire/auth`, `@nwire/rbac`, `koa`) stay opt-in.
  */
 import supertest from "supertest";
+import { forgeDispatcher } from "@nwire/forge";
 /**
  * Return a thin proxy that pins `envelope.user` (and `envelope.userId`,
  * `envelope.tenant` derived from the user) on every dispatch/query.
@@ -32,11 +33,11 @@ export function asUser(harness, user) {
     // `user` too, which is on MessageEnvelope but not on the public dispatch
     // overload. Going through runtime.dispatch with a hand-seeded envelope
     // keeps the type contract honest without widening the public Harness API.
-    const app = harness.app;
+    const dispatcher = forgeDispatcher(harness.app);
     return {
         async dispatch(action, input, envelope) {
             if (!user)
-                return app.dispatch(action, input);
+                return dispatcher.dispatch(action, input);
             const { seedEnvelope } = await import("@nwire/envelope");
             const seeded = seedEnvelope({
                 tenant: envelope?.tenant ?? user.tenant,
@@ -44,10 +45,10 @@ export function asUser(harness, user) {
                 user,
                 correlationId: envelope?.correlationId,
             });
-            return app.dispatch(action, input, seeded);
+            return dispatcher.dispatch(action, input, seeded);
         },
         async query(queryDef, input, tenant) {
-            return app.query(queryDef.name, input, tenant ?? user?.tenant ?? "");
+            return dispatcher.query(queryDef.name, input, tenant ?? user?.tenant ?? "");
         },
     };
 }

package/dist/harness.d.ts

@@ -1,23 +1,25 @@
 /**
- * `harness(app)` — wrap an already-constructed `ForgeApp` with a light test
- * handle: dispatch helpers, idle-wait, and a buffered telemetry probe.
+ * `harness(app)` — wrap an already-constructed App with a light test handle:
+ * dispatch helpers, idle-wait, and a buffered telemetry probe.
  *
- *   const app = createForgeApp({ name: "submissions", handlers, actors })
- *   const h = await harness({ app })
- *   await h.dispatch(submitAnswer, { … })
- *   await h.idle()
- *   expect(h.telemetry.count("event.published")).toBeGreaterThan(0)
- *   await h.stop()
+ *   const app = createApp({ appName: "submissions",
+ *     plugins: [createForgePlugin({ handlers, actors })] });
+ *   const h = await harness({ app });
+ *   await h.dispatch(submitAnswer, { … });
+ *   await h.idle();
+ *   expect(h.telemetry.count("event.published")).toBeGreaterThan(0);
+ *   await h.stop();
  */
-import type { ActionDefinition, ForgeApp } from "@nwire/forge";
+import type { App } from "@nwire/app";
+import type { ActionDefinition } from "@nwire/forge";
 import type { z } from "zod";
 import type { ZodTypeAny } from "@nwire/messages";
 import { TelemetryProbe } from "./telemetry-probe.js";
 export interface HarnessOptions {
-    readonly app: ForgeApp;
+    readonly app: App;
 }
 export interface Harness {
-    readonly app: ForgeApp;
+    readonly app: App;
     readonly telemetry: TelemetryProbe;
     dispatch<TSchema extends ZodTypeAny>(action: ActionDefinition<TSchema>, input: z.input<TSchema>, envelope?: {
         tenant?: string;

package/dist/harness.js

@@ -1,20 +1,23 @@
 /**
- * `harness(app)` — wrap an already-constructed `ForgeApp` with a light test
- * handle: dispatch helpers, idle-wait, and a buffered telemetry probe.
+ * `harness(app)` — wrap an already-constructed App with a light test handle:
+ * dispatch helpers, idle-wait, and a buffered telemetry probe.
  *
- *   const app = createForgeApp({ name: "submissions", handlers, actors })
- *   const h = await harness({ app })
- *   await h.dispatch(submitAnswer, { … })
- *   await h.idle()
- *   expect(h.telemetry.count("event.published")).toBeGreaterThan(0)
- *   await h.stop()
+ *   const app = createApp({ appName: "submissions",
+ *     plugins: [createForgePlugin({ handlers, actors })] });
+ *   const h = await harness({ app });
+ *   await h.dispatch(submitAnswer, { … });
+ *   await h.idle();
+ *   expect(h.telemetry.count("event.published")).toBeGreaterThan(0);
+ *   await h.stop();
  */
+import { forgeDispatcher } from "@nwire/forge";
 import { TelemetryProbe } from "./telemetry-probe.js";
 export async function harness(options) {
     const app = options.app;
     const probe = new TelemetryProbe();
     const unsubscribe = app.runtime.onTelemetry((rec) => probe.record(rec));
     await app.start();
+    const dispatcher = forgeDispatcher(app);
     let pending = 0;
     let lastRecordAt = Date.now();
     app.runtime.onTelemetry(() => {
@@ -33,16 +36,16 @@ export async function harness(options) {
                         userId: envelope.userId,
                         correlationId: envelope.correlationId,
                     });
-                    return await app.dispatch(action, input, seeded);
+                    return await dispatcher.dispatch(action, input, seeded);
                 }
-                return await app.dispatch(action, input);
+                return await dispatcher.dispatch(action, input);
             }
             finally {
                 pending--;
             }
         },
         async query(queryDef, input, tenant = "") {
-            return app.query(queryDef.name, input, tenant);
+            return dispatcher.query(queryDef.name, input, tenant);
         },
         async idle(graceMs = 25, timeoutMs = 5000) {
             const deadline = Date.now() + timeoutMs;

package/dist/test-kit.d.ts

@@ -20,6 +20,6 @@ export { asUser, simulateRequest, checkPolicy, onLog, type UserLike, type Scoped
 export { TelemetryProbe, type TelemetryFilter } from "./telemetry-probe.js";
 export { dockerCompose, PRESETS as DOCKER_COMPOSE_PRESETS, type ComposeStack, type ComposePreset, } from "./docker-compose.js";
 export { isReachable } from "./is-reachable.js";
-export { feature, type BddContext } from "./bdd.js";
+export { feature, loadBddRunner, bddHarness, type BddContext, type BddHarnessOptions, type BddHarnessCtx, } from "./bdd.js";
 export { factory, sequence, type Factory, type SequenceCounter } from "./zod-fixture-factory.js";
 export { createTestApp, bootTestApp, type BootedTestApp } from "./supertest-app-helper.js";

package/dist/test-kit.js

@@ -20,7 +20,7 @@ export { asUser, simulateRequest, checkPolicy, onLog, } from "./harness-extensio
 export { TelemetryProbe } from "./telemetry-probe.js";
 export { dockerCompose, PRESETS as DOCKER_COMPOSE_PRESETS, } from "./docker-compose.js";
 export { isReachable } from "./is-reachable.js";
-export { feature } from "./bdd.js";
+export { feature, loadBddRunner, bddHarness, } from "./bdd.js";
 // Pre-existing helpers
 export { factory, sequence } from "./zod-fixture-factory.js";
 export { createTestApp, bootTestApp } from "./supertest-app-helper.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nwire/test-kit",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Shared test helpers and zod-driven fixture factories",
   "keywords": [
     "fixtures",
@@ -28,20 +28,20 @@
   "dependencies": {
     "supertest": "^7.2.2",
     "zod": "^4.0.0",
-    "@nwire/envelope": "0.10.0",
-    "@nwire/forge": "0.10.0",
-    "@nwire/logger": "0.10.0",
-    "@nwire/messages": "0.10.0"
+    "@nwire/envelope": "0.11.0",
+    "@nwire/forge": "0.11.0",
+    "@nwire/logger": "0.11.0",
+    "@nwire/messages": "0.11.0"
   },
   "devDependencies": {
     "@types/koa": "^2.15.0",
     "@types/node": "^22.19.9",
     "@types/supertest": "^6.0.3",
     "typescript": "^5.9.3",
-    "@nwire/app": "0.10.0",
-    "@nwire/endpoint": "0.10.0",
-    "@nwire/wires": "0.10.0",
-    "@nwire/koa": "0.10.0"
+    "@nwire/app": "0.11.0",
+    "@nwire/endpoint": "0.11.0",
+    "@nwire/wires": "0.11.0",
+    "@nwire/koa": "0.11.0"
   },
   "peerDependencies": {
     "@amiceli/vitest-cucumber": "^4.0.0",