@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.

// 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',
  })
})
Copy

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.

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',
  })
})
Copy

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.