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

import { detectRunner } from "@suaveplan/testing-dom/config";

const runner = detectRunner();
if (runner === "bun-test") {
    // Use bun:test APIs
}

Usage: Advanced Example

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.

2.2 KiB Raw Blame History