`conformance-binding`

(no submodules)

Purpose

Binds the abstract runWsEngineConformance harness from @suaveplan/api-ws/testing to a default createBunWsEngine-backed factory. Plugin authors who want to drop the conformance suite into their own integration tests import runBunWsConformance from @suaveplan/api-ws-bun/testing and get the full Stage-1 contract assertion set wired against the Bun engine in one line.

The factory uses @suaveplan/api-ws-broker-in-memory so the conformance run has no external dependencies — every host that can run Bun + vitest can run the suite without standing up Redis.

Features

bunEngineFactory() — fresh engine/broker per scenario; no shared state.
adaptEngineToFactory(engine, broker?) — exposes a custom engine through the conformance factory contract.
runBunWsConformance(options?) — drop-in suite that defaults to bunEngineFactory but accepts a custom label / factory for plugin-specific wiring.
Re-export of runWsEngineConformance so the api-ws import is one hop away.

Usage: Basic

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

runBunWsConformance();

Usage: Advanced

import { createInMemoryWsBroker } from "@suaveplan/api-ws-broker-in-memory";
import {
    adaptEngineToFactory,
    runBunWsConformance,
} from "@suaveplan/api-ws-bun/testing";
import { createBunWsEngine } from "@suaveplan/api-ws-bun";

runBunWsConformance({
    label: "bun-with-strict-heartbeat",
    factory: () => {
        const broker = createInMemoryWsBroker();
        const engine = createBunWsEngine({
            reconnectTokenSecret: new Uint8Array(32).fill(1),
            broker,
            heartbeatMs: 5_000,
            missedPongLimit: 1,
        });
        return adaptEngineToFactory(engine, broker);
    },
});

API Reference

bunEngineFactory<Payload>(): WsEngineFactoryResult<Payload> — default factory.
adaptEngineToFactory<Payload>(engine, broker?): WsEngineFactoryResult<Payload> — manual adapter.
runBunWsConformance(options?): void — convenience wrapper around runWsEngineConformance.

Implementation Notes

makeTestConnection routes through the real engine.attach(...) path, so the conformance suite exercises the production handshake / registry / bus wiring rather than a stubbed registry add. This is the same property the api-ws contract package's inMemoryFactory achieves for the in-memory bus — once you accept the conformance contract, the implementation is tested too.

The default factory's secret is a fixed Uint8Array(32).fill(7) — that is acceptable for tests because no test asserts on token contents across factory invocations. Production callers MUST supply their own secret via createBunWsEngine directly, never through this convenience factory.

2.8 KiB Raw Blame History

conformance-binding