Public API
The package has two entry points:
@ghostry/harness:initialize,remap,HarnessError, and the types for writing integrations and naming the wrapped API.@ghostry/harness/conformance:conformance, the suite that checks a runner.
initialize(options)
function initialize(options: {
framework: Framework;
integrations?: Integration[];
}): Initialized;Wraps a runner. Call it once, in a setup module every test file imports. See Quick start.
frameworkis the runner's module. It needsdescribe,it, andexpect, and harness usestest,beforeAll,afterAll, and the modifiers when it has them. See Runners.integrationsrun around every test, the first one outermost. Defaults to none.
Throws IntegrationKeyCollisionError, PrototypePollutionError, or ReservedContextKeyError when an integration's keys can't be used. See Key checks.
Returns:
| member | what it is |
|---|---|
describe | the wrapped describe, with the runner's modifiers and .each |
it, test | the wrapped it, one function under two names |
beforeEach, afterEach | hooks run inside each test. See Hooks |
beforeAll, afterAll | the runner's, with a suite identity. Present when the runner has them |
expect | the runner's own expect, bound |
attest | assertions that narrow. See Attest |
framework | the unchanged runner module |
A test body, hook, or .each body gets one argument, the context: every integration's keys, read-only, plus row in an .each test.
remap(integration, options)
function remap(
integration: Integration,
options: {
name?: string;
provides: { [key: string]: (args: RemapArgs) => unknown };
},
): Integration;Returns an integration that provides the keys in options.provides instead of the wrapped one's. Each provider gets provided (the wrapped integration's context), identity, and established. name defaults to the wrapped integration's name. See Remap.
conformance(framework)
import { conformance } from "@ghostry/harness/conformance";
function conformance(framework: Framework): void;Registers a suite that checks the runner. Call it at the top of its own test file. See Conformance.
HarnessError
Every error harness throws is a subclass of HarnessError, so instanceof HarnessError catches them all. Each message stands on its own, and the fields are there for code that needs them.
| error | thrown when | fields |
|---|---|---|
HarnessError.IntegrationKeyCollisionError | two integrations provide the same key | key, first, second |
HarnessError.PrototypePollutionError | a key is __proto__, constructor, or prototype | key, integration |
HarnessError.ReservedContextKeyError | a key is row | key, integration |
HarnessError.EachTableError | an .each table can't produce rows | reason, detail |
HarnessError.ModifierUnsupportedError | a *If modifier has no runner modifier to use | modifier, wanted |
HarnessError.AmbientHookError | beforeEach or afterEach is called with no suite | hook |
HarnessError.AsyncDescribeError | an async describe callback doesn't take its scope | suite |
HarnessError.IntegrationFrameResultError | frame returns something other than a generator | integration, received |
HarnessError.IntegrationFrameWrapperError | frame yields something other than a function | integration, received |
HarnessError.IntegrationFrameYieldError | frame yields more than once | integration |
HarnessError.ConformanceError | the runner fails a conformance check | check, expected, actual |
HarnessError.AttestationError | an attest check fails and the runner's expect didn't throw | attestation, label, expected, actual, cause |
EachTableError's reason is "shape" (not an array or a tagged template), "empty" (no rows), or "incomplete" (a template row missing a cell).
Types
Writing an integration
| type | what it is |
|---|---|
Integration<Context, Established> | { name, provides, frame? }. See Writing integrations |
Provides<Context, Established> | the provides map: one Provider per key of Context |
Provider<Value, Established> | (args: ProviderArgs) => Value |
ProviderArgs<Established> | { identity, established } |
FrameArgs | { identity }, what frame receives |
Frame<Established> | the generator frame returns: one yield, of a Wrapper or nothing |
Wrapper<Established> | (body) => body(established), run the test inside a scope |
Identity | { kind, path, name, row }. See Test identity |
AnyIntegration | the bound every entry of integrations satisfies |
TestContext<Integrations> | the merged, read-only context a test body receives |
RemapOptions, Remapping, RemapArgs | remap's argument, its provides map, and what each new provider receives |
Naming the wrapped API
| type | what it is |
|---|---|
Framework | what a runner module has to have |
InitializeOptions, Initialized | initialize's argument and return value |
DescribeSurface, TestSurface | the wrapped describe and it, typed from the runner |
DescribeFn, TestFn | the plain call of each |
DescribeEach, TestEach | .each on each |
SuiteScope | what a describe callback receives |
HookSurface, HookBody, TestHookFn, SuiteHookFn | the four hooks, and what each takes |
Attest | the type to annotate your attest binding with |
OptionalBodyTestSurface, OptionalBodyTestFn, OptionalBodyTestEach | it.skip and it.todo, where the body is optional |
OptionalCallbackDescribeSurface, OptionalCallbackDescribeFn, OptionalCallbackDescribeEach | describe.todo, where the callback is optional |
AnyFn | any function |
