Skip to content
Logo

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, and test (it and test are the same function), with the modifiers your runner has, plus .each.
  • beforeEach and afterEach, which harness runs itself, and beforeAll and afterAll when 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:

  1. Each integration's setup, up to its yield, outermost first.
  2. beforeEach hooks, outermost describe first.
  3. The test body.
  4. afterEach hooks, innermost describe first.
  5. 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 beforeEach can 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 .each test also gets row. 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.