Skip to content
Logo

Public API

The package has two entry points:

  • @ghostry/extern: initialize, T, the error classes, and the types for writing extensions.
  • @ghostry/extern/harnessing: integration, harness's integration. See Harness.

initialize(config?)

function initialize(config?: {
  scope?: "async" | "sync";
  extensions?: Extension[];
}): Initialized;

Makes an instance. Call it once, in a module your source and tests both import. See Quick start.

  • scope chooses how a testing block follows its body. Left unset, it's "async" where node:async_hooks exists and "sync" elsewhere. "async" throws AsyncScopeUnavailableError where it doesn't exist. See Scope.
  • extensions widen what this instance accepts as an identity. Defaults to none. See Extensions.

Returns:

memberwhat it is
typedstarts a block whose identity only names its type
validatedstarts a block whose value is checked against a Standard Schema
effectstarts a block that produces nothing. See Effects
testingruns a function as a testing block
Tmakes a type-only identity, the same function as the T export

Blocks

extern.typed.by(identity).named(name).given(data).will(fn);
extern.validated.by(schema).named(name).given(data).will(fn);
extern.effect.named(name).given(data).will(fn);
extern.effect.will(fn);

named and given are optional, and come in this order. On an effect block, given needs named.

  • by(identity) sets the identity: a T<…>(), a Standard Schema, or an extension's schema. validated.by takes only a Standard Schema, and throws InvalidSchemaError for anything else.
  • named(name) names the block. See Named blocks.
  • given(data) passes data to fn, and records it on the spy. See Given.
  • will(fn) runs the block, and returns its value. A typed block returns fn's value as is. A validated block always returns a promise, and throws InvalidDataTypeError for a value that doesn't match. An effect block's fn returns void or Promise<void>.

T<Type>()

function T<Type>(): T<Type>;

Returns a new identity whose only content is Type. Each call returns a different identity. See Values.

extern.testing(fn)

function testing<Return>(fn: (mock: Mocker) => Return): Return;

Runs fn as a testing block, and returns its value unchanged: a synchronous fn stays synchronous. Throws UnusedMocksError when fn finishes with a mock that served no call.

mock(identity)

The mocker. Each terminal takes an optional last argument, { unused: "allow" }, and returns a spy.

terminalwhat matching blocks do
with(value)return value. Alias: substitute
skip()run their function. Alias: passthrough
produce(callback?)return a value their extension produces. Only for identities an extension accepts. See Extensions
named(name).<terminal>the same, for blocks with that name only

mock.effect.named(name) targets effect blocks, with two terminals: observe(), which records calls and doesn't run them, and passthrough(), which records calls and runs them. See Effects.

Defining a second mock with the same identity and name throws DuplicateMockError.

Spies

memberwhat it is
executionseach call the mock served, in order
strategythe terminal that made it: { kind: "substitute", value }, { kind: "passthrough" }, { kind: "produce" }, or { kind: "observe" }
namedthe name it was defined with, if any
optionsthe options it was defined with

An execution has mode, named and given when the block had them, and, for a value block, outcome: { kind: "returned", value } or { kind: "threw", error }.

integration(extern)

import { integration } from "@ghostry/extern/harnessing";
 
function integration(extern: Initialized): Integration;

Returns a harness integration that runs every test body inside one testing block, and provides extern.mock on the test context. Suite hooks aren't framed, and using the mocker from one throws MockingUnavailableError. See Harness.

Errors

Every error extends ExternError.

errorthrown when
NotMockedErrora value block in a testing block has no mock
UnusedMocksErrora testing block ends with a mock that served no call
DuplicateMockErrora second mock is defined with the same identity and name
InvalidSchemaErrorvalidated.by is given something that isn't a Standard Schema
InvalidDataTypeErrora validated block's value doesn't match. Has schema and issues
IllegalConcurrencyTestingErrortwo testing blocks overlap under the synchronous scope
AsyncScopeUnavailableErrorscope: "async" is asked for where node:async_hooks doesn't exist
MockingUnavailableErrorharness's mocker is used from a suite hook
AmbiguousIdentityErrormore than one extension accepts an identity. Has extensions
ExtensionUnavailableErrora block needs an extension's value and no extension can make it
CleanupFailedErrorone or more extension teardowns threw and the block passed. Has errors
ExtensionFrameResultErroran extension's frame didn't return a generator
ExtensionFrameSessionErroran extension's frame yielded neither a session nor a wrapper
ExtensionFrameYieldErroran extension's frame yielded twice

Types

From @ghostry/extern:

  • Configuration: Configuration, Options.
  • Identities: Identity, AnyIdentity, T.
  • Mocking: Mocker, Spy, Execution.
  • Extensions: Extension, TypeLambda, HandleLambda, Apply, HandleOf, LambdaOf, Produce, Session, Frame, Wrapper, Outcome. See Writing extensions.

From @ghostry/extern/harnessing: Integration, ExternTestContext, Mocking, Established, Provider, ProviderArgs, Provides.