proxyquire
Proxies Node.js require to allow easy overriding of dependencies during testing without modifying source code.
What is proxyquire?
Proxyquire is a Node.js library that proxies the `require` function to allow easy stubbing and mocking of dependencies during unit testing. It solves the problem of isolating modules by letting developers override specific dependencies without altering the original source code, ensuring tests are focused and reliable.
Node.js developers and testers who need to write isolated unit tests for modules with external dependencies, particularly those working in test-driven development (TDD) or behavior-driven development (BDD) environments.
Developers choose Proxyquire because it requires no changes to production code, works with any mocking framework, and provides fine-grained control over dependency behavior while keeping non-overridden methods intact, making it a flexible and unobtrusive testing tool.
Overview
🔮 Proxies nodejs require in order to allow overriding dependencies during testing.
Use Cases
Best For
- Unit testing Node.js modules with external dependencies
- Mocking filesystem or network calls in tests
- Testing modules that conditionally require packages
- Isolating modules for test-driven development (TDD)
- Overriding transitive dependencies in complex dependency trees
- Simulating the absence of modules to test fallback logic
Not Ideal For
- Projects using ES modules (ESM) instead of CommonJS require
- Integration or end-to-end testing where real dependencies are needed
- Teams already using Jest or similar frameworks with built-in mocking
- Developers needing simple, out-of-the-box mocking without advanced cache control
Pros & Cons
Pros
Proxyquire works without modifying the original module, as emphasized in the README's 'no changes to your code' feature, making it non-invasive.
It is agnostic to mocking libraries, compatible with any tool that can stub functions, allowing integration with Sinon.JS or others.
Features like @noCallThru and cache management (noPreserveCache) provide precise control over dependency behavior and module state in tests.
Allows overriding dependencies across the module graph with @global, useful for complex stubbing scenarios, though with caveats.
Cons
The README warns that using @global can cause module initialization code to run multiple times, leading to side effects and harder-to-debug tests.
Designed for CommonJS require, it does not natively handle ES modules, limiting its use in modern Node.js projects adopting import/export syntax.
Advanced features like @runtimeGlobal and cache configuration require careful setup, adding verbosity and potential for errors in test code.
Frequently Asked Questions
Related Projects
react testing library🐐 Simple and complete React DOM testing utilities that encourage good testing practices.
Supertest🕷 Super-agent driven library for testing node.js HTTP servers using a fluent API. Maintained for @forwardemail, @ladjs, @spamscanner, @breejs, @cabinjs, and @lassjs.
Sinon.JSTest spies, stubs and mocks for JavaScript.
chaiBDD / TDD assertion framework for node.js and the browser that can be paired with any testing framework.
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.