proxyquire

What is proxyquire?

Proxyquire is a powerful tool for stubbing and mocking dependencies in Node.js unit tests. It allows you to override dependencies during testing without modifying the actual code, making it easier to isolate and test individual modules.

What are proxyquire's main functionalities?

Basic Dependency Override

This feature allows you to override a dependency with a mock implementation. In this example, the './dependency' module's 'myFunction' is replaced with a mock function that returns 'mocked value'.

const proxyquire = require('proxyquire');
const myModule = proxyquire('./myModule', {
  './dependency': { myFunction: () => 'mocked value' }
});
console.log(myModule.useDependency()); // Outputs: 'mocked value'

Override Multiple Dependencies

This feature allows you to override multiple dependencies at once. In this example, both './dependency1' and './dependency2' are replaced with mock implementations.

const proxyquire = require('proxyquire');
const myModule = proxyquire('./myModule', {
  './dependency1': { myFunction1: () => 'mocked value 1' },
  './dependency2': { myFunction2: () => 'mocked value 2' }
});
console.log(myModule.useDependencies()); // Outputs: 'mocked value 1 and mocked value 2'

Conditional Overrides

This feature allows you to conditionally override dependencies based on certain conditions, such as environment variables. In this example, the './dependency' module is only mocked if the TEST_ENV environment variable is set.

const proxyquire = require('proxyquire');
const myModule = proxyquire('./myModule', {
  './dependency': process.env.TEST_ENV ? { myFunction: () => 'mocked value' } : require('./dependency')
});
console.log(myModule.useDependency()); // Outputs: 'mocked value' if TEST_ENV is set, otherwise the real value

Other packages similar to proxyquire

sinon

Sinon is a popular library for creating spies, stubs, and mocks in JavaScript. Unlike Proxyquire, which focuses on overriding dependencies, Sinon provides a more comprehensive set of tools for creating test doubles and verifying interactions.

rewire

Rewire is another library that allows you to modify the behavior of modules during testing. It provides a similar functionality to Proxyquire but with a different API. Rewire allows you to access private variables and functions within a module, which can be useful for more fine-grained control.

mock-require

Mock-require is a simpler alternative to Proxyquire that allows you to mock Node.js modules. It provides a straightforward API for replacing modules with mock implementations, but it lacks some of the advanced features of Proxyquire.

README

proxyquire

Proxies nodejs's require in order to make overriding dependencies during testing easy while staying totally unobstrusive.

Features

• no changes to your code are necessary
• non overriden methods of a module behave like the original
• overrides can be removed individually after they were added
• strict mode to enforce overriding all methods used in a to be tested module

Example

foo.js:

var path = require('path');

module.exports.extnameAllCaps = function (file) { 
  return path.extname(file).toUpperCase();
};

module.exports.basenameAllCaps = function (file) { 
  return path.basename(file).toUpperCase();
};

foo.test.js:

var proxyquire = require('proxyquire').setup()
  , assert = require('assert');

// no overrides yet, so path.extname behaves normally
var foo = proxyquire.require('./foo');
assert.equal(foo.extnameAllCaps('file.txt'), '.TXT');

// override path.extname
proxyquire({
  path: { extname: function (file) { return 'Exterminate, exterminate the ' + file; } }
});

// path.extname now behaves as we told it to
foo = proxyquire.require('./foo');
assert.equal(foo.extnameAllCaps('file.txt'), 'EXTERMINATE, EXTERMINATE THE FILE.TXT');

// path.basename and all other path module methods still function as before
assert.equal(foo.basenameAllCaps('/a/b/file.txt'), 'FILE.TXT');

Table of Contents generated with DocToc

• Installation
• Usage
• API
  • Setup proxyquire inside test
  • Require module to be tested
  • Reset all overrides
  • Override methods of required modules
  • Reset and override in one step
  • Removing overrides
  • Chain API Calls
  • strict vs. non-strict overrides
    • Non-strict
    • Strict
• More Examples

Installation

npm install proxyquire

Usage

Three simple steps to override require in your tests:

• var proxyquire = require('proxyquire').setup(); on top level of your test file
• setup desired module overrides e.g., proxyquire({ path: { extname: function () { return 'meh'; } }); in your test
• proxyquire.require(..) the module you want to test and excercise its methods

Alternatively if you are worried about test speed and/or are testing very large modules:

• include var require = require('proxyquire'); on top of any module whose requires you want to be able to control
• setup desired module overrides (same as above)
• use regular nodejs require in order to require the module you want to test and excercise its methods

API

Setup proxyquire inside test

var proxyquire = require('proxyquire').setup();

• needs to be called from top level of test file
• properly sets up calls to proxyquire.require(..)

Require module to be tested

proxyquire.require(String [, String])

Works the same as nodejs's require while preparing the to be tested module to have its dependencies overridden.

• without touching the original code proxyquire.require injects a require override before passing it on to nodejs's require
• since this happens automatically, you don't need to change the code of the module whose dependencies you want to override
• optional second argument can be used to manually pass __dirname of test file, but ideally this would be done via proxyquire.setup()

Reset all overrides

proxyquire.reset()

Useful if you want to entirely start over in overriding dependencies.

• resets any registered overrides
• flushes nodejs's require cache in order to force re-requiring the module you are testing, in order to cause any new overridden modules to be re-required as well

Override methods of required modules

proxyquire.add(Object)

Adds overrides for given methods in particular modules.

Example:

proxyquire.add({
    './module1': {
          prop: /* override */
        , func: function () { /* override */ }
        }
  ,  module2: {
          prop: /* override */
        , func: function () { /* override */ }
        , __proxyquire: { strict: true }
        }
  });

• note that a relative path to the module can be given ('./module1')
  • Important: this is the path as it appears inside the module you are testing, proxyquire will resolve it as if it was required from that module
• __proxyquire property allows to further configure overrides. In the case of module2 it is configured to be strict see strict vs. non-strict overrides

Reset and override in one step

proxyquire(Object)

A shortcut which calls proxyquire.reset() and then proxyquire.add(Object)

Removing overrides

proxyquire.del(String | Object)

Removes overrides and replaces them with method of the real module unless it was overridden using strict mode.

Examples:

Assume path.extname and path.basename were overridden previously.

Remove all path module overrides:

    proxyquire.del('path');

Remove only path.extname override:

    proxyquire.del({ path: 'extname' });

Explicitly remove path.extname and path.basename overrides. (In this case this has the same effect as overriding entire path module):

    proxyquire.del({ path: [ 'extname', 'basename' ] });

Chain API Calls

proxyquire's API supports chaining of method calls during setup.

Things like:

proxyquire
  .reset()
  .add({
    path: { extname: function (x) { return 'what?'; } 
  })
  .add({
    fs: { realpath: function (x, y) { return 'no really, what?'; } 
  })
  .del('path')
  ;

are perfectly legal. Yes I know this example is totally contrived, but it shows lots of possibilities in one shot ;) .

strict vs. non-strict overrides

Controls what happens when a function that wasn't overridden (added) via proxyquire is called.

In non-strict mode proxyquire will call the method with the same name on the 'real' module.

In strict mode proxyquire will fail with has no method ... exception

Examples:

Non-strict

proxyquire.add({
    path: { extname: function (x) { return 'what?'; } 
})
require('path').basename('/a/b/c.txt') // returns 'c.txt'

Strict

proxyquire.add({
    path: { extname: function (x) { return 'what?'; } 
  , __proxyquire: { strict: true }
})
require('path').basename('/a/b/c.txt') // will throw an error

More Examples

For more examples look inside the examples folder or look through the tests