rhythmjs

Search documentation

Search guides, the tutorial and every package.

On this page

@rhythmjs/testing/rhythm#

TypeScript
function mockModule<TExports extends object>(values: TExports): Rhythm<TExports>;

function withMockContext(app: Mountable, values: object | undefined): Mountable;

function runMiddleware<TContext extends object>(
  middleware: Middleware<TContext>,
  ctx: TContext,
): Promise<MiddlewareRun<TContext>>;
mockModule(values)#
A Rhythm module named mock whose startup context is values, copied verbatim. Pull it into an app with include(mockModule(values), pick). There is no dispose hook: a fake that needs cleanup is cleaned up by the test that created it.
withMockContext(app, values)#
Wraps any mountable (app, router, cli, ws) so values are assigned onto every call's input. Rhythm merges input over its startup context, so mocks replace real startup values. values may be undefined (no-op). Typed as a plain Mountable, so cast the context it returns.
runMiddleware(middleware, ctx)#
Invokes the middleware with your context and a stub next() that records being called and resolves immediately.
MiddlewareRun<TContext>#
{ ctx: TContext; nextCalled: boolean }: the mutated context and whether the chain continued.
MockContext<TApp>#
The startup fields plus declared input an app accepts mocks for.

@rhythmjs/testing/router#

TypeScript
function createTestClient<TApp extends Mountable>(
  app: TApp, // a Rhythm app or a RhythmRouter that accepts the HTTP context
  options?: TestClientOptions<Mockable<TApp>>,
): 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 app or a bare RhythmRouter and returns verb helpers over toFetchHandler. options.baseUrl resolves relative paths (default http://localhost). options.context is a Partial of the app's startup context and declared input (minus the HTTP base fields), assigned onto every request's context, so mocks replace real startup values. It fails to type-check when the app needs input the client cannot provide.
TestClient#
fetch(input, init?) plus get / head / post / put / patch / delete, each (path, options?) => Promise<Response>. There is no teardown(): close any resource you created yourself in afterAll.
TestRequestOptions#
{ headers?; body?; json? }; json serializes the value and sets content-type: application/json unless you set one yourself, and takes precedence over body. 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. To test a router, pass mount(router).
HttpMiddlewareRun#
{ ctx; nextCalled: boolean; response: Response }: response is the context's response rendered with toResponse.

@rhythmjs/testing/cli#

TypeScript
function createCliRunner<TApp extends Mountable>(
  app: TApp, // a Rhythm app that mounts a cli, or a RhythmCli
  options?: CliRunnerOptions<Mockable<TApp>>,
): CliRunner;

interface CliRunner {
  run(argv: string | string[]): Promise<CliRunResult>;
}

interface CliRunResult {
  stdout: string;
  stderr: string;
  exitCode: number;
}
createCliRunner(app, options?)#
Runs the app through toCliHandler, with output captured instead of written to real stdio. options.context is a Partial of the app's startup context and input (minus the cli base fields), assigned onto every run's context so mocks win over real values.
CliRunner.run(argv)#
argv is a command string (trimmed and split on whitespace) or an argv array. Flags are parsed only when the cli uses withParsedArgv(). An unknown command exits with 2, a thrown error with 1, and ctx.fail(message, code) with your code.
CliRunResult#
{ stdout: string; stderr: string; exitCode: number }: the captured text, newlines included.

@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(peer: MockWs): void | Promise<void>;
function fireMessage(peer: MockWs, data: string | Uint8Array | object): void | Promise<void>;
function fireClose(peer: MockWs, code = 1000, reason = ""): void | Promise<void>;
function fireDrain(peer: MockWs): void | Promise<void>;
upgradeWs(ws, request)#
Mounts the RhythmWs in a fresh Rhythm app and runs the request through toFetchHandler with a recording server. A string becomes a request with the upgrade: websocket header implied. Middleware, the route's upgrade and headers all run for real.
WsUpgradeResult<Data>#
{ upgraded; response; data; headers; peer }: upgraded is true when the route called server.upgrade; response is the rejection or unmatched response, null when accepted; data is the ws.data attached and headers what the route passed to the upgrade (both null when not upgraded); peer is a MockWs built on data, or null.
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#
Take only the peer and invoke the matching handler of the websocket object from @rhythmjs/ws, which dispatches through ws.data to the matched route. The peer must come from upgradeWs. fireMessage passes strings through, wraps Uint8Array in a Buffer, and JSON-serializes any other object. Always await them.