Mockery - Simplifying the use of mocks with Node.js
If you've tried working with mocks in Node.js, you've no doubt discovered that
it's not so easy to get your mocks hooked up in the face of Node's module
loading system. When your source-under-test pulls in its dependencies through
require
, you want your mocks provided, instead of the original module,
to enable true unit testing of your code.
This is exactly the problem Mockery is designed to solve. Mockery gives you a
simple and easy to use API with which you can hook in your mocks without having
to get your hands dirty with the require
cache or other Node implementation
details.
Mockery is not a mocking framework. It lets you work more easily with your framework of choice (or no framework) to get your mocks hooked in to all the right places in the code you need to test.
- Installation
- Enabling mockery
- Registering mocks
- Registering substitutes
- Registering allowable modules
- Deregistering everything
- Controlling the module cache
- Disabling warnings
- The name
- License
Installation
Just use npm:
npm install mockery
Enabling mockery
When enabled, Mockery intercepts all require
calls, regardless of where
those calls are being made from. Thus it's almost always desirable to bracket
your usage as narrowly as possible.
If you're using a typical unit testing framework, you might enable and disable Mockery in the test setup and teardown functions for your test cases. Something like this:
setUp: function() {
mockery.enable();
},
tearDown: function() {
mockery.disable();
}
Options
You can set up some initial configuration by passing an options object to
enable
. Omitting the options object, or any of the defined keys, causes the
standard defaults to be used.
For example, to disable all warnings, you might use this:
mockery.enable({
warnOnReplace: false,
warnOnUnregistered: false
});
The available options are:
- useCleanCache determines whether a temporary module cache should be used while Mockery is enabled. See Controlling the module cache below. [Default: false]
- warnOnReplace determines whether or not warnings are issued when a mock or
substitute is replaced without being first deregistered. This has the same
effect as the
warnOnReplace
function. [Default: true] - warnOnUnregistered determines whether or not warnings are issued when a
module is not mocked, substituted or allowed. This has the same effect as the
warnOnUnregistered
function. [Default: true]
Registering mocks
You register your mocks with Mockery to tell it which mocks to provide for which
require
calls. For example:
var fsMock = {
stat: function (path, cb) { /* your mock code */ }
};
mockery.registerMock('fs', fsMock);
The arguments to registerMock
are as follows:
- module, the name or path of the module for which a mock is being
registered. This must exactly match the argument to
require
; there is no "clever" matching. - mock, the mock to be provided. Whatever is provided here is what will
become the result of subsequent
require
calls; that is, theexports
of the module.
If you no longer want your mock to be used, you can deregister it:
mockery.deregisterMock('fs');
Now the original module will be provided for any subsequent require
calls.
Registering substitutes
Sometimes you want to implement your mock itself as a module, especially if it's more complicated and you'll be reusing it more widely. In that case, you can tell Mockery to substitute that module for the original one. For example:
mockery.registerSubstitute('fs', 'fs-mock');
Now any require
invocation for 'fs' will be satisfied by loading the 'fs-mock'
module instead.
The arguments to registerSubstitute
are as follows:
- module, the name or path of the module for which a substitute is being
registered. This must exactly match the argument to
require
; there is no "clever" matching. - substitute, the name or path of the module to substitute for module.
If you no longer want your substitute to be used, you can deregister it:
mockery.deregisterSubstitute('fs');
Now the original module will be provided for any subsequent require
calls.
Registering allowable modules
If you enable Mockery and don't mock or substitute a module that is later
loaded via require
, Mockery will print a warning to the console to tell you
that. This is so that you don't inadvertently use downstream modules without
being aware of them. By registering a module as "allowable", you tell Mockery
that you know about its use, and then Mockery won't print the warning.
The most common use case for this is your source-under-test, which obviously you'll want to load without warnings. For example:
mockery.registerAllowable('./my-source-under-test');
As with registerMock
and registerSubstitute
, the first argument, module,
is the name or path of the module as it would be provided to require
. Once
again, you can deregister it if you need to:
mockery.deregisterAllowable('./my-source-under-test');
Sometimes you'll find that you need to register several modules at once. A convenience function lets you do this with a single call:
mockery.registerAllowables(['async', 'path', 'util']);
and similarly to deregister several modules at once, as you would expect:
mockery.deregisterAllowables(['async', 'path', 'util']);
Unhooking
By default, the Node module loader will load a given module only once, caching
the loaded module for the lifetime of the process. When you're using Mockery,
this is almost always what you want. Almost. In relatively rare situations,
you may find that you need to use different mocks for different test cases
for the same source-under-test. (This is not the same as supplying different
test data in the same mock; here we're talking about providing different
functions for a module's exports
.)
To do this, your source-under-test must be unhooked from Node's module loading
system, such that it can be loaded again with new mocks. You do this by passing
a second argument, unhook, to registerAllowable
, like this:
mockery.registerAllowable('./my-source-under-test', true);
When you subsequently deregister your source-under-test, Mockery will unhook it from the Node module loading system as well as deregistering it.
Deregistering everything
Since it's such a common use case, especially when you're using a unit test framework and its setup and teardown functions, Mockery provides a convenience function to deregister everything:
mockery.deregisterAll();
This will deregister all mocks, substitutes, and allowable modules, as well as unhooking any hooked modules.
Controlling the module cache
One of the common problems that people encounter when trying to use mocks in Node is that modules and their exports are almost always cached. This makes it difficult to plug in a mock for testing if the module being mocked has already been loaded elsewhere.
Mockery provides a way for you to run your tests using a clean module cache, as
if no modules have been loaded. When this option is enabled, any previously
loaded modules will be "forgotten", and require
calls will cause them to be
reloaded. This in turn allows your mocks to be picked up, and your tests to run
as expected.
You tell Mockery to use a clean cache when you enable it, like this:
mockery.enable({ useCleanCache: true });
Now all modules will be cached in this new clean cache, until you later disable Mockery again. The new cache is temporary, and is discarded when Mockery is disabled. The original cache is reinstated at that point, so you are back to where you were before enabling the clean cache option.
While you are working with a temporary cache, it may occasionally be useful to reset it to a clean state again, without disabling and re-enabling Mockery. You can do this with:
mockery.resetCache();
This function has no effect if the clean cache option is not already in use.
Disabling warnings
As mentioned above, if you enable Mockery and don't mock, substitute, or allow a module that is later loaded, Mockery will print a warning to the console to tell you that. This is important when you're writing unit tests, so that you don't end up using modules you weren't aware of.
In certain circumstances, such as when writing functional or integration tests, you may find it irritating to have to allow each module or to have all the warnings appear on the console. If you need to, you can tell Mockery to turn off those warnings:
mockery.warnOnUnregistered(false);
Mockery will also print a warning to the console whenever you register a mock or substitute for a module for which one is already registered. This is almost always what you want, since you should be deregistering mocks and substitutes that you no longer need. Occasionally, though, you may want to suppress these warnings, which you can do like this:
mockery.warnOnReplace(false);
In either of these cases, if you later need to re-enable the warnings, then
passing true
to the same functions will do that, as you might imagine.
The name
Mockery is to mocks as rookery is to rooks.
License
Mockery is licensed under the MIT License.