Mockery-next - Simplifying the use of mocks with Node.js

This is a fork of mockery intended to fix bugs and implement new features. Hopefully it will be merged into mockery. Until then, I've pushed it to npm to use in my own projects.

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-next

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. Path to the module is resolved the same way as when require is used.
• mock, the mock to be provided. Whatever is provided here is what will become the result of subsequent require calls; that is, the exports 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. Path to the module is resolved the same way as when require is used.
• 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.