API reference · @rhythmjs/testing

@rhythmjs/testing/rhythm#

TypeScript

function mockModule<TExports extends object>(
  values: TExports,
  dispose?: (values: TExports) => void | Promise<void>,
): Rhythm<{}, TExports, TExports>;

function runMiddleware<TContext extends object>(
  middleware: Middleware<TContext>,
  ctx: TContext,
): Promise<MiddlewareRun<TContext>>;

mockModule(values, dispose?)#: A Rhythm module (type module, name mock) providing values verbatim. dispose, when given, runs on the host app's teardown with those same values.
runMiddleware(middleware, ctx)#: Invokes the middleware with your context and a next() that records being called and resolves to the context.
MiddlewareRun<TContext>#: { ctx: TContext; nextCalled: boolean }: the mutated context and whether the chain continued.

@rhythmjs/testing/router#

TypeScript

function createTestClient(
  app: Rhythm<RhythmHttpContext, …> | RhythmRouter,
  options?: TestClientOptions,
): TestClient;

function runHttpMiddleware<TExtras extends object = {}>(
  middleware: Middleware<RhythmHttpContext & TExtras>,
  request?: string | Request,
  extras?: TExtras,
): Promise<HttpMiddlewareRun<RhythmHttpContext & TExtras>>;

createTestClient(app, options?)#: Accepts a Rhythm HTTP app or a bare RhythmRouter (mounted into a fresh app for you) and returns verb helpers over toFetchHandler. options.baseUrl resolves relative paths (default http://localhost).
TestClient#: fetch(input, init?) plus get / head / post / put / patch / delete, each (path, options?) => Promise<Response>, and teardown() which disposes the app's providers.
TestRequestOptions#: { headers?; body?; json? }; json serializes the value and sets content-type: application/json unless you set one yourself. TestRequestHeaders, TestRequestBody, and TestRequestInit alias the corresponding fetch constructor parameter types.
runHttpMiddleware(middleware, request?, extras?)#: Builds a real HTTP context with createHttpContext from a path or Request (default http://localhost/), assigns extras onto it, runs the middleware, and returns HttpMiddlewareRun.
HttpMiddlewareRun#: { ctx; nextCalled: boolean; response: Response } - response is the context's response rendered with toResponse.

@rhythmjs/testing/cli#

TypeScript

function createCliRunner(
  app: Rhythm<RhythmCliContext, …> | RhythmCli,
): CliRunner;

createCliRunner(app)#: Accepts a Rhythm CLI app or a bare RhythmCli (mounted for you). The runner parses flags exactly like the real entry point, via parseArgv.
CliRunner.run(argv, options?)#: argv is a command string (whitespace-split) or an argv array. options.stdin becomes a web ReadableStream on the context; omitted, ctx.stdin is null, matching a TTY. Resolves to CliRunResult.
CliRunResult#: { ctx; stdout: string[]; stderr: string[]; exitCode: number } - copies of the response buffers, nothing written to real stdio.
CliRunner.teardown()#: Disposes the underlying app's providers.

@rhythmjs/testing/ws#

TypeScript

function upgradeWs<Data extends object = Record<string, string>>(
  ws: RhythmWs,
  request: string | Request,
): Promise<WsUpgradeResult<Data>>;

function mockWs<Data extends object = Record<string, string>>(data: Data): MockWs<Data>;

function fireOpen(ws: RhythmWs, peer: MockWs): void | Promise<void>;
function fireMessage(ws: RhythmWs, peer: MockWs, data: string | Uint8Array | object): void | Promise<void>;
function fireClose(ws: RhythmWs, peer: MockWs, code = 1000, reason = ""): void | Promise<void>;
function fireDrain(ws: RhythmWs, peer: MockWs): void | Promise<void>;

upgradeWs(ws, request)#: Drives RhythmWs.upgrade against a mock server whose upgrade() always accepts and records its options. A string becomes a request with the upgrade: websocket header implied. Guards, the route's upgrade, and headers all run for real.
WsUpgradeResult<Data>#: { matched; upgraded; response; data; headers } - matched is false when upgrade() returned null (not a websocket request, or no route); response carries a rejection; on success data is the exact ws.data object and headers whatever the route contributed to the 101.
mockWs(data)#: A recording ServerWebSocket stand-in: sent, published, topics, closed, and terminated capture everything handlers do; send/publish return byte counts; close/terminate flip readyState to 3. data, readyState, remoteAddress (127.0.0.1), and isSubscribed round out the surface handlers touch.
fireOpen / fireMessage / fireClose / fireDrain#: Dispatch through the instance's real websocket behavior, so routing by ws.data identity is exercised too. fireMessage passes strings through, wraps Uint8Array in a Buffer, and JSON-serializes any other object.