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.
scopechooses how a testing block follows its body. Left unset, it's"async"wherenode:async_hooksexists and"sync"elsewhere."async"throwsAsyncScopeUnavailableErrorwhere it doesn't exist. See Scope.extensionswiden what this instance accepts as an identity. Defaults to none. See Extensions.
Returns:
| member | what it is |
|---|---|
typed | starts a block whose identity only names its type |
validated | starts a block whose value is checked against a Standard Schema |
effect | starts a block that produces nothing. See Effects |
testing | runs a function as a testing block |
T | makes 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: aT<…>(), a Standard Schema, or an extension's schema.validated.bytakes only a Standard Schema, and throwsInvalidSchemaErrorfor anything else.named(name)names the block. See Named blocks.given(data)passesdatatofn, and records it on the spy. See Given.will(fn)runs the block, and returns its value. Atypedblock returnsfn's value as is. Avalidatedblock always returns a promise, and throwsInvalidDataTypeErrorfor a value that doesn't match. An effect block'sfnreturnsvoidorPromise<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.
| terminal | what 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
| member | what it is |
|---|---|
executions | each call the mock served, in order |
strategy | the terminal that made it: { kind: "substitute", value }, { kind: "passthrough" }, { kind: "produce" }, or { kind: "observe" } |
named | the name it was defined with, if any |
options | the 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.
| error | thrown when |
|---|---|
NotMockedError | a value block in a testing block has no mock |
UnusedMocksError | a testing block ends with a mock that served no call |
DuplicateMockError | a second mock is defined with the same identity and name |
InvalidSchemaError | validated.by is given something that isn't a Standard Schema |
InvalidDataTypeError | a validated block's value doesn't match. Has schema and issues |
IllegalConcurrencyTestingError | two testing blocks overlap under the synchronous scope |
AsyncScopeUnavailableError | scope: "async" is asked for where node:async_hooks doesn't exist |
MockingUnavailableError | harness's mocker is used from a suite hook |
AmbiguousIdentityError | more than one extension accepts an identity. Has extensions |
ExtensionUnavailableError | a block needs an extension's value and no extension can make it |
CleanupFailedError | one or more extension teardowns threw and the block passed. Has errors |
ExtensionFrameResultError | an extension's frame didn't return a generator |
ExtensionFrameSessionError | an extension's frame yielded neither a session nor a wrapper |
ExtensionFrameYieldError | an 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.
