Installation
Extern is ESM only and has no runtime dependencies. Install it as a regular dependency, since your source code imports it:
It's also published to JSR.
Requirements
- Bun, Node, or Deno for async testing blocks. A browser bundle works too, but runs one synchronous testing block at a time. See Scope.
- Any test runner. Extern doesn't depend on one, and
extern.testingis a plain function you call inside a test. - TypeScript is not required, but it is strongly recommended. It's what checks each mock against the type of the block it replaces. Extern's types need TypeScript 5.0 or later, and
@ghostry/extern-extension-fabricator-v0needs 5.4 or later, as fabricator does.
Scope
A testing block has to stay active across every await in its body, so that a block reached after an await still finds its mock. On Bun, Node, and Deno, extern uses node:async_hooks for this, and concurrent testing blocks don't see each other's mocks.
Anywhere without node:async_hooks, extern falls back to a synchronous scope. A synchronous body works there, and running two testing blocks at once throws IllegalConcurrencyTestingError.
initialize takes a scope to choose instead:
initialize({ scope: "async" }); // throws AsyncScopeUnavailableError without node:async_hooks
initialize({ scope: "sync" }); // one testing block at a time, on any runtimeLibraries that work with extern
- harness runs every test inside a testing block. Its integration is
@ghostry/extern/harnessing, part of this package. See Harness. - fabricator schemas can be block identities that produce their own values, through
@ghostry/extern-extension-fabricator-v0. See Extensions.
