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

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

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.

2.6 KiB Raw Blame History