Skip to content
Logo

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.testing is 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-v0 needs 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 runtime

Libraries 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.