Mocking
Mocks are defined inside a testing block, and last until it ends:
await extern.testing(async (mock) => {
const spy = mock(Forecast).with({ high: 3, low: -2 });
// ...
});extern.testing returns its body's value, so a synchronous body needs no await. A test can open as many testing blocks as it likes, and each starts with no mocks.
Substituting a value
with(value) makes every block with that identity return value instead of running. The value must match the identity's type. substitute is the same terminal under a longer name.
mock(Forecast).with({ high: 3, low: -2 });A mock's value is returned as given, even in a validated block, where TypeScript's check is the only one.
Running the real function
skip() lets the block run its function, while the spy still records each call. passthrough is the same terminal.
mock(Forecast).skip();Use it when one test needs the real call, like a test against a local server.
Every value block needs a mock
Inside a testing block, a value block with no mock throws NotMockedError, even when the test would otherwise pass. A test can't reach an external system unless it says so with skip().
Effect blocks are the exception: an unmocked effect block doesn't run, and doesn't throw. See Effects.
Every mock must be used
When a testing block ends, a mock that served no call throws UnusedMocksError. A test's mocks list what it actually needs, and a mock left over from a refactor fails instead of lingering.
To allow one mock to go unused, pass { unused: "allow" } as the last argument of its terminal:
const spy = mock(Forecast).with({ high: 3, low: -2 }, { unused: "allow" });
expect(await packFor("Oslo", { offline: true })).toBe("a jacket");
expect(spy.executions).toHaveLength(0);That's also how a test asserts a block did not run. Every terminal takes the option, skip({ unused: "allow" }) included.
UnusedMocksError is thrown only when the body finished. A body that throws reports its own error.
Named blocks
Every block with an identity shares that identity's mock. When a test reaches two blocks with one identity and needs different values from them, name the blocks:
export const today = (city: string) =>
extern.typed
.by(Forecast)
.named("today")
.will(() => fetchForecast(city, 0));
export const tomorrow = (city: string) =>
extern.typed
.by(Forecast)
.named("tomorrow")
.will(() => fetchForecast(city, 1));and name their mocks to match:
mock(Forecast).named("today").with({ high: 20, low: 12 });
mock(Forecast).named("tomorrow").with({ high: 9, low: 2 });A named mock is used only for a block with that name. An unnamed mock is used for every block with the identity, named or not, unless a named mock matches first:
mock(Forecast).with({ high: 15, low: 8 }); // tomorrow, and any unnamed block
mock(Forecast).named("today").with({ high: 20, low: 12 }); // todayAn unnamed block can only use an unnamed mock. With only mock(Forecast).named("today") defined, an unnamed Forecast block throws NotMockedError.
Two mocks with the same identity and the same name, or two unnamed mocks of one identity, throw DuplicateMockError as soon as the second is defined.
Reading a spy
Every terminal returns a spy. Its executions lists each call the mock served, in order:
const spy = mock(Forecast).with({ high: 3, low: -2 });
await packFor("Oslo");
spy.executions[0];
// { mode: "typed", given: "Oslo", outcome: { kind: "returned", value: { high: 3, low: -2 } } }Each execution has:
mode:"typed","validated", or"effect".named: the block's name, when it has one.given: the block'sgivendata, when it has some. See Given.outcome:{ kind: "returned", value }, or{ kind: "threw", error }when the block threw. Extern always rethrows the error, so the record is only for assertions.
Under typed, an async block's value is the promise it returned.
Nested testing blocks
Under the default scope, a testing block opened inside another one replaces it until it ends: blocks inside see only the inner block's mocks, and none of the outer one's. Under scope: "sync", a nested or concurrent testing block throws IllegalConcurrencyTestingError.
