`@tapjs/intercept`

A default tap plugin for doing object/global property/method interception and observing.

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.

Current Tags

1.2.7 ... latest (a year ago)
1.0.0 ... pre (a year ago)

39 Versions

1.2.7 ... a year ago
1.2.6 ... a year ago
1.2.5 ... a year ago
1.2.4 ... a year ago
1.2.3 ... a year ago
1.2.2 ... a year ago
1.2.1 ... a year ago
1.2.0 ... a year ago
1.1.4 ... a year ago
1.1.3 ... a year ago
1.1.2 ... a year ago
1.1.1 ... a year ago
1.1.0 ... a year ago
1.0.3 ... a year ago
1.0.2 ... a year ago
1.0.1 ... a year ago
1.0.0 ... a year ago
0.0.0-22 ... a year ago
0.0.0-21 ... a year ago
0.0.0-20 ... a year ago
0.0.0-19 ... a year ago
0.0.0-18 ... a year ago
0.0.0-17 ... a year ago
0.0.0-16 ... a year ago
0.0.0-15 ... a year ago
0.0.0-14 ... a year ago
0.0.0-13 ... a year ago
0.0.0-12 ... a year ago
0.0.0-11 ... a year ago
0.0.0-10 ... a year ago
0.0.0-9 ... a year ago
0.0.0-8 ... a year ago
0.0.0-7 ... a year ago
0.0.0-6 ... a year ago
0.0.0-5 ... a year ago
0.0.0-4 ... a year ago
0.0.0-3 ... a year ago
0.0.0-2 ... a year ago
0.0.0-1 ... a year ago