will-call

Credit: This module borrows heavily from the common.mustCall() functionality in Node core's test suite.

will-call allows you to mark functions that should be executed. You can later check which functions were actually called.

const WillCall = require('will-call');
const wc = new WillCall();
const foo = wc.expect(function foo () { return 'foo'; });     // must be called once
const bar = wc.expect(function bar () { return 'bar'; }, 2);  // must be called twice
const baz = wc.expect(function baz () { return 'baz'; });     // must be called once
 
foo();
bar();
baz();
baz();
 
const results = wc.check();
// results contains an array of length two, corresponding to bar() and baz()
// Each entry provides the function name, a stack, expected calls, and actual calls

Methods

will-call exports a constructor function that takes no arguments. Constructed instances support the following methods.

WillCall.prototype.expect(fn [, expected])

• Arguments
  • fn (function) - The function that is expected to be called.
  • expected (integer) - The exact number of times that fn should be called. If a non-negative integer is not received, this defaults to 1. Optional.
• Returns
  • A wrapped version of fn. The wrapped function should behave the same as fn.

This function specifies the exact number of times that a given function is expected to be called. expect() returns a wrapped version of the fn argument. It is important that the wrapped function be used instead of the original fn function.

WillCall.prototype.check()

• Arguments
  • None
• Returns
  • Array of objects. Each object adheres to the following schema.
    • name (string) - The name of the function, or '<anonymous>' if the function doesn't have a name.
    • expected (integer) - The number of times the function was expected to be called.
    • actual (integer) - The number of times the function was actually called.
    • stack (string) - A partial stack trace identifying where the function was passed to expect().

This function verifies that all expected functions were called the correct number of times. check() returns an array identifying the functions that were not called correctly. This function does not alter any internal state, and can be called multiple times.