Quick start
This page sets up harness on Bun with one small integration. Every other runner works the same way: only the framework import changes.
1. Install
2. Write one setup module
initialize takes your runner's module and a list of integrations, and returns the wrapped describe, it, expect, and hooks. Call it once, in a module every test file imports:
// test/setup.ts
import { initialize, type Attest } from "@ghostry/harness";
import * as framework from "bun:test";
export const harness = initialize({ framework, integrations: [] });
export const { describe, it, test, expect, beforeEach, afterEach } = harness;
export const attest: Attest = harness.attest;The attest line needs its own explicit type for its assertions to narrow. See Attest.
3. Write a test
Import from the setup module instead of from the runner:
// test/math.test.ts
import { describe, expect, it } from "./setup";
describe("add", () => {
it("adds", () => {
expect(1 + 1).toBe(2);
});
});Run it the way you always do (bun test). With no integrations, this behaves like the runner alone.
4. Add an integration
An integration provides values to every test and can run code around each one. This one gives every test a log, and prints it, under the test's name, only when the test fails. Define it in the setup module and pass it to initialize:
// test/setup.ts
import { , type , type } from "@ghostry/harness";
import * as from "bun:test";
const : <{ : string[] }, string[]> = {
: "log",
: { : ({ }) => },
*({ }) {
const : string[] = [];
try {
yield () => ();
} catch () {
.([...., .].(" › "));
.(.("\n"));
throw ;
}
},
};
export const = ({ , : [] });
export const { , , , , , } = ;
export const : = .;providesnames the keys the integration adds to each test's context. Here that'slog.frameruns around each test. The test runs at theyield, and acatcharound it sees the test fail.yield (body) => body(lines)handslinesto the providers, sologis this test's own array.
Every test now receives log as part of its first argument:
// test/checkout.test.ts
import { , , } from "./setup";
("checkout", () => {
("totals the cart", ({ log }) => {
.("adding two items");
(10 + 5).(15);
});
});Each test gets a new array, so one test's lines never show up in another's output. See Writing integrations for everything a frame can do.
Next steps
- Mental model: the order things run in, and what's in a test's context.
- Hooks: how
beforeEachandafterEachdiffer from the runner's own. - Fabricator's integration: per-test data from each test's identity.
