first commit

docs/testkit/testing/testing-dom/src/runner/bun-test.md

@@ -0,0 +1,62 @@
+# runner/bun-test
+
+## Purpose
+
+The `runner/bun-test` module re-exports bun-test's primitives (`describe`, `it`, `test`, `expect`, `beforeAll`, `beforeEach`, `afterAll`, `afterEach`, `mock`) under the same stable alias the `runner/vitest` module uses. Together they make `@suaveplan/testing-dom/runner` a dual-runner entry point — consumer test files that import from here run unchanged under either vitest (via `bunx vitest`) or bun-test (via `bun test`).
+
+## Features
+
+- Re-exports the bun-test assertion + lifecycle API
+- Uses `bun:test` specifier — resolved at runtime by Bun, excluded from vitest builds
+- Conditional export — package.json's `exports` picks this module under the `bun` condition
+
+## Usage: Basic Example
+
+```ts
+import { describe, it, expect } from "@suaveplan/testing-dom/runner";
+
+describe("same test file, either runner", () => {
+    it("asserts", () => {
+        expect(1 + 1).toBe(2);
+    });
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+    describe,
+    it,
+    expect,
+    beforeAll,
+    afterAll,
+    mock,
+} from "@suaveplan/testing-dom/runner";
+
+describe("bun-test specific mocks", () => {
+    let server: { close: () => void };
+    beforeAll(() => {
+        server = startHttpStub(3000);
+    });
+    afterAll(() => server.close());
+
+    it("mocks a module method", () => {
+        const fetchStub = mock<typeof fetch>(() => Promise.resolve(new Response("ok")));
+        // ... use fetchStub
+        expect(fetchStub).toHaveBeenCalled();
+    });
+});
+```
+
+## API Reference
+
+Re-exports: `describe`, `it`, `test`, `expect`, `beforeAll`, `beforeEach`, `afterAll`, `afterEach`, `mock`.
+
+## Implementation Notes
+
+The module imports from `"bun:test"`, which resolves only in Bun; under vitest it's excluded from the bundle via vite's external-module configuration AND via the package's coverage-exclude list (since the file is never executed under vitest). Mocking APIs differ between the two runners: bun-test's `mock` returns a different shape than vitest's `vi.fn`. Consumers who need both runners' test files to type-check should stick to the lowest-common-denominator API — `describe`, `it`, `expect`, and lifecycle hooks — and branch on `detectRunner()` for anything beyond that.
+
+### Integration
+
+The Bun-test runner shim exposes `describe` / `it` / `beforeEach` / `afterEach` / `expect` bindings that mirror Vitest's API so test files can be written once and run in either runner. The shim installs the jest-dom matchers via `registerMatchers` on module load and sets up happy-dom as the default DOM host when the test file imports from `@suaveplan/testing-dom/runner/bun-test`.