first commit

docs/testkit/testing/testing-dom/src/config/detect-runner.md

@@ -0,0 +1,60 @@
+# detect-runner
+
+## Purpose
+
+`detectRunner` tells the caller whether the currently-executing process is vitest or bun-test. It's used by the runner-adapter module to pick the right implementation of `describe`/`it`/`expect` at runtime when a test file wants to be dual-runner. Since vitest and bun-test expose slightly different globals, consumers either import the detected runner's API from this package or branch on the returned string.
+
+## Features
+
+- Pure probe of `globalThis` / environment variables
+- Three possible outcomes: `"vitest"`, `"bun-test"`, `"unknown"`
+- Safe to call outside any test context — returns `"unknown"` rather than throwing
+- Deterministic under a single runner — no heuristics that flip between runs
+
+## Usage: Basic Example
+
+```ts
+import { detectRunner } from "@suaveplan/testing-dom/config";
+
+const runner = detectRunner();
+if (runner === "bun-test") {
+    // Use bun:test APIs
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import { detectRunner } from "@suaveplan/testing-dom/config";
+
+// A shared test-helper module that branches on runner.
+export function useHelper(): unknown {
+    const runner = detectRunner();
+    switch (runner) {
+        case "vitest":
+            return loadVitestHelper();
+        case "bun-test":
+            return loadBunTestHelper();
+        case "unknown":
+            throw new Error(
+                "useHelper() called outside a supported test runner"
+            );
+    }
+}
+```
+
+## API Reference
+
+### `detectRunner(): TestRunner`
+
+Returns one of:
+
+- `"vitest"` — detected via `import.meta.vitest` or vitest-owned globals
+- `"bun-test"` — detected via bun's `Bun.version` + `process.env.BUN_TEST`
+- `"unknown"` — neither was detected
+
+### `type TestRunner = "vitest" | "bun-test" | "unknown"`
+
+## Implementation Notes
+
+Detection reads multiple signals for each runner to remain robust against future runtime changes — relying on a single global is fragile. The function never reads from disk or spawns a child process, so it's safe to call at module-top during config import. For test files that want to statically import one runner's API, prefer importing `@suaveplan/testing-dom/runner` (which internally calls `detectRunner`) over writing the branch manually.