Writing integrations
An integration is an object with three members:
type Integration<Context, Established = void> = {
name: string;
provides: { [Key in keyof Context]: (args) => Context[Key] };
frame?(args: { identity: Identity }): Generator | AsyncGenerator;
};nameappears in error messages.providesmaps each context key to a function that makes its value for one test.frameruns around each test. It's optional.
Integrations don't import harness to satisfy this shape, so a library can ship one without depending on harness at all. Import the Integration type when you want the checking.
provides
Each provider runs once per test, and receives the test's identity and what the frame's wrapper established (below):
const seed: Integration<{ seed: string }> = {
name: "seed",
provides: {
seed: ({ identity }) => [...identity.path, identity.name].join("/"),
},
};An integration with no frame is just provides. Its keys still reach every test.
frame
frame is the whole per-test lifecycle as one generator with one yield. Setup runs before the yield, the test runs at it, and teardown runs after it:
const timing: Integration<{}> = {
name: "timing",
provides: {},
*frame({ identity }) {
const start = performance.now();
try {
yield;
} finally {
console.log(identity.name, performance.now() - start);
}
},
};Teardown runs when the test settles: when a sync test returns, or when an async test's promise resolves or rejects. So a try/finally around the yield means what it looks like, and a try/catch around it sees the test's error. The test still fails with that error whether or not the frame rethrows it, so a catch can't hide a failure.
A generator, not a callback, because a callback that wraps the test returns at an async test's first await. Its finally would run in the middle of the test. Only yield both runs the test and waits for it.
Async setup and teardown
Use async *frame() when setup or teardown needs await:
async *frame() {
const server = await startServer();
try {
yield;
} finally {
await server.close();
}
}A synchronous generator can't wait for its teardown. An async frame makes every test that uses it async, including sync ones.
Async setup and teardown should wait on I/O or promises, not on setTimeout. With fake timers installed, a timer never fires, and on Bun that hangs the whole run rather than failing the test.
Running the test inside something
Some things only work inside a callback: an AsyncLocalStorage scope, a library's own wrap, a connection from a pool. To run the test inside one, yield a wrapper. It takes the test as body, calls it once inside the scope, and returns what body returned:
const db: Integration<{ db: Transaction }, Transaction> = {
name: "db",
provides: { db: ({ established }) => established },
*frame() {
yield (body) => pool.transaction((tx) => body(tx));
},
};What the wrapper passes to body reaches the providers as established, so a provider can return the thing the wrapper just opened. The second type parameter of Integration is its type.
Code before the yield runs before the wrapper does, so it's outside the scope. Setup that has to be inside goes in the wrapper. Teardown after the yield runs inside it, so an AsyncLocalStorage value the wrapper set is still readable in the finally.
Yield exactly once
Harness rejects a frame it can't run as written, rather than letting the test pass without it:
- A
framethat returns something other than a generator throwsIntegrationFrameResultError. This catches a frame written as a plain callback. - A
yieldwith a value that isn't a function throwsIntegrationFrameWrapperError. Values for the test go inprovides, not in theyield. - A second
yieldthrowsIntegrationFrameYieldError. There's one test, so there's oneyield.
Order across integrations
Integrations apply outside in, in the order you list them. Each frame encloses the next, so setup runs first to last, and teardown runs last to first. An outer async teardown waits for an inner one, with nothing for you to order.
beforeEach and afterEach run inside every frame, so a scope a wrapper opens is live in both.
Errors in teardown
When teardown throws, the error is always logged. It's also thrown, failing the test, if the test itself passed. A failing test reports its own error, not the teardown's.
Key checks
initialize checks every integration's provides keys before any test runs, and throws:
IntegrationKeyCollisionErrorwhen two integrations provide the same key. Useremapto rename one.PrototypePollutionErrorfor__proto__,constructor, orprototype.ReservedContextKeyErrorforrow, which.eachsets itself.
