Testing@rhythmjs/testing
WebSockets, socketless
Run the whole upgrade for real against a mock server, get a recording peer built on the attached ws.data, and fire lifecycle events through the real handler.
Upgrade without sockets#
upgradeWs(ws, request) from @rhythmjs/testing/ws drives a RhythmWs upgrade the way production does: it mounts the instance in a fresh Rhythm app and calls it through toFetchHandler with a mock Bun server. The origin check, middleware, the route's upgrade, and headers all run for real; only server.upgrade() is captured instead of taking a socket. A plain path gets the upgrade: websocket header implied (the request goes to http://localhost); pass a full Request to control headers, cookies, or the Origin yourself.
import { upgradeWs } from "@rhythmjs/testing/ws";
const result = await upgradeWs(ws, "/ws/rooms/7?token=good");
// {
// upgraded: true, server.upgrade() was called
// response: null, the answer when rejected or unmatched, otherwise null
// data: { room: "7", ... }, the ws.data that was attached
// headers: null, the 101 headers when the route sets them
// peer: MockWs, a recording peer built on data; null when not upgraded
// }The generic parameter types data and peer: upgradeWs<Chat>(ws, "/ws/chat"). Because the full pipeline runs, an unauthenticated handshake is simply a rejected result, and a path no route serves comes back unupgraded with the app's 404:
import { expect, test } from "bun:test";
test("a handshake without a token is refused", async () => {
const result = await upgradeWs(guardedWs, "/ws/guarded");
expect(result.upgraded).toBe(false);
expect(result.response?.status).toBe(401);
expect(result.peer).toBeNull();
});The recording peer#
peer is a MockWs<Data>, a recording stand-in for Bun's ServerWebSocket<Data> built around the exact data the upgrade attached. It records everything handlers do: sent and published (send and publish return byte counts like Bun), topics with isSubscribed(), closed with code and reason, terminated, and a readyState that moves from open to closed. remoteAddress is 127.0.0.1. You can also build one by hand with mockWs(data) for a handler unit test that skips the upgrade.
Firing lifecycle events#
fireOpen(peer), fireMessage(peer, data), fireClose(peer, code?, reason?), and fireDrain(peer) dispatch through the real websocket handler from @rhythmjs/ws, the same data-identity routing production uses, so a peer whose data did not come from an upgrade has no handlers to run. fireMessage accepts a string, bytes (delivered as a Buffer, Bun's binary shape), or any object, which is JSON-serialized, so a join command is just an object. fireClose defaults to code 1000 with an empty reason.
import { upgradeWs, fireOpen, fireMessage, fireClose } from "@rhythmjs/testing/ws";
test("join by message, then chat", async () => {
const { peer } = await upgradeWs(chatWs, "/ws");
await fireOpen(peer!);
await fireMessage(peer!, { type: "join", room: "dev" });
expect(peer!.isSubscribed("room:dev")).toBe(true);
await fireMessage(peer!, { type: "say", text: "hi" });
expect(peer!.published.at(-1)).toEqual({ topic: "room:dev", data: `${peer!.data.handle}: hi` });
await fireClose(peer!, 1001, "bye");
expect(peer!.published.at(-1)?.data).toContain("left");
});What to assert where#
Rejections are upgradeWs assertions (upgraded, response?.status); connection behavior is peer assertions (sent, published, subscriptions, closed); negotiated handshakes are headers assertions. Publishing from an HTTP route with ctx.server.publish is a router concern: test it with the router client. The upgrade contract itself, middleware order and the ctx.server requirement, is documented in Quick start and Serving & tuning.