Why Harness?
Test suites grow per-test plumbing: a transaction opened in beforeEach and rolled back in afterEach, a temp directory shared between them through a let at the top of the file, a seed made up from the test's name. Each piece is copied into every file that needs it, and each one is written a little differently for each runner.
Harness moves that plumbing into integrations. You configure them once, in one setup module, and every test runs inside them.
One setup for every runner
You pass your runner's module to initialize, and it hands back describe, it, expect, and the hooks. They work the same on bun, vitest, jest, mocha, and node:test. Harness imports no runner and has no runtime dependencies, so it adds nothing to your install beyond itself.
The wrapped API is typed from your runner's own types. A modifier your runner doesn't have, like it.failing on vitest, isn't offered. See Runners.
Setup and teardown that line up
An integration's per-test work is one generator with one yield. Everything before it is setup, the test runs at the yield, and everything after it is teardown:
*frame() {
const tx = openTransaction();
try {
yield;
} finally {
tx.rollback();
}
}The finally runs when the test settles, sync or async. A wrapping callback can't promise that: it returns at an async test's first await, so its finally runs in the middle of the test. See Writing integrations.
Context instead of shared variables
What an integration provides reaches the test as its first argument, typed from the integrations you passed:
it("inserts a user", async ({ db }) => {
await db.insert(users).values({ name: "Ada" });
});There's no let at the top of the file for hooks to assign and tests to read, and a test can't see another test's value.
Identity from the test path
Every test has an identity: its describe names, its own name, and its .each row. Integrations derive per-test state from it, like fabricator's per-test data. The identity doesn't depend on which other tests ran or in what order, so .only, filters, sharding, and .concurrent don't change it. See Test identity.
Assertions that narrow
expect(user).toBeDefined() checks the value but doesn't tell TypeScript, so the next line needs a !. attest.definite(user) does both. See Attest.
When not to use it
- You need runner-level hook semantics. Harness runs
beforeEachandafterEachinside the test, so a hook failure is reported as a test failure, and hook time counts against the test's timeout. See Hooks. - You use
donecallbacks. A test body takes the context as its only argument, sodone-style tests aren't supported. - You only use one runner and have no per-test plumbing. Harness doesn't add much over the runner alone.
