@nwire/test-kit

Test helpers for Nwire apps — harness, telemetry probe, Docker presets, BDD.

What it does

Boots a Nwire app in-process with in-memory adapters, gives you a dispatch/query/telemetry/idle/stop API, and adds Docker presets for real-deps integration tests plus a Gherkin BDD wrapper around vitest-cucumber. Three layers (unit, real-deps, BDD) so the same test kit covers fast feedback and end-to-end coverage.

Install

pnpm add -D @nwire/test-kit

Quick start

import { describe, it, expect } from "vitest";
import { harness } from "@nwire/test-kit";
import { app } from "../app";

describe("enrolStudent", () => {
  it("emits StudentWasEnrolled", async () => {
    const h = await harness({ app });
    try {
      const probe = h.telemetry.events("StudentWasEnrolled");
      await h.dispatch("enrolStudent", { studentId: "s-1", courseId: "c-1" });
      await h.idle();
      expect(probe.collected).toHaveLength(1);
    } finally {
      await h.stop();
    }
  });
});

API surface

• harness({ app, providers? }) — boot an app in-process; returns { dispatch, query, telemetry, idle, stop }.
• TelemetryProbe / TelemetryFilter — filter the runtime telemetry stream.
• dockerCompose({ preset }) — spin up Mongo / Postgres / NATS / Redis for the suite; DOCKER_COMPOSE_PRESETS for ready-made stacks.
• feature(path, define) — wire .feature files to vitest via @amiceli/vitest-cucumber.
• factory(schema) / sequence() — zod-driven fixture factories.
• createTestApp / bootTestApp — supertest agent helpers for HTTP-level tests.
• isReachable(url) — startup probe for Docker-backed services.

Integration helpers

Layered on harness() for ergonomic integration tests. Each one is a thin proxy — the base Harness interface stays untouched.

asUser

Pin envelope.user on every dispatch/query in a scoped proxy. The acting user (and tenant) flows through to handlers, RBAC middleware, and audit fields automatically.

await asUser(h, { id: "u-1", roles: ["admin"], tenant: "t-1" }).dispatch(createPost, { ... });

simulateRequest

Run a request through a wired Koa app as if it came over HTTP — wraps supertest so test code doesn't need to know which agent helper to import. Returns { status, body, headers }.

const res = await simulateRequest(api.toKoa(), { method: "POST", path: "/posts", body: { ... } });
expect(res.status).toBe(201);

checkPolicy

Build an ability for a user via a @nwire/rbac-shaped factory and run a can(action, subject?) check. Returns { can, reason? } — reason carries the CASL rule message when access is denied.

const check = await checkPolicy(buildAbility, user, "delete", subject("Post", post));
expect(check.can).toBe(false);

onLog

Tap every logger.{info,warn,error,debug} call made through the runtime. Returns an unsubscribe function. Use to assert "warned about X" without swapping in a fake logger.

const off = onLog(h, (e) => expect(e.message).not.toMatch(/PII/));
// ... drive a flow ...
off();

When to use

In every Nwire test file. Fits every level — harness covers unit/integration, dockerCompose covers real-deps, feature covers BDD acceptance.