Initial Commit

packages/api-stack/api/api-ws/src/testing/conformance.md

@@ -0,0 +1,88 @@
+# `testing` — `runWsEngineConformance` harness
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## 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
+
+```ts
+import { runWsEngineConformance } from "@suaveplan/api-ws/testing";
+import { createBunEngine } from "@suaveplan/api-ws-bun";
+
+runWsEngineConformance({
+    label: "Bun engine",
+    factory: async () => createBunEngine(),
+});
+```
+
+## Usage: Advanced
+
+```ts
+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.