Mental model
Harness has four parts: the wrapped API that initialize returns, the integrations you pass it, the context each test receives, and the identity each test has.
initialize wraps your runner
const harness = initialize({ framework, integrations: [a, b] });framework is your runner's module, passed in, not imported by harness. initialize returns:
describe,it, andtest(itandtestare the same function), with the modifiers your runner has, plus.each.beforeEachandafterEach, which harness runs itself, andbeforeAllandafterAllwhen your runner has them.expect, your runner's own, bound so it survives a destructure.attest, assertions that narrow types. See Attest.framework, the unchanged module, for anything harness doesn't wrap.
initialize checks the integrations right away. Two integrations that provide the same key, a key like __proto__, or the key row (which .each uses) throw there, not at the first test.
Integrations run around each test
An integration is an object with a name, a provides map, and an optional frame:
const integration = {
name: "db",
provides: { db: ({ established }) => established },
*frame() {
// setup
yield (body) => withTransaction((tx) => body(tx));
// teardown
},
};provides lists the keys the integration adds to each test's context, and how to make each one. It is the only place those keys are named. frame is setup, the test, and teardown in one generator. See Writing integrations.
Integrations apply outside in. The first one in the list is the outermost: its setup runs first, and its teardown runs last.
The order a test runs in
For each test, harness runs:
- Each integration's setup, up to its
yield, outermost first. beforeEachhooks, outermostdescribefirst.- The test body.
afterEachhooks, innermostdescribefirst.- Each integration's teardown, after its
yield, innermost first.
afterEach runs even when a beforeEach or the body threw, and teardown runs even when an afterEach threw. beforeAll and afterAll run on their own, outside any test. See Hooks.
The context
A test body gets one argument, the context. It holds every integration's keys merged into one object:
it("works", ({ db, log }) => { … });- Each test gets a new context object. Hooks and the body share it, so a
beforeEachcan add a key of its own for the body to read. - The keys that integrations provide are read-only, in the types and at runtime. Reassigning one would only change this test's copy, so it isn't allowed.
- Read-only is shallow. An integration's own value, like a
string[]log, is still yours to change. - An
.eachtest also getsrow. See .each.
Identity
Every test and hook has an identity:
type Identity = {
kind: "test" | "suite";
path: string[]; // enclosing describe names, outermost first
name: string; // the test's name, "" for beforeAll and afterAll
row: number | undefined; // the .each row, from 0
};frame and every provider receive it. It comes from where the test was declared, not from the file or the order tests ran in. See Test identity.
