Testing@rhythmjs/testing
Mock the kernel
Typed module fakes that drop into register(), and a one-middleware driver that reports whether next() ran - no ports, no processes.
Install the package#
@rhythmjs/testing is the test toolkit for the whole ecosystem, one harness per layer, each on its own subpath export with no root barrel: /rhythm for the kernel (this page), /router for HTTP, /cli for commands, and /ws for WebSockets (upgradeWs, mockWs, fireOpen). Everything runs in-process on bun test; nothing listens on a port.
bun add -D @rhythmjs/testingMock kernel modules#
mockModule(values) builds a Rhythm module whose startup context is exactly the object you pass: the drop-in replacement for a real module wherever the app would include it. Its return type exposes values' shape, so the include pick callback stays fully typed. There is no dispose hook; a fake that needs cleanup is cleaned up by the test that created it.
import { Rhythm, include } from "@rhythmjs/rhythm";
import { mockModule } from "@rhythmjs/testing/rhythm";
const sent: string[] = [];
const app = new Rhythm().register(
include(mockModule({ mailer: { send: async (to: string) => void sent.push(to) } }), ({ mailer }) => ({ mailer })),
);Swap it for the real module at the one register(include(...)) call site; handlers and every downstream middleware are untouched.
Override startup values#
To replace values on an app you already built, wrap it with withMockContext(app, values). It assigns values onto every call's input, and Rhythm merges input over its startup context, so the mock wins over the real value. It accepts any mountable (an app, a router, a cli, a ws route). The result is typed as a plain mountable, so you may need a cast on the context it returns. createTestClient and createCliRunner use it for their context option.
import { Rhythm, decorate } from "@rhythmjs/rhythm";
import { withMockContext } from "@rhythmjs/testing/rhythm";
const app = new Rhythm().register(decorate(() => ({ name: "real" })));
const ctx = (await withMockContext(app, { name: "mock" }).callback()({})) as { name: string };
expect(ctx.name).toBe("mock");Run one middleware#
runMiddleware(middleware, ctx) drives a single middleware against a context you construct: no kernel, no composition. It resolves to { ctx, nextCalled }: the same (mutated) context back, and whether the middleware called next(). The next passed in is a stub that records the call and resolves immediately; nothing downstream runs.
import { runMiddleware } from "@rhythmjs/testing/rhythm";
const { ctx, nextCalled } = await runMiddleware(audit(), { user: "ada", log: [] });
expect(nextCalled).toBe(true);
expect(ctx.log).toContain("audited ada");Guards are the negative case: a middleware that short-circuits reports nextCalled: false. For HTTP middleware specifically, prefer runHttpMiddleware, which seeds a real HTTP context and renders the response.