first commit

docs/ui/react/react-audio/src/test-utils.md

@@ -0,0 +1,64 @@
+# `test-utils`
+
+## Purpose
+
+Test-only helpers for the `@suaveplan/react-audio` test suite. The
+module exports three utilities: `makeFakeAudioContext`, an injectable
+`BaseAudioContext`-shaped stub used by adapter tests; `makeFakePlugin`,
+a minimal `AudioFxPlugin` implementation with two declared parameters
+used by parameter / chain hook tests; and `renderWithProvider`, a
+`@testing-library/react` wrapper that mounts the component under an
+`<AudioProvider>` configured with the fake context.
+
+The helpers are excluded from coverage and from the production build —
+they exist purely to keep the test files concise and the assertions
+focused on behaviour rather than fixture setup.
+
+## Features
+
+- `makeFakeAudioContext(sampleRate?)` — returns a plain object that
+  satisfies the engine's `AdapterContextLike` and `AudioContextLike`
+  structural interfaces, with every node type stubbed to no-ops.
+- `makeFakePlugin(options?)` — returns a minimal `AudioFxPlugin`
+  with two parameters (`gain`, `tone`) and a working
+  `getParameter`/`setParameter` pair.
+- `renderWithProvider(ui, opts?, rtlOpts?)` — renders `ui` inside an
+  `<AudioProvider>` injected with the fake context; `opts.strict`
+  toggles `<StrictMode>`.
+
+## Usage: Basic
+
+```tsx
+import { renderWithProvider } from "../test-utils.js";
+
+renderWithProvider(<Consumer />);
+```
+
+## Usage: Advanced
+
+```tsx
+import { makeFakePlugin, renderWithProvider } from "../test-utils.js";
+
+const plugin = makeFakePlugin({ id: "fake-eq" });
+
+renderWithProvider(<UsesPlugin plugin={plugin} />, {
+    strict: true,
+    options: { sampleRateHz: 30 },
+});
+```
+
+## API Reference
+
+- `makeFakeAudioContext(sampleRate?): unknown`.
+- `makeFakePlugin(options?): AudioFxPlugin`.
+- `renderWithProvider(ui, opts?, rtlOptions?)`.
+
+## Implementation Notes
+
+The fake context is a plain object rather than a class because the
+engine's structural type checks pass without nominal identity; every
+`createXxx` method returns a tagged stub whose `constructor.name`
+matches the relevant `AudioNode` class so the engine's
+`classifyNode` helper resolves correctly. The fake plugin's `process`
+is a no-op — these tests do not exercise audio block processing,
+only the React-tier event/state surface around the engine.