esmock

You can mock specific dependencies by providing their name or path in the second argument of esmock. This includes standard npm packages, subpath imports (aliases like #icon), and relative file paths.

import test from 'node:test'
import assert from 'node:assert'
import esmock from 'esmock'

test('package, alias and local file mocks', async () => {
  const cookup = await esmock('../src/cookup.js', {
    addpkg: (a, b) => a + b,
    '#icon': { coffee: '☕', bacon: '🥓' },
    '../src/breakfast.js': {
      default: () => ['coffee', 'bacon'],
      addSalt: meal => meal + '🧂'
    }
  })

  assert.equal(cookup('breakfast'), '☕🥓🧂')
})

When your code uses dynamic await import(), use esmock.p. This version of the function ensures that mock definitions are kept in a cache, so when the dynamic import is called, the mocked definition is returned correctly.

import test from 'node:test'
import assert from 'node:assert'
import esmock from 'esmock'

test('mocks "await import()" using esmock.p', async () => {
  const doAwaitImport = await esmock.p('../awaitImportLint.js', {
    eslint: { ESLint: cfg => cfg }
  })

  assert.equal(await doAwaitImport('cfg🛠️'), 'cfg🛠️')
})

The primary esmock function accepts three arguments:

1. path: The path to the target module being tested.
2. childmocks: An object defining mocks for modules imported by the target module (supports package names, aliases, and local file paths).
3. globalmocks: An object defining mocks that are applied to the global scope or the import namespace, affecting the entire import tree.

Note: For Node.js versions prior to v20.6.0, you must use the --loader command line argument with esmock. Current versions of Node.js do not require this.

await esmock(
  './to/module.js', // path to target module being tested
  { ...childmocks }, // mock definitions imported by target module
  { ...globalmocks }) // mock definitions imported everywhere

By default, esmock may merge mocks with existing module definitions. If you want to completely replace the original module definitions without merging them, use esmock.strict. If your mock object is missing properties that the original module had, accessing those properties will result in a TypeError.

import test from 'node:test'
import assert from 'node:assert'
import esmock from 'esmock'

test('esmock.strict mocks', async () => {
  // replace original module definitions and do not merge them
  const pathWrapper = await esmock.strict('../src/pathWrapper.js', {
    path: { dirname: () => '/path/to/file' }
  })

  // error, because "path" mock above does not define path.basename
  await assert.rejects(() => pathWrapper.basename('/dog.🐶.png'), {
    name: 'TypeError',
    message: 'path.basename is not a function'
  })
})

The esmock repository uses a flat configuration for ESLint. It integrates @eslint/js, @eslint/markdown, and typescript-eslint to enforce code quality across JavaScript, TypeScript, and Markdown files. Key features include:

• Markdown Support: Uses @eslint/markdown to process code blocks within .md files.
• TypeScript Integration: Applies typescript-eslint recommended rules with specific overrides to allow any types and unused expressions/variables in certain contexts.
• Global Variables: Defines globals for testing environments (e.g., describe, it, test, expect) and specific esmock utilities (esmock, childmocks, globalmocks) within Markdown code blocks.
• Code Style: Enforces a specific style including 2-space indentation, no semicolons, and specific rules for variable declarations and arrow functions.

When using esmock, modules are cached to optimize performance. If you need to re-mock a module or ensure a fresh import, you can manually purge it using the purge function.

To use purge, you must pass the imported module object returned by esmock. The function checks if the object is a valid mockable entity (object or function) and contains the required esmkTreeId.

import esmock, { purge } from 'esmock';

const mod = await esmock('./module.js', import.meta.url, { './dep.js': {} });

// ... perform tests ...

// Clear the module from the esmock cache
purge(mod);

The esmock.strict variant (and the standalone strict export) replaces original module definitions with your provided mock definitions instead of merging them. This is useful when you want to ensure the original implementation is not executed at all.

import { strict } from 'esmock';

const mockedModule = await strict('./my-module.js', import.meta.url, {
  './dependency.js': { mockedValue: true }
});

The esmock function allows you to mock imports for a specific module. You provide a modulePath (the module to be mocked), a parent (a URL used to resolve relative specifiers, typically import.meta.url), and defs (a mapping of import specifiers to mock definitions).

By default, esmock merges your mock definitions with the original module definitions. To completely replace the original definitions, use the strict or strictest variants.

import esmock from 'esmock';

// Basic usage: mocking a module
const mockedModule = await esmock('./my-module.js', import.meta.url, {
  './dependency.js': { mockedValue: true }
});