# `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.