cjs-mock
v1.4.15
Published
NodeJS module mocking for CJS (CommonJS) modules for unit testing purposes.
Downloads
37,149
Maintainers
Readme
cjs-mock
NodeJS module mocking for CJS (CommonJS) modules for unit testing purposes. Similar to proxyquire, but simpler and safer. Sponsored by Aeroview.
😃 Easy to use
- Super simple & straightforward documentation
- Powerful debugging utility
- Built in Typescript support
🛡 Defensive & immutable mocking
- Throws an error if any mocks are unused by module we are mocking
- Module Cache for mocked modules are always deleted before and after, to minimize side effects and make behavior more predictable and approximate immutability
💪 Robust & reliable
- Tiny codebase written in Typescript with only 1 tiny dependency
Example
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);
});
See more examples in docs/examples.md
Installation
npm i cjs-mock -D
API
mock(modulePath: string, mocks: any): module
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 would likely be a problem in a production environment.
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 for re-exported modules (ie,
export * from 'foo'
).
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
This is a defensive measure to ensure that the mocks are being used as intended.
The mocked dependencies will only be resolved once, and the real (non-mocked) dependencies will be used for any subsequent imports/requires. This is to prevent the mocks from being used in other modules that import the same module.
However, this can also be a source of confusion.
To aid in debugging, you can set the environment variable CJS_MOCK_DEBUG=1
to see the order of module resolution and mocking.
Partial mocking
You can nest mock()
for partial mocking of nested dependencies:
const m = mock('./foo', {
'.': mock('./bar', {
'bob': () => 'fake bob'
})
});
DO NOT USE IN PRODUCTION
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).
- It has side effects on the module cache, by clearing it. This can lead to some very unexpected behavior outside of a unit test.
Debugging
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 output (truncated screenshot):
In this screenshot, we can see that 'lambdaconf' is being imported twice, once from ./getSupportedAwsRegions.ts
(in which case they are getting the replacement mock), and ./updateAwsLogsDestinations.ts
(in which case they are not getting the replacement mock). This is because the module cache is cleared after the first import, and the real module is used for the second import. So, we either forgot to mock lambdaconf
in one of these modules, or one of our imports also imports lambdaconf
and we need to mock that module as well.
This can be useful for debugging, to see if a mock is being used or not, and to see the order of module resolution.
Be warned, this may produce a metric ton of output. It's sometimes shocking just how many modules are required in a node project, including built-in modules. You may want to limit the output to just the relevant test by only running that test.
Support, feedback, and contributions
- Star this repo if you like it!
- Submit an issue with your problem, feature request or bug report
- Issue a PR against
main
and request review. Make sure all tests pass and coverage is good. - Write about this project in your blog, tweet about it, or share it with your friends!
Sponsorship
Aeroview is a lightning-fast, developer-friendly, and AI-powered logging IDE. Get started for free at https://aeroview.io.
Want to sponsor this project? Reach out.
Other useful libraries
- autorel: Automate semantic releases based on conventional commits. Similar to semantic-release but much simpler.
- hoare: An easy-to-use, fast, and defensive JS/TS test runner designed to help you to write simple, readable, and maintainable tests.
- jsout: A Syslog-compatible, small, and simple logger for Typescript/Javascript projects.
- brek: A small, yet powerful typed and structured config library with lambda support for things like AWS Secrets Manager.
- typura: Simple and extensible runtime input validation for TS/JS, written in TS, fried in batter.