# @tapjs/mock

> tap plugin adding t.mockRequire() and t.mockImport()

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

## Install

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

## 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.4.10 |
| 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 | 4 |
| Unpacked size | 219.6 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/mock
- Repository: https://github.com/tapjs/tapjs
- Homepage: https://github.com/tapjs/tapjs/tree/main/src/mock#readme
- Issues: https://github.com/tapjs/tapjs/issues
- Funding: https://github.com/sponsors/isaacs
- npm.io page: https://npm.io/package/@tapjs/mock

## Dependencies (4)

- [@tapjs/after](https://npm.io/package/@tapjs/after.md) 3.3.12
- [@tapjs/stack](https://npm.io/package/@tapjs/stack.md) 4.3.3
- [walk-up-path](https://npm.io/package/walk-up-path.md) ^4.0.0
- [resolve-import](https://npm.io/package/resolve-import.md) ^2.4.0

## Recent versions

- 4.4.10 (latest) — 2026-09-03
- 1.0.0 (pre) — 2023-09-15
- 4.4.9 — 2026-07-27
- 4.4.8 — 2026-05-15
- 4.4.7 — 2026-05-13
- 4.4.6 — 2026-05-01
- 4.4.5 — 2026-04-17
- 4.4.4 — 2026-04-15
- 4.4.3 — 2026-04-05
- 4.4.2 — 2026-02-20
- 4.4.1 — 2026-02-18
- 4.4.0 — 2026-02-18
- 4.3.1 — 2026-02-05
- 4.3.0 — 2025-12-01
- 4.2.1 — 2025-11-26
- … 77 more at https://npm.io/package/@tapjs/mock/versions

## README

# `@tapjs/mock`

A default tap plugin adding `t.mockRequire()`, `t.mockImport()`,
and `t.createMock()`

## USAGE

This plugin is installed with tap by default. If you had
previously removed it, you can `tap plugin add @tapjs/mock` to
bring it back.

This is the way to do dependency injection at the module level.
When the loaded module, or anything it loads, loads something
that you've mocked, it'll get your mock instead of the real
thing. Useful for getting into those hard to trigger code paths.

```ts
// test.mts
import t from 'tap'

t.test('handls stat failure by throwing', async t => {
  const mockStatSync = (p: string) => {
    t.equal(p, 'filename.txt')
    throw Object.assign(new Error('expected error'), {
      code: 'ENOENT',
    })
  }
  // supply type param so that TS knows what it returns
  const thingThatDoesStat = await t.mockImport<
    typeof import('../dist/my-statty-thing.js')
  >('../dist/my-statty-thing.js', {
    'node:fs': { statSync: mockStatSync },
  })

  t.throws(() => thingThatDoesStat('filename.txt'), {
    message: 'expected error',
    code: 'ENOENT',
  })
})
```

### `t.mockImport(module, [mocks]): Promise<any>`

Load the module with `import()`. If any mocks are provided, then
they'll override the module's imported deps. This works for both
ESM and CommonJS modules.

### `t.mockRequire(module, [mocks]): any`

Same as `t.mockImport()`, but synchronously using `require()`
instead. This only works with CommonJS, and only mocks CommonJS
modules loaded.

### `t.mockAll(mocks?: Record<string,any> | null): Record<string, any>`

Convenience method to set the mocks for all subsequent calls to
`t.mockRequire` or `t.mockImport` for the remainder of the test.

Mocks added with `mockAll` are overridden by any explicit mocks
set in the `t.mockRequire` or `t.mockImport` call.

Repeated calls to `t.mockAll()` will _add_ mocks to the set. If the same
name is used again, it will replace the previous value, not merge.

If a key is set to `undefined` or `null`, then it will be removed from
the `mockAll` set.

Reset by calling `t.mockAll(null)`

Call with no args to return the current `mockAll` object.

### `t.createMock(originalModule, mockOverrides): mockedModule`

Sometimes you only want to override one function or property,
perhaps buried deep within a module's exports, but leave all the
rest of it intact.

This function makes it easy to do that.

```ts
import * from 'tap'
import * as FS from 'node:fs'

t.test('situation where we get a bogus file descriptor', async t => {
  const { thing } = await t.mockImport<typeof import('../dist/my-thing.js')>(
    '../dist/my-thing.js',
    { 'node:fs': t.createMock(FS, { openSync: () => true }) }
  )
  t.throws(() => thing(), {
    // imagine this is the error we get for some reason
    message: 'got non-numeric file descriptor: true',
  })
})
```

## Loader

The `t.mockImport()` function relies on the `@tapjs/mock/loader`
loader being used, which this plugin adds to tap's set of
loaders.

If you run tests directly with node, and they use `t.mockImport`
then you'll have to include `--loader=@tapjs/mock/loader` to the
command line arguments ahead of the main script filename.

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