# 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.