# @tapjs/intercept

> a built-in tap extension for t.intercept() and t.capture()

Latest version **4.3.12** (published 2026-09-03) · BlueOak-1.0.0 license · 0 weekly downloads

## Install

```sh
npm install @tapjs/intercept
pnpm add @tapjs/intercept
yarn add @tapjs/intercept
bun add @tapjs/intercept
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 4.3.12 |
| Published | 2026-09-03 |
| First published | 2023-08-04 |
| Weekly downloads | 0 |
| License | BlueOak-1.0.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | 20 \|\| >=22 |
| Dependencies | 2 |
| Unpacked size | 99.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2423 |
| Author | Isaac Z. Schlueter |
| Maintainers | ljharb, isaacs |
| Keywords | tapjs plugin |

## Links

- npm: https://www.npmjs.com/package/@tapjs/intercept
- Repository: https://github.com/tapjs/tapjs
- Homepage: https://github.com/tapjs/tapjs/tree/main/src/intercept#readme
- Issues: https://github.com/tapjs/tapjs/issues
- npm.io page: https://npm.io/package/@tapjs/intercept

## Dependencies (2)

- [@tapjs/after](https://npm.io/package/@tapjs/after.md) 3.3.12
- [@tapjs/stack](https://npm.io/package/@tapjs/stack.md) 4.3.3

## Recent versions

- 4.3.12 (latest) — 2026-09-03
- 1.0.0 (pre) — 2023-09-15
- 4.3.11 — 2026-07-27
- 4.3.10 — 2026-05-15
- 4.3.9 — 2026-05-13
- 4.3.8 — 2026-05-01
- 4.3.7 — 2026-04-17
- 4.3.6 — 2026-04-15
- 4.3.5 — 2026-04-05
- 4.3.4 — 2026-02-20
- 4.3.3 — 2026-02-18
- 4.3.2 — 2026-02-18
- 4.3.1 — 2026-02-05
- 4.3.0 — 2025-12-01
- 4.2.1 — 2025-11-26
- … 76 more at https://npm.io/package/@tapjs/intercept/versions

## README

# `@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](https://node-tap.org/plugins/mock)).

## Usage

```js
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.

---
_Source: https://npm.io/package/@tapjs/intercept · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._