Attest
expect(user).toBeDefined() checks the value, but TypeScript doesn't learn anything from it. expect(x) returns a matcher object, and a method on that object can't narrow the x you passed in. So the next line needs a !, a ?., or a cast.
attest is a set of assertions that check a value and narrow its type in one call. initialize returns it, built over your runner's own expect.
Setup
Export it from your setup module with an explicit Attest type:
// 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, expect } = harness;
export const attest: Attest = harness.attest; The annotation is required. TypeScript only narrows through an assertion function when every name in the call has an explicit type, and that includes your own binding. A destructure never qualifies, even with a type annotation, and neither does harness.attest.definite(…). If you get it wrong, the call is a compile error (TS2775), so you can't lose the narrowing without noticing.
One line in the setup module covers every test file that imports it.
Narrowing
import { , , } from "./setup";
type = { : string; ?: { : string } };
declare function (: string): | undefined;
("finds Ada", () => {
const = ("Ada");
.();
(user.).("Ada");
.(.);
(..).("London");
});Members
| member | on success |
|---|---|
definite(value) | narrows value to neither null nor undefined |
definitely(value) | returns value, typed the same way, for use in an expression |
instanceOf(value, Class) | narrows value to an instance of Class |
variant(value, "kind", "err") | narrows a discriminated union to its kind: "err" member |
that(value, isFoo) | narrows value through your own type guard |
throws(Class, () => …) | returns what the function threw, as an instance of Class |
rejects(Class, promise) | resolves to the rejection reason, as an instance of Class |
const error = attest.throws(ParseError, () => parse("{"));
expect(error.line).toBe(1);
attest.variant(event, "kind", "err");
expect(event.message).toBe("timed out");
expect(attest.definitely(users[0]).name).toBe("Ada");definiteonly fails onnullandundefined, so0,"", andfalsepass.definitely,throws, andrejectsreturn their result instead of asserting it, so they work without the annotation, from a plain destructure too.throwscalls the function once, and fails if it returns a promise. Userejectsfor that.rejectstakes a promise, or a function that returns one. A function that throws instead of returning counts as a rejection.- Members that check a value take it first, so
instanceOf(value, Class)reads as the sentence it asserts.throwsandrejectstake the class first, so a long function goes last. - Every member takes an optional last argument,
label, that names the subject in the failure message.
Failures
A failure is your runner's own. Each member first calls the matching matcher (toBeDefined, toBeInstanceOf, toThrow, rejects.toThrow, and so on), so you get the runner's message and diff.
Then it checks again itself, and throws AttestationError if the runner let the value through. That second check is what makes the narrowing safe on a runner whose expect lacks the matcher or doesn't throw.
On Bun, the code excerpt in a failure shows a line inside harness, not your test, because Bun shows the line that threw. The stack trace below it still names your line.
