@irtio/testing 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,542 @@
+import { RoleOf, AnySchema, State, PlainState } from '@irtio/schema';
+import { RoomDefinition } from '@irtio/server';
+import { Room, ClientState, RelayRoom, Scheduler } from '@irtio/client';
+import { RoomCore } from '@irtio/runtime';
+import { TraceEntry, HarnessHost, VisibilityLeak, FakeClock } from '@irtio/runtime/test';
+export { TraceEntry, VisibilityLeak } from '@irtio/runtime/test';
+export { M as MatcherResult, T as TRACE_TAIL, m as matchers, t as toHaveConverged, a as toHaveNoVisibilityLeaks, b as toHaveRejected, c as toStayUnderBandwidth } from './assertions-BP4as6ol.js';
+
+/**
+ * `@irtio/testing`'s public contract: what `testRoom` hands back, and the two option bags.
+ *
+ * The shapes here are the surface the canonical usage example relies on (the docblock in
+ * `index.ts`). Two of them differ from the shipped client and the difference is deliberate:
+ *
+ * - **`client.id` is the *client* id.** The example writes `expect([a.id, b.id]).toContain(...)` against an
+ *   owner, so `a.id` has to be `room.me`. `@irtio/client`'s `Room.id` is the *room code*, so a
+ *   `TestClient` shadows it and re-exposes the room code as `client.roomId`.
+ * - **`client.view` is `room.state`.** The example reads `a.view.cards.get('c1')`; the shipped client calls
+ *   that `room.state`. Both names point at the same object.
+ *
+ * Two more things live here beyond that example:
+ *
+ * - **Reconnection.** `TestClient.drop()` severs a client's in-process transport the way a real
+ *   socket drop would, so the shipped client's own backoff runs on the harness's fake clock —
+ *   `await t.run(300)` is enough to see it reconnect. `TestClient.reconnects` counts how many
+ *   times it has.
+ * - **Relay.** `testRelay()` is the sibling of `testRoom()` for relay rooms: no schema, no
+ *   state, no RPCs — presence and a raw message channel over the same in-process, fake-clock link.
+ */
+
+/**
+ * Network simulation for the in-process link. Delays are applied on the **fake clock**, so a
+ * `rttMs: 100` room still runs at full speed — it just needs 100 ms of `t.run()` to see a reply.
+ */
+interface LatencySpec {
+    /** Round trip in ms; each direction gets half. Default 0. */
+    readonly rttMs?: number;
+    /** Extra uniform `[0, jitterMs)` delay per frame, never enough to reorder. Default 0. */
+    readonly jitterMs?: number;
+    /**
+     * Drop probability in `[0, 1)` for **state** frames (`WRITE`, `DELTA`, `CORRECT`, `MSG`).
+     * Session and RPC frames (`HELLO`, `WELCOME`, `CALL`, `REPLY`, `ERROR`, `PING`, `PONG`) are
+     * never dropped: a WebSocket is a reliable stream, and a lost `WELCOME` would hang the join
+     * rather than teach the test anything.
+     */
+    readonly loss?: number;
+}
+interface TestRoomOptions {
+    /** Overrides the room definition's mode. The definition is **not** re-validated. */
+    readonly mode?: 'tick' | 'event';
+    /** Overrides the room definition's tick rate (and therefore what one `t.tick()` costs in ms). */
+    readonly tickRate?: number;
+    /** `room.random()` and the latency rng share this seed; default 1, same as `RoomCore`. */
+    readonly seed?: number;
+    /** Room-wide link simulation; `t.join(n, { latency })` overrides it per client. */
+    readonly latency?: LatencySpec;
+    /** The room code every client joins. Default `'test-room'`. */
+    readonly roomId?: string;
+    /** The clients' owned-write flush window, in ms of fake time. Default 50 (the client's own). */
+    readonly writeIntervalMs?: number;
+}
+interface TestJoinSpec<Role extends string = string> {
+    readonly role?: Role;
+    readonly name?: string;
+    /** Link simulation for this client only. */
+    readonly latency?: LatencySpec;
+    /**
+     * Implementations of the schema's `client(...)` RPCs, handed straight to `joinRoom({ rpc })`.
+     * Without this there is no way to test a server-to-client call succeeding — the client replies
+     * `no client implementation` and the only reachable path is the failure one.
+     */
+    readonly rpc?: Record<string, (params: never) => unknown>;
+}
+interface UntilOptions {
+    /** Default 1000. */
+    readonly maxTicks?: number;
+    /**
+     * How much fake time each attempt advances. Defaults to the tick interval in tick mode and to
+     * **1 ms in event mode**, where a "tick" is otherwise a zero-length clock step — without this,
+     * `until` could spin a thousand times without moving the clock at all, and could never reach a
+     * timer-driven condition such as a client's reconnect backoff.
+     */
+    readonly stepMs?: number;
+}
+/**
+ * A real `@irtio/client` room, plus the two aliases the canonical example uses. Everything else — `state`,
+ * `call`, `requestOwnership`, `on`, `flush`, `leave` — is the shipped client surface, unchanged.
+ */
+type TestClient<S, Role extends string = RoleOf<S> & string> = Omit<Room<S, Role>, 'id'> & {
+    /** This client's id (`room.me`). The canonical example spells it `a.id`. */
+    readonly id: string;
+    /** The room code — what `Room.id` means outside `@irtio/testing`. */
+    readonly roomId: string;
+    /** Alias of `state`, the name the canonical example uses. */
+    readonly view: ClientState<S, Role>;
+    /**
+     * Severs the in-process transport out from under this client — exactly as a network drop
+     * would, **not** a `leave()`. The room sees a disconnect (not a leave), and the shipped
+     * client's own reconnect backoff (250 ms doubling to a 5 s cap) is driven by the harness's
+     * fake clock: `await t.run(300)` or `await t.until(() => a.status === 'connected')` is enough
+     * to see it resume with the same `id`. `on('status')` fires `'reconnecting'` then
+     * `'connected'`. Synchronous — the socket-close side effects (status flip, backoff timer
+     * armed) happen before `drop()` returns; nothing needs to be awaited to observe them.
+     */
+    drop(options?: {
+        code?: number;
+        reason?: string;
+    }): void;
+    /** How many times this client has completed a reconnect (a resumed `WELCOME` after a drop). */
+    readonly reconnects: number;
+};
+/** One `REPLY` that came back with `ok: false`, keyed by the rpc the client had called. */
+interface RejectedCall {
+    readonly clientId: string;
+    readonly rpc: string;
+    readonly error: string;
+    readonly tick: number;
+}
+/** What `testRoom` returns. */
+interface TestRoom<S extends AnySchema> {
+    /** The tracked authority — the same object room handlers mutate. */
+    readonly state: State<S>;
+    /** The authority's plain state (what the codec reads). */
+    readonly plain: PlainState;
+    /** Every frame that crossed the seam, in order. `in` = client → room, `out` = room → client. */
+    readonly trace: readonly TraceEntry[];
+    /** Error replies seen so far, for `toHaveRejected`. */
+    readonly rejections: readonly RejectedCall[];
+    /** Frames the `latency.loss` die dropped. */
+    readonly dropped: number;
+    /** Escape hatch: the real `RoomCore`. */
+    readonly core: RoomCore<S>;
+    /** Escape hatch: the `RoomHost` the core talks to (logs, kicks, byte counts). */
+    readonly host: HarnessHost;
+    /** Fake-clock time in ms. */
+    readonly now: number;
+    /** The room's tick counter (`tick()` is the method that advances it). */
+    readonly tickCount: number;
+    readonly mode: 'tick' | 'event';
+    /** Every client that joined, in join order. */
+    readonly clients: readonly TestClient<S>[];
+    join<Role extends string = RoleOf<S> & string>(n: number, spec?: TestJoinSpec<Role> & {
+        role?: RoleOf<S> & string;
+    }): Promise<TestClient<S, Role>[]>;
+    join<Role extends string = RoleOf<S> & string>(spec?: TestJoinSpec<Role> & {
+        role?: RoleOf<S> & string;
+    }): Promise<TestClient<S, Role>>;
+    /** Tick mode: run exactly `n` ticks. Event mode: run whatever is already due. */
+    tick(n?: number): Promise<void>;
+    /** Advance the fake clock by `ms`, firing ticks and timers in order. */
+    run(ms: number): Promise<void>;
+    /** Tick until `pred()` holds; rejects when it never does. */
+    until(pred: () => boolean, options?: UntilOptions): Promise<void>;
+    /** `withBuiltins(schema)`: the schema every frame is encoded against. */
+    readonly ext: AnySchema;
+    /** Collections a client can see that its role must not. `[]` when the room is clean. */
+    checkVisibility(): VisibilityLeak[];
+    /**
+     * Judges `clientId` as `role` in `checkVisibility` from now on, without telling the room — the
+     * only way for a test to prove the leak detector actually fires.
+     */
+    pretendRole(clientId: string, role: string): void;
+    /** Per-client divergence from the authority; `differences` is empty when that client is level. */
+    convergence(): {
+        clientId: string;
+        differences: string[];
+    }[];
+    /** Outbound bytes per client and the per-tick average, as `toStayUnderBandwidth` reads them. */
+    bandwidth(): {
+        clientId: string;
+        bytes: number;
+        perTick: number;
+    }[];
+    /** Every client leaves and the room stops. */
+    stop(): void;
+}
+interface TestRelayOptions {
+    /** Presence order and the latency rng share this seed; default 1, same as `testRoom`. */
+    readonly seed?: number;
+    /** Room-wide link simulation for every relay client. */
+    readonly latency?: LatencySpec;
+    /** The room code every client joins. Default `'test-relay'`. */
+    readonly roomId?: string;
+    /** Default 64, same as `@irtio/server`'s relay default. */
+    readonly maxClients?: number;
+}
+interface TestRelayJoinSpec {
+    readonly role?: string;
+    readonly name?: string;
+}
+/** A real `@irtio/client` relay room, plus `drop()` and a recording of every `onMessage` delivery. */
+type TestRelayClient = RelayRoom & {
+    /** Severs the in-process transport, exactly as `TestClient.drop` does for a schema room. */
+    drop(options?: {
+        code?: number;
+        reason?: string;
+    }): void;
+    /** Every `{ from, bytes }` this client's `onMessage` has delivered, in order. */
+    readonly received: readonly {
+        from: string;
+        bytes: Uint8Array;
+    }[];
+};
+/** What `testRelay` returns: `testRoom`'s sibling for a schema-less relay room. */
+interface TestRelay {
+    join(n: number, spec?: TestRelayJoinSpec): Promise<TestRelayClient[]>;
+    join(spec?: TestRelayJoinSpec): Promise<TestRelayClient>;
+    /** Advance the fake clock by `ms`, firing timers (and message delivery) in order. */
+    run(ms: number): Promise<void>;
+    /** Relay rooms have no tick loop; this just settles whatever is already in flight `n` times. */
+    tick(n?: number): Promise<void>;
+    /** Advances the fake clock until `pred()` holds; rejects when it never does. */
+    until(pred: () => boolean, options?: UntilOptions): Promise<void>;
+    /** Every client that joined, in join order. */
+    readonly clients: readonly TestRelayClient[];
+    /** Every frame that crossed the seam, in order. `in` = client → relay, `out` = relay → client. */
+    readonly trace: readonly TraceEntry[];
+    /** Every client leaves and the relay stops. */
+    stop(): void;
+}
+
+/**
+ * `testRoom` — a real `RoomCore`, real `@irtio/client` instances, and nothing in between but
+ * function calls.
+ *
+ * ## Why this does not wrap `createRoomHarness`
+ *
+ * That harness owns its own `FakeClient`: its `join()` calls `RoomCore.join()` directly and
+ * hands back a `JoinResult`, and the bridge that carries frames is private. A real client needs a
+ * `WELCOME` frame, not a `JoinResult`. So this file builds on the harness's **public** pieces —
+ * `FakeClock`, `HarnessHost`, `RoomCore`, `visibleNames`, `TraceEntry`, `VisibilityLeak` — and adds
+ * the one thing that was missing: a tiny in-process supervisor that speaks the wire.
+ *
+ * ## Timing model
+ *
+ * The only clock is `FakeClock`, shared by the room (through `HarnessHost`) and by every client
+ * (through `clockScheduler`). **Every** frame crosses the seam as a fake-clock timer, including
+ * the zero-latency case. That is what keeps the core re-entrancy-free: `FakeClock.advance` fires
+ * timers in a loop, never nested, so `RoomCore.receive` is never called from inside a
+ * `RoomCore` send. Latency is then just a larger delay on the same timer.
+ *
+ * ## Reconnection
+ *
+ * `TestClient.drop()` (see `dropClient` below) calls `RoomCore.markDisconnected` — the same call
+ * the real supervisor makes when a socket closes mid-session — and then `InProcessSocket.hangUp`,
+ * which fires the client's `onclose` without going through `linkClosed`/`RoomCore.leave`. The
+ * client's own backoff (`Session.onSocketClosed` in `@irtio/client`) is armed with
+ * `this.scheduler.setTimeout`, and `this.scheduler` here is `clockScheduler(this.clock)` — the
+ * same `FakeClock` everything else runs on — so the backoff genuinely advances with `t.run()`/
+ * `t.tick()`, not a real timer running alongside them.
+ *
+ * ## Why `t.tick()` is async
+ *
+ * The clock is synchronous but a client is not: `joinRoom` resolves in a microtask, an RPC promise
+ * settles in a microtask, and an async client RPC implementation replies in one. So each of
+ * `join`, `tick`, `run` and `until` advances the clock, drains microtasks, and repeats until
+ * nothing new is in flight — which makes them `Promise`-returning. Callers already await `testRoom`
+ * and `t.join`; `await t.tick()` is the same shape.
+ */
+
+declare class TestHarness<S extends AnySchema> implements TestRoom<S> {
+    private readonly clock;
+    readonly host: HarnessHost;
+    private readonly coreRef;
+    private readonly scheduler;
+    private readonly rng;
+    private readonly definition;
+    private readonly links;
+    private readonly byId;
+    private readonly resumeTokens;
+    private readonly clientList;
+    private readonly roleById;
+    private readonly roleOverrides;
+    private readonly traceLog;
+    private readonly frameLeaks;
+    private readonly rejectionLog;
+    /** Reconnects completed per client id — bumped in `handleHello` on a resumed `WELCOME`. */
+    private readonly reconnectCounts;
+    private nextClientId;
+    private droppedFrames;
+    /** Bumped whenever a frame is scheduled or delivered; the settle loop watches it. */
+    private activity;
+    private inCore;
+    private readonly deferred;
+    private readonly roomId;
+    private readonly writeIntervalMs;
+    private readonly latency;
+    private stopped;
+    constructor(definition: RoomDefinition<S>, options: TestRoomOptions);
+    get core(): RoomCore<S>;
+    get state(): State<S>;
+    get plain(): PlainState;
+    get trace(): readonly TraceEntry[];
+    get rejections(): readonly RejectedCall[];
+    get dropped(): number;
+    get now(): number;
+    get tickCount(): number;
+    get mode(): 'tick' | 'event';
+    get clients(): readonly TestClient<S>[];
+    private get intervalMs();
+    /** The extended schema every frame is encoded against. */
+    get ext(): AnySchema;
+    private enterCore;
+    /** A `Transport` bound to one `t.join()`; reconnects call `connect` again with the same spec. */
+    private transportFor;
+    /** The client end hung up: a deliberate `leave()`, or `t.stop()`. Treated as a graceful leave. */
+    private linkClosed;
+    /**
+     * `TestClient.drop()`: severs the transport out from under a client, the way a network drop
+     * would — the room only learns the client is *disconnected* (`RoomCore.markDisconnected`, the
+     * same call the real supervisor makes when a socket closes mid-session), not that it left. The
+     * client's own `onclose` handler then arms its reconnect backoff on the fake clock, exactly as
+     * it would over a real killed socket.
+     */
+    private dropClient;
+    /**
+     * Schedules one frame's arrival on the fake clock. Returns `false` when the loss die dropped it.
+     * The `next*` clamp keeps a jittered stream in order: a WebSocket never reorders.
+     */
+    private schedule;
+    private fromClient;
+    private preresolve;
+    private noteCall;
+    private toRoom;
+    /**
+     * `LEAVE`, the wire counterpart of `linkClosed`'s deliberate-leave branch: call
+     * `RoomCore.leave` with `'left'` right away instead of routing the frame into
+     * `RoomCore.receive` (which has no case for it — that would hit its `badFrame` fallback) or
+     * waiting for the socket's close event. Marks the link gone first so the close that follows
+     * moments later (`leave()` always closes its socket) finds `linkClosed` a no-op.
+     */
+    private handleLeaveFrame;
+    /**
+     * The whole supervisor: allocate an id, `RoomCore.join`, answer with a real `WELCOME`. The
+     * resume token is the client id — there is nothing to sign in-process.
+     */
+    private handleHello;
+    private fail;
+    private toClient;
+    /** A `DELTA`/`CORRECT` naming a collection this client's role may not see is a leak. */
+    private checkFrame;
+    private noteReply;
+    private record;
+    /** Fires everything due, then lets the clients' promises run, until nothing new is in flight. */
+    private settle;
+    tick(n?: number): Promise<void>;
+    run(ms: number): Promise<void>;
+    /**
+     * Advances until `pred()` holds. In **event mode** a tick is a zero-length clock step, so this
+     * advances `stepMs` (1 ms by default) of fake time per attempt instead — otherwise a condition
+     * that depends on a timer, such as a dropped client's 250 ms reconnect backoff, could never
+     * become true no matter how large `maxTicks` was. Found when a test spent its whole budget
+     * on `t.until: predicate still false after 1000 ticks`.
+     */
+    until(pred: () => boolean, options?: UntilOptions): Promise<void>;
+    join<Role extends string = RoleOf<S> & string>(n: number, spec?: TestJoinSpec<Role> & {
+        role?: RoleOf<S> & string;
+    }): Promise<TestClient<S, Role>[]>;
+    join<Role extends string = RoleOf<S> & string>(spec?: TestJoinSpec<Role> & {
+        role?: RoleOf<S> & string;
+    }): Promise<TestClient<S, Role>>;
+    private joinOne;
+    /**
+     * Drives the clock until `joinRoom` settles. A zero-latency join lands inside the first
+     * `advance(0)`; a slow link needs the 1 ms steps.
+     */
+    private awaitJoin;
+    /**
+     * Judges `clientId` as `role` in `checkVisibility` from now on, without telling the room. The
+     * only way to prove the leak detector fires: a correct room never produces a leak, so a test
+     * that asserts the checker works has to assert a client against a role it did not join as.
+     */
+    pretendRole(clientId: string, role: string): void;
+    private roleFor;
+    checkVisibility(): VisibilityLeak[];
+    /** Per-client divergence from the authority, restricted to what that client's role may see. */
+    convergence(): {
+        clientId: string;
+        differences: string[];
+    }[];
+    /** Outbound bytes per client, and the ticks they were spread over. */
+    bandwidth(): {
+        clientId: string;
+        bytes: number;
+        perTick: number;
+    }[];
+    stop(): void;
+}
+
+/**
+ * `testRelay` — `testRoom`'s sibling for a relay room: no `RoomCore`, no schema, no worker.
+ *
+ * A relay room's server side is `@irtio/supervisor`'s `RelayRoom` (presence bookkeeping) plus a
+ * few lines of `MSG` forwarding in `server.ts` — but `RelayRoom` is not part of that package's
+ * public surface (`@irtio/supervisor`'s `package.json` only exports `.`), and going through the
+ * supervisor for real would mean a real `ws` server, breaking `@irtio/testing`'s "no sockets"
+ * promise. So this file does what `harness.ts` already does for schema rooms: it re-implements
+ * the tiny slice of the supervisor a relay client actually needs — presence add/disconnect/remove
+ * against `relaySchema`, and `MSG` fan-out — as an in-process peer of the real `@irtio/client`
+ * `joinRelay`, wired through the same `InProcessSocket` and driven by the same `FakeClock`. No new
+ * workspace dependency: every primitive here (`relaySchema`, `PRESENCE_COLLECTION`, `EntityCollection`,
+ * `encodeDelta`/`encodeSnapshot`, …) is already public in `@irtio/protocol` and `@irtio/schema`,
+ * which `@irtio/testing` depends on regardless.
+ */
+
+declare class TestRelayHarness implements TestRelay {
+    private readonly clock;
+    private readonly scheduler;
+    private readonly rng;
+    private readonly relay;
+    private readonly roomId;
+    private readonly maxClients;
+    private readonly latency;
+    private readonly links;
+    private readonly byId;
+    private readonly resumeTokens;
+    private readonly clientList;
+    private readonly traceLog;
+    private nextClientId;
+    private activity;
+    private stopped;
+    constructor(options: TestRelayOptions);
+    get clients(): readonly TestRelayClient[];
+    get trace(): readonly TraceEntry[];
+    private transportFor;
+    private linkClosed;
+    private dropClient;
+    private schedule;
+    private fromClient;
+    private preresolve;
+    private toRelay;
+    private handleHello;
+    private fail;
+    private relayMsg;
+    private toClient;
+    /** Sends a presence delta to everyone except (optionally) the client it is about. */
+    private broadcastDelta;
+    private record;
+    private settle;
+    tick(n?: number): Promise<void>;
+    run(ms: number): Promise<void>;
+    until(pred: () => boolean, options?: UntilOptions): Promise<void>;
+    join(n: number, spec?: TestRelayJoinSpec): Promise<TestRelayClient[]>;
+    join(spec?: TestRelayJoinSpec): Promise<TestRelayClient>;
+    private joinOne;
+    private awaitJoin;
+    stop(): void;
+}
+
+/**
+ * The client `Scheduler` backed by the harness `FakeClock`. Injecting this is what makes a
+ * `testRoom` test finish in microseconds: the write batcher, the ping timer and every RPC timeout
+ * are armed on fake time, so nothing in the room needs a real timer to make progress.
+ *
+ * `frame()` is deliberately absent. The browser scheduler aligns the write batcher to
+ * `requestAnimationFrame` with `writeIntervalMs` as a cap; a fake clock has no frames, and leaving
+ * it out means one flush per `writeIntervalMs` exactly — which is what a deterministic test wants.
+ */
+
+/** A `Scheduler` whose whole notion of time is `clock`. */
+declare function clockScheduler(clock: FakeClock): Scheduler;
+
+/**
+ * Comparing a client's view with the authority.
+ *
+ * A `testRoom` client is a real `@irtio/client`, and its decoded state is private to it. What is
+ * public is `room.state` — the collection facades and singleton proxies a builder reads — so that
+ * is what the matchers check: the view is **materialised** back into a `PlainState` through the
+ * public read API, and then diffed against the authority with `computeDirty`. Nothing here reaches
+ * into the client's internals, which is the point: a leak the builder can see is a leak.
+ */
+
+type AnyRecord = Record<string, unknown>;
+/** Reads a client's `room.state` back into a plain state of the extended schema. */
+declare function materialize(ext: AnySchema, view: AnyRecord): PlainState;
+/**
+ * Where a client's view differs from the authority, restricted to the collections its role may
+ * see. Empty ⇒ converged.
+ */
+declare function divergence(ext: AnySchema, authority: PlainState, client: PlainState, visible: ReadonlySet<string>): string[];
+
+/**
+ * `@irtio/testing` — the blessed test API.
+ *
+ * ```ts
+ * import { test, expect } from 'vitest';
+ * import { testRoom } from '@irtio/testing';
+ * import '@irtio/testing/matchers';
+ * import room from './room';
+ *
+ * test('two players grab the same card; exactly one wins', async () => {
+ *   const t = await testRoom(room);
+ *   const [a, b] = await t.join(2, { role: 'player' });
+ *   a.requestOwnership('cards', 'c1');
+ *   b.requestOwnership('cards', 'c1');
+ *   await t.tick();
+ *   expect([a.id, b.id]).toContain(t.state.cards.ownerOf('c1'));
+ *   expect(t).toHaveNoVisibilityLeaks();
+ * });
+ * ```
+ *
+ * No sockets, no worker, no real timers, no randomness that is not seeded: a room, its clients and
+ * the network between them are one synchronous object graph driven by a fake clock. The clients
+ * are the shipped `@irtio/client` — prediction, batching, server-wins and reconnection included —
+ * so a test that passes here is testing the SDK your players run, not a stand-in.
+ *
+ * **Reconnection.** `t.join()`'s clients have a `drop()`: it severs the in-process transport the
+ * way a real socket drop would (not a `leave()`), and the shipped client's own backoff — driven
+ * by this same fake clock — reconnects it. `await t.run(300)` (or `t.until(...)`) is enough to
+ * see `on('status')` fire `'reconnecting'` then `'connected'`; `client.reconnects` counts how
+ * many times it has.
+ *
+ * **Relay.** `testRelay()` is the sibling of `testRoom()` for relay rooms: no schema, no
+ * state, no RPCs — just presence and `message()`/`onMessage()`, over the same in-process link.
+ *
+ * ```ts
+ * const relay = await testRelay();
+ * const [a, b] = await relay.join(2);
+ * a.message('all', new TextEncoder().encode('hi'));
+ * await relay.until(() => b.received.length > 0);
+ * ```
+ *
+ * Importing this module does **not** pull Vitest in. `@irtio/testing/matchers` does, and
+ * registers the four matchers as a side effect.
+ *
+ * Every method that touches the clock — `join`, `tick`, `run`, `until` on both `testRoom` and
+ * `testRelay` — is `async` and **must be awaited**; see `harness.ts`'s docblock for why.
+ */
+
+/**
+ * Starts a room in-process and returns the test handle.
+ *
+ * Two overloads rather than one signature with an optional parameter: a defaulted generic in a
+ * contextually-typed position widens to `any`, which is how three schema-inference bugs got in
+ * (see `types.test-d.ts`). Splitting the call keeps `S` inferred from `definition` in both shapes.
+ */
+declare function testRoom<S extends AnySchema>(definition: RoomDefinition<S>): Promise<TestRoom<S>>;
+declare function testRoom<S extends AnySchema>(definition: RoomDefinition<S>, options: TestRoomOptions): Promise<TestRoom<S>>;
+/** Starts a schema-less relay room in-process and returns the test handle. See the module docblock. */
+declare function testRelay(options?: TestRelayOptions): Promise<TestRelay>;
+
+export { type LatencySpec, type RejectedCall, type TestClient, TestHarness, type TestJoinSpec, type TestRelay, type TestRelayClient, TestRelayHarness, type TestRelayJoinSpec, type TestRelayOptions, type TestRoom, type TestRoomOptions, type UntilOptions, clockScheduler, divergence, materialize, testRelay, testRoom };