first commit

docs/testkit/testing/testing-dom/src/runner/vitest.md

@@ -0,0 +1,71 @@
+# runner/vitest
+
+## Purpose
+
+The `runner/vitest` module re-exports vitest's `describe`, `it`, `test`, `expect`, `beforeAll`, `beforeEach`, `afterAll`, `afterEach`, and `vi` under a stable alias. It's part of the dual-runner support in `@suaveplan/testing-dom` — consumers who want their test files to run under both vitest and bun-test can import from `@suaveplan/testing-dom/runner` instead of picking one directly. At type-check time this module statically resolves to vitest's types.
+
+## Features
+
+- Re-exports the vitest assertion + lifecycle API
+- Preserves upstream types — TS jumps to vitest's definitions
+- Conditional export — package.json's `exports` picks this module under the `vitest` condition
+
+## Usage: Basic Example
+
+```ts
+import { describe, it, expect } from "@suaveplan/testing-dom/runner";
+
+describe("my suite", () => {
+    it("asserts", { timeout: 5000 }, () => {
+        expect(1 + 1).toBe(2);
+    });
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { describe, it, expect, beforeEach, vi } from "@suaveplan/testing-dom/runner";
+
+describe("mockable dependency", () => {
+    let clock = 0;
+    beforeEach(() => {
+        clock = 0;
+    });
+
+    it("uses fake timers", { timeout: 5000 }, () => {
+        vi.useFakeTimers();
+        try {
+            const inner = vi.fn((n: number) => ++clock);
+            inner(1);
+            inner(1);
+            expect(inner).toHaveBeenCalledTimes(2);
+            expect(clock).toBe(2);
+        } finally {
+            vi.useRealTimers();
+        }
+    });
+});
+```
+
+## API Reference
+
+Re-exports: `describe`, `it`, `test`, `expect`, `beforeAll`, `beforeEach`, `afterAll`, `afterEach`, `vi`.
+
+## Implementation Notes
+
+The re-export is unconditional because the module is only reachable via the `vitest` condition in `package.json#exports`. If the condition machinery is bypassed (e.g. the import is resolved manually), vitest must still be available as a peer of the consumer — this module does not install vitest or provide its own assertion library.
+
+### Integration
+
+The Vitest runner shim re-exports `describe` / `it` / `beforeEach` / `afterEach` / `expect` from `vitest` and installs the jest-dom matcher set via `registerMatchers` on module load. Importing this module is sufficient for a Vitest file to use the full DOM-matcher surface — no manual matcher wiring needed.
+
+## Further Usage: Basic Example
+
+```ts
+import { it, expect, render } from "@suaveplan/testing-dom/runner/vitest";
+it("renders hello", { timeout: 5000 }, () => {
+    const { getByText } = render(<h1>Hello</h1>);
+    expect(getByText("Hello")).toBeInTheDocument();
+});
+```