first commit

docs/ui/react/react-audio-stream/src/test-setup.md

@@ -0,0 +1,59 @@
+# test-setup
+
+## Purpose
+
+`test-setup.ts` is the per-worker bootstrap file referenced by `vitest.config.ts`'s
+`setupFiles`. It registers `@testing-library/jest-dom`'s custom matchers
+(`toBeInTheDocument`, `toHaveAttribute`, `toHaveTextContent`, ...) onto Vitest's
+`expect`, and it installs a global `afterEach` hook that runs
+`@testing-library/react`'s `cleanup()` so each test starts with a fresh DOM tree.
+
+The auto-cleanup that ships with `@testing-library/react` is gated on
+`globalThis.afterEach` being present at import time, which is not the case under
+Vitest's `globals: false` mode used by this package — hence the explicit hook here.
+
+## Features
+
+- Loads `@testing-library/jest-dom/vitest` (Vitest-native matcher extension).
+- Installs an `afterEach` hook to call `cleanup()`.
+- Runs once per worker process; idempotent across re-imports.
+
+## Usage: Basic
+
+The file is referenced by `vitest.config.ts`:
+
+```ts
+setupFiles: ["@suaveplan/testing/polyfills", "./src/test-setup.ts"],
+```
+
+Consumers do not import it directly.
+
+## Usage: Advanced
+
+To add another test-time global (e.g. a fake `localStorage` reset), extend this file:
+
+```ts
+import { afterEach } from "@suaveplan/testing/runner";
+import { cleanup } from "@testing-library/react";
+
+afterEach(() => {
+    cleanup();
+    localStorage.clear();
+});
+```
+
+## API Reference
+
+This module exports nothing. Side effects only.
+
+## Implementation Notes
+
+The `@testing-library/jest-dom/vitest` entry point automatically calls
+`expect.extend(matchers)` for Vitest's `expect` singleton, which is why no explicit
+`expect.extend` call is needed here. Importing the package root instead (without
+`/vitest`) would attach the matchers to Jest's globals — wrong runtime for this
+package, and a silent no-op under Vitest because the matchers never see the right
+`expect`. The two import order also matters: jest-dom must be loaded before any
+test file executes so the matcher patches are visible when the first test runs.
+Listing this file second in `setupFiles` (after the polyfills bootstrap) preserves
+that order.