rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

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.

Shell
bun add -D @rhythmjs/testing

Mock 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.

TypeScript
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.

TypeScript
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.

TypeScript
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.