# `conformance-binding`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

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

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

runBunWsConformance();
```

## Usage: Advanced

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