`testing` — `runWsEngineConformance` harness

(no submodules)

Purpose

Every concrete WebSocket engine and broker the foundation publishes (api-ws-bun, api-ws-broker-in-memory, api-ws-broker-redis, future adapters) MUST pass an identical battery of behavioural tests. This module ships that battery as a reusable harness so engine authors get the same verification surface without re-deriving it. The harness covers handshake, subscribe / broadcast fan-out, backpressure policy, heartbeat policy, reconnect-token round trip, broker disposal, and the cross-tenant broadcast capability gate.

It also ships inMemoryFactory — a self-contained (bus, registry, broker, makeConnection) quadruple wired against the in-memory primitives shipped in this package — so the harness self-tests cleanly and engine authors have an executable reference.

Features

runWsEngineConformance({ label, factory }) — Vitest describe/it block driving the seven category tests.
WsEngineFactoryResult — strongly typed quadruple every adapter returns: { bus, registry, broker, makeConnection, dispose }.
inMemoryFactory() — reference factory used by the package's own conformance test.

Usage: Basic

import { runWsEngineConformance } from "@suaveplan/api-ws/testing";
import { createBunEngine } from "@suaveplan/api-ws-bun";

runWsEngineConformance({
    label: "Bun engine",
    factory: async () => createBunEngine(),
});

Usage: Advanced

import {
    inMemoryFactory,
    runWsEngineConformance,
    type WsEngineFactoryResult,
} from "@suaveplan/api-ws/testing";

async function instrumentedFactory(): Promise<WsEngineFactoryResult> {
    const base = inMemoryFactory();
    return {
        ...base,
        async dispose() {
            await base.dispose();
            console.log("engine disposed");
        },
    };
}

runWsEngineConformance({
    label: "instrumented",
    factory: instrumentedFactory,
});

API Reference

interface WsEngineFactoryResult<Payload> { bus, registry, broker, makeConnection, dispose }.
interface WsEngineConformanceOptions<Payload> { label, factory }.
runWsEngineConformance<Payload>(options): void.
inMemoryFactory<Payload>(): WsEngineFactoryResult<Payload>.

Implementation Notes

The harness uses @suaveplan/testing/runner (NOT a direct vitest import) so it stays portable between Vitest and Bun-test under the project's runner conditional-export wrapper.
dispose() runs inside a finally block so a failing assertion still releases the underlying engine resources.
The cross-tenant test uses a deliberately under-capability caller to assert that engines properly delegate to the bus's capability gate rather than re-implementing it incorrectly.
The harness is intentionally additive — engines may layer their own describe(...) blocks alongside it for engine-specific behaviour.

2.9 KiB Raw Blame History

testing — runWsEngineConformance harness