first commit

docs/api-stack/api/api-router-worker-bridge/src/testing/testing.md

@@ -0,0 +1,69 @@
+# `testing`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module hands consumers the in-process scaffolding needed to exercise
+the worker bridge under a real `MessageChannel` without spinning up an
+actual worker thread, plus a conformance harness that every alternate
+transport (in-process today, worker-thread tomorrow) must satisfy.
+
+## Features
+
+- `createInProcessBridge(handler, options?)` returns a ready-to-use pair:
+  the main-side `dispatch`, the underlying ports, and a shared `close`
+  that tears down both halves and the channel.
+- `runBridgeConformance(runner, factory)` exercises round-trip GET, JSON
+  POST, and the header deny-list invariant. Test-runner-agnostic via the
+  injected `ConformanceRunner` shape.
+- Built on `@suaveplan/api-worker-rpc/testing`'s
+  `createInProcessPortPair`, so the conformance suite stays aligned with
+  the underlying RPC contract.
+
+## Usage: Basic
+
+```ts
+import { createInProcessBridge } from
+    "@suaveplan/api-router-worker-bridge/testing";
+
+const bridge = createInProcessBridge(async () => new Response("pong"));
+const res = await bridge.dispatch(new Request("https://api.local/ping"));
+console.log(await res.text()); // "pong"
+bridge.close();
+```
+
+## Usage: Advanced
+
+Plug into Vitest's conformance gates:
+
+```ts
+import { describe, expect, it } from "@suaveplan/testing/runner";
+import {
+    createInProcessBridge,
+    runBridgeConformance,
+} from "@suaveplan/api-router-worker-bridge/testing";
+
+runBridgeConformance(
+    { describe, it, expect: expect as unknown as never },
+    (handler) => createInProcessBridge(handler)
+);
+```
+
+## API Reference
+
+- `createInProcessBridge(handler, options?) → InProcessBridge`.
+- `InProcessBridge { ports, dispatch, close }`.
+- `runBridgeConformance(runner, factory) → void`.
+- `ConformanceRunner { describe(name, body), it(name, opts, body), expect }`
+  — matches vitest 4 / bun:test signatures.
+
+## Implementation Notes
+
+The harness intentionally only asserts the invariants that ALL bridge
+implementations share. Transport-specific behaviour (e.g. worker-thread
+spin-up costs, transferList semantics, restart-on-crash) belongs in the
+transport package's own test file. Each scenario tears down via
+`bridge.close()` in `finally` to avoid leaking ports across tests.