esmock

esmock

esmock provides native ESM import mocking for unit tests. Use the examples below as a quick-start guide or use a descriptive and more friendly esmock guide here.

esmock must be used with node's experimental --loader

{
  "name": "give-esmock-a-star",
  "type": "module",
  "scripts": {
    "test-ava": "ava --node-arguments=\"--loader=esmock\"",
    "test-mocha": "mocha --loader=esmock --no-warnings"
  }
}

esmock has the following signature

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

unit-test examples, using esmock and ava for various situations

import test from 'ava';
import esmock from 'esmock';

test('should mock local files, packages and core modules', async t => {
  const main = await esmock('../src/main.js', {
    fs: { readFileSync: () => 'give it a star' },
    stringifierpackage : o => JSON.stringify(o),
    '../src/hello.js' : {
      default : () => 'world'
    },
    '../src/util.js' : {
      exportedFunction : () => 'foobar'
    }
  });

  t.is(main(), JSON.stringify({ test : 'world foobar' }));
});

test('should do global instance mocks —third parameter', async t => {
  const { getFile } = await esmock('../src/main.js', {}, {
    fs : {
      readFileSync : () => {
        return 'anywhere the instance uses fs readFileSync';
      }
    }
  });

  t.is(getFile(), 'anywhere the instance uses fs readFileSync');
});

test('should mock "await import()" using esmock.p', async t => {
  // using esmock.p, mock definitions are not deleted from cache
  const doAwaitImport = await esmock.p('../src/awaitImportLint.js', {
    eslint : { ESLint : config => config }
  });

  // cached mock definition is there when import is called
  t.is(await doAwaitImport('config'), 'config');

  esmock.purge(doAwaitImport); // clear the cache, if you wish
});

changelog

• 1.6.1 Dec.03.2021
  • adds test verifying deep stacktrace has small path file:///
  • resolve bug, '--loader=esmoc' not-found error not thrown
  • small README edits, update link to wiki (use Home as default)
• 1.6.0 Dec.02.2021
  • reduce file url length (improve readability of stacktrace)
• 1.5.0 Dec.01.2021
  • resolve bug around error '--loader=esmock' detection
• 1.4.0 Nov.30.2021
  • throw error if esmock is called without --loader=esmock
• 1.3.3 Nov.28.2021
  • update quick-start README to include phrase 'unit test'
• 1.3.2 Nov.27.2021
  • use quick-start README with link to more descriptive README
• 1.3.1 Nov.26.2021
  • add npm keywords, remove lines of code
• 1.3.0 Nov.26.2021
  • add support for await import, update README
• 1.1.0 Nov.25.2021
  • add windows-latest to testing pipeline and begin windows support
  • removed files and functions no longer needed
  • increment resolvewithplus package and other dependencies
• 1.0.1 Nov.02.2021
  • add node v17.x to testing pipeline
  • add, make warning message go away for node 16.12.0+
• 1.0.0 Oct.27.2021
  • release version 1.0
• 0.4.2 Oct.27.2021
  • export 'load' hook from moduleLoader, required by node v16.12.0+
• 0.4.1 Oct.10.2021
  • version bump, increment devDependencies,
  • major improvement to README, thanks @swivelgames
• 0.4.0 Sep.07.2021
  • do not runtime error when returning type '[object Module]' default
• 0.3.9 May.05.2021
  • small change to README
  • added a test, update gitlab action to use node 16.x
• 0.3.8 Apr.21.2021
  • small change to README
• 0.3.7 Apr.20.2021
  • add test, throw error if mocked module path is not found
• 0.3.6 Apr.19.2021
  • throw error if mocked module path is not found
• 0.3.5 Apr.18.2021
  • added gitlab actions npm test: node 12.x, 14.x and 15.x
• 0.3.3 Apr.13.2021
  • added keywords to package.json, use github action to npm publish
• 0.3.1 Apr.12.2021
  • simplify README
• 0.3.0 Apr.10.2021
  • adds support for mocking modules 'globally' for the instance
• 0.2.0 Apr.10.2021
  • adds support for mocking core modules such as fs and path
• 0.1.0 Apr.10.2021
  • adds support for native esm modules