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