@tapjs/intercept

A default tap plugin for doing object/global property/method
interception and observing. These are sometimes refered to as
"spy" or "mock" methods (though the term "mock" is extremely
overloaded, and in tap is usually used to refer to dependency
injection mocking).

Usage

 import t from 'tap'

const functionThatLogs = (n: number) => {
  console.log('the number is', n)
}

t.test('some child test', t => {
  // track console.log calls
  const results = t.capture(console, 'log')
  functionThatLogs(10)
  functionThatLogs(5)
  // results() returns the list of what was called, and resets
  // the store.
  t.match(results(), [
    { args: ['the number is', 10], returned: undefined },
    { args: ['the number is', 5], returned: undefined },
  ])
  functionThatLogs(1)
  t.match(results(), [
    { args: ['the number is', 1], returned: undefined },
  ])
  // when the test ends, the original is restored
  t.end()
})

t.test('capture with an implementation', t => {
  const results = t.capture(console, 'log', () => {
    throw new Error('thrown from stub')
  })
  t.throws(
    () => {
      functionThatLogs(3)
    },
    { message: 'thrown from stub' }
  )
  t.match(results(), { args: ['the number is', 3], threw: true })
  t.end()
})

t.test('capture and still call the function', t => {
  // to do this, we just pass the original in as the third arg
  const results = t.capture(console, 'log', console.log)
  // actually logs to the console
  functionThatLogs(1)
  t.match(results(), [
    { args: ['the number is', 1], returned: undefined },
  ])
  t.end()
})

t.test('intercept a property set/get', t => {
  // the last arg is a propertyDescriptor, but configurable: true
  // forced on it even if not provided, so that we can restore
  // it at the end of the test.
  // If a value is provided, then we still actually set to a
  // setter/getter so that we can track accesses.
  const results = t.intercept(process, 'version', {
    value: '1.2.3',
  })
  t.equal(process.version, '1.2.3')
  process.version = '2.4.6'
  // we didn't make it writable, so this didn't do anything.
  t.equal(process.version, '1.2.3')
  t.match(results(), [
    { receiver: process, type: 'get', value: '1.2.3', success: true },
    {
      receiver: process,
      type: 'set',
      value: '2.4.6',
      success: false,
    },
    { receiver: process, type: 'get', value: '1.2.3', success: true },
  ])
})

API

• Type ResultsFunction A function that returns data about the
  intercepted calls, and resets the tracking array.
  results.restore() will restore the method to its original
  state.

• t.capture(obj, method, implementation = () => {}): CaptureResultFunction

  Replaces obj[method] with the supplied implementation.

  The results() method will return an array of objects with a
  receiver property indicating the this-context of the method
  call, an args array, an at CallSiteLike object, and either
  threw: true or returned: <value>.

  If t.teardown() is available (ie, if the @tapjs/after
  plugin is not disabled) then it will be automatically
  restored on test teardown. Otherwise, results.restore()
  must be called to restore the original method.

  Returned method also has a calls array which contains the
  results.

• t.intercept(obj, property, desc?: PropertyDescriptor, strictMode: boolean = true): InterceptResultsFunction

  Similar to t.capture(), but can be used to track get/set
  operations for any arbitrary property. The results function
  returns a list of objects with:

  • receiver the object where the set/get is happening
  • type 'get' for get operations, 'set' for set operations
  • value The value that was returned by a get, or set in a
    set.
  • at call site where the get/set occurred.
  • threw whether or not the call threw.
  • success whether or not the call was sucessful.

• t.captureFn(original: (...a:any[]) => any): WrappedFunction

  Similar to t.capture(), but just wraps the function and
  returns it.

  Returned function has a calls array property containing the
  results.