'Immutable' NodeJS module mocking for CJS (CommonJS) modules for unit testing purposes. Similar to proxyquire, but much simpler and more defensive.
Easy to Use 😃
- Much simpler than proxyquire. Straightforward documentation.
- Debugging utility.
Defensive 🛡
- Throws an error if any mocks are unused by module we are mocking.
- Module Cache for the module in question is always deleted before and after mocking to minimize side effects and make behavior more predictable and approximate immutability.
Robust & Reliable 💪
- Tiny codebase written in Typescript with only 1 dependency.
isValidWord.ts
import {readFile} from 'fs/promises'; // we're going to mock this
export async function isValidWord(word: string) {
const validWords = await getValidWords();
return validWords.indexOf(word) !== -1;
}
async function getValidWords() {
const contents = await readFile('./dict.txt', 'utf-8');
return contents.split('\n');
}
isValidWord.spec.ts
import {test} from 'hoare';
import {mock} from 'cjs-mock';
import * as mod from './isValidWord'; // just used for type
const dict = ['dog', 'cat', 'fish'].join('\n');
const mockMod: typeof mod = mock('./isValidWord', {
'fs/promises': {readFile: () => Promise.resolve(dict)},
});
test('valid word returns true', async (assert) => {
const result = await mockMod.isValidWord('dog');
assert.equal(result, true);
});
npm i cjs-mock -D
Returns a module with Dependency Injection for modulePath
, as specified by the mocks
argument. As a side effect, the module cache is deleted for module specified by modulePath
and all modules specified in mocks
. This cache is deleted at the start and end of the function. This should not matter during unit testing, but it is something to be aware of. This should not be used in production code.
You should pass as a string the same thing you would pass to an import
statement or require
, with the following caveats:
- Any relative paths be relative to the module being returned
- It must only be a direct dependency of that module. It will not work recursively, including re-exported modules.
This function throws if any of the modules or properties are not resolvable, or if there are any unused (not required/imported by the module specified in modulePath
):
Error: Unable to find foo
Error: The following imports were unused in ./foo:
./bar
Example usage with relative paths:
/fake/a/foo.js
const bar = require('./bar');
module.exports = function() {
return 'foo ' + bar();
}
/fake/b/example.js
const mockedFoo = mock('../a/foo', { //relative to example.js
'./bar': () => 'fakeBar', //relative to foo.js
});
console.log(mockedFoo()) // foo fakeBar
You can nest mock()
for partial mocking of nested dependencies:
const m = mock('./foo', {
'.': mock('./bar', {
'bob': () => 'fake bob'
})
});
Just like for proxyquire
and other mocking utilities, use of this utility is not recommended in production environments, for the following reasons:
- Mocking utilities (including this one) are typically designed for unit testing in a sandbox environment, not production code.
- It's easy to get the mock wrong (which is why we throw errors for unused mocks and offer debug utilities). Although frustrating, this is harmless in a test environment, but can be disastrous in production.
- It has side effects on the module cache. This can lead to some very unexpected behavior outside of a unit test.
A debugging utility is included, for use when you are having a difficult time seeing the order of how things are getting imported, and if a mock has been substituted after a successful resolution & match.
To enable this mode, set this in your environment: CJS_MOCK_DEBUG=1
.
Example (trucated) output:
Be warned, this will produce a ton of output to stdout
. It's sometimes shocking just how many modules are required in a node project, including built-in modules.
For local development, see scripts in package.json
.
- Issue a PR against
main
and request review. Make sure all tests pass and coverage is good. - You can also submit an issue.
MIT © Marc H. Weiner