first commit

docs/ui/react/react-midi/src/test-setup.md

@@ -0,0 +1,62 @@
+# `test-setup`
+
+## Purpose
+
+Per-package Vitest bootstrap loaded via `setupFiles` before the first
+test in a worker runs. Its only job is to register a single
+`afterEach` hook that calls React Testing Library's `cleanup()`, so
+the DOM is wiped between tests and `screen.getByText` does not pick
+up stale nodes from a previous test's render tree. The default RTL
+auto-cleanup only fires when `globalThis.afterEach` is exposed,
+which is not the case under Vitest's `globals: false` configuration
+the rest of the project runs with.
+
+This file is intentionally tiny — it is not a production module and
+is excluded from the coverage report. It exists alongside the package
+source so the test runner's setup path is co-located with the tests
+themselves rather than buried inside a separate `tests/` tree.
+
+## Features
+
+- One `afterEach` registration via `@suaveplan/testing/runner`.
+- Single side-effect import; safe to load multiple times per worker.
+- Excluded from coverage, types output, and runtime bundles.
+
+## Usage: Basic
+
+```ts
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+export default defineConfig({
+    test: {
+        setupFiles: [
+            "@suaveplan/testing/polyfills",
+            "./src/test-setup.ts",
+        ],
+    },
+});
+```
+
+## Usage: Advanced
+
+```ts
+// To add extra per-test cleanup logic, append more afterEach hooks:
+import { afterEach } from "@suaveplan/testing/runner";
+
+afterEach(() => {
+    // Reset any module-level state captured by tests.
+});
+```
+
+## API Reference
+
+This module exports nothing — it is a side-effect bootstrap. The
+single registration is `afterEach(cleanup)` where `cleanup` is the
+function exported by `@testing-library/react`.
+
+## Implementation Notes
+
+The cleanup hook is registered at module load time, not lazily — so
+the first import of this module in a worker is the moment the cleanup
+contract is honoured. Subsequent imports are no-ops because Vitest
+deduplicates `setupFiles` per worker.