Harness
Harness wraps your test runner so libraries can run code around every test. Extern's integration, @ghostry/extern/harnessing, makes every test body a testing block, and puts its mocker on the test context.
Setup
Pass integration(extern) to harness's initialize, in your test setup module:
// test/setup.ts
import { integration } from "@ghostry/extern/harnessing";
import { initialize } from "@ghostry/harness";
import * as framework from "bun:test";
import { extern } from "../src/extern";
export const { describe, it, expect, beforeAll, beforeEach, framework } =
initialize({ framework, integrations: [integration(extern)] });Extern doesn't depend on harness. Install both:
Writing tests
Every test receives extern.mock:
("reads the forecast", ({ : { } }) => {
const = ().({ : 3, : -2 });
(("Oslo").).(-2);
(.).(1);
});There's no extern.testing and no await around the body: the testing block is already open, and a synchronous test stays synchronous. Mocks are checked when the test ends, so an unused one fails it.
Every test is now a testing block
Weigh this before adopting it. Outside a testing block, a block runs its function. With the integration installed, there is no outside: every test that reaches a value block needs a mock for it, or fails with NotMockedError. The first tests to fail are the ones nobody thinks of as extern tests.
There are two ways out. skip() lets one block run its function in one test, and still records it:
it("calls the real service", ({ extern: { mock } }) => {
mock(Forecast).skip();
// ...
});The runner's own it, framework.it, runs a test with no integrations at all:
import { framework } from "./setup";
framework.it("is not a testing block", () => {
// blocks run their functions here
});Hooks
beforeEach and afterEach run inside the testing block, around the body. A mock defined in a beforeEach is live for the test, and an afterEach can read its spies:
describe("packing", () => {
beforeEach(({ extern: { mock } }) => {
mock(Forecast).with({ high: 3, low: -2 }, { unused: "allow" });
});
});A mock from a beforeEach counts toward every test's unused-mock check, so give it { unused: "allow" } unless every test in the describe uses it.
beforeAll and afterAll run outside any testing block, so blocks reached from them run their functions. Using the mocker there throws MockingUnavailableError, since each test opens its own testing block and a mock defined beforehand could never reach one. A suite hook that needs mocks opens a testing block itself:
beforeAll(() => {
extern.testing((mock) => {
mock(Forecast).with({ high: 3, low: -2 });
seed();
});
});See harness's Hooks for when each hook runs.
With other integrations
Integrations apply outside in, the first one outermost:
initialize({
framework,
integrations: [fabricatorIntegration(fabricator), integration(extern)],
});An extension's scope, like fabricator's, opens inside the testing block, so the order decides which integration's scope encloses the other's. Both orders work and stay deterministic, but they give different generated values, so pick one and keep it. Registering extern last is what these docs do. See fabricator's Extern guide.
Under scope: "sync"
The synchronous scope allows one testing block at a time. With every test a testing block, concurrent tests throw IllegalConcurrencyTestingError, and so does an extern.testing written inside a test.
Under the default scope, an extern.testing inside a test is allowed, but its body sees only its own mocks, none of the test's.
