Skip to content
Logo

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.

  • framework is the runner's module. It needs describe, it, and expect, and harness uses test, beforeAll, afterAll, and the modifiers when it has them. See Runners.
  • integrations run 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:

memberwhat it is
describethe wrapped describe, with the runner's modifiers and .each
it, testthe wrapped it, one function under two names
beforeEach, afterEachhooks run inside each test. See Hooks
beforeAll, afterAllthe runner's, with a suite identity. Present when the runner has them
expectthe runner's own expect, bound
attestassertions that narrow. See Attest
frameworkthe 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.

errorthrown whenfields
HarnessError.IntegrationKeyCollisionErrortwo integrations provide the same keykey, first, second
HarnessError.PrototypePollutionErrora key is __proto__, constructor, or prototypekey, integration
HarnessError.ReservedContextKeyErrora key is rowkey, integration
HarnessError.EachTableErroran .each table can't produce rowsreason, detail
HarnessError.ModifierUnsupportedErrora *If modifier has no runner modifier to usemodifier, wanted
HarnessError.AmbientHookErrorbeforeEach or afterEach is called with no suitehook
HarnessError.AsyncDescribeErroran async describe callback doesn't take its scopesuite
HarnessError.IntegrationFrameResultErrorframe returns something other than a generatorintegration, received
HarnessError.IntegrationFrameWrapperErrorframe yields something other than a functionintegration, received
HarnessError.IntegrationFrameYieldErrorframe yields more than onceintegration
HarnessError.ConformanceErrorthe runner fails a conformance checkcheck, expected, actual
HarnessError.AttestationErroran attest check fails and the runner's expect didn't throwattestation, 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

typewhat 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
AnyIntegrationthe bound every entry of integrations satisfies
TestContext<Integrations>the merged, read-only context a test body receives
RemapOptions, Remapping, RemapArgsremap's argument, its provides map, and what each new provider receives

Naming the wrapped API

typewhat it is
Frameworkwhat a runner module has to have
InitializeOptions, Initializedinitialize's argument and return value
DescribeSurface, TestSurfacethe wrapped describe and it, typed from the runner
DescribeFn, TestFnthe plain call of each
DescribeEach, TestEach.each on each
SuiteScopewhat a describe callback receives
HookSurface, HookBody, TestHookFn, SuiteHookFnthe four hooks, and what each takes
Attestthe type to annotate your attest binding with
OptionalBodyTestSurface, OptionalBodyTestFn, OptionalBodyTestEachit.skip and it.todo, where the body is optional
OptionalCallbackDescribeSurface, OptionalCallbackDescribeFn, OptionalCallbackDescribeEachdescribe.todo, where the callback is optional
AnyFnany function