0
# Mock Require
1
2
Mock Require provides simple, intuitive mocking of Node.js modules for testing purposes. It allows you to replace any required module (local files, external modules, or built-in modules) with custom implementations, making it ideal for unit testing and test isolation.
3
4
## Package Information
5
6
- **Package Name**: mock-require
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install mock-require`
10
11
## Core Imports
12
13
```javascript
14
const mock = require('mock-require');
15
```
16
17
## Basic Usage
18
19
```javascript
20
const mock = require('mock-require');
21
22
// Mock a module with a custom implementation
23
mock('fs', {
24
readFileSync: function() {
25
return 'mocked content';
26
}
27
});
28
29
// Use the mocked module
30
const fs = require('fs');
31
console.log(fs.readFileSync()); // 'mocked content'
32
33
// Stop mocking when done
34
mock.stop('fs');
35
```
36
37
## Capabilities
38
39
### Mock Module
40
41
Replace any module with a custom implementation or redirect to another module.
42
43
```javascript { .api }
44
/**
45
* Mock a module with custom implementation or redirect to another module
46
* @param {string} path - Module path to mock (same as require() path)
47
* @param {*} mockExport - Mock implementation (any value) or path to replacement module (string)
48
*/
49
function mock(path, mockExport);
50
```
51
52
**Usage Examples:**
53
54
```javascript
55
const mock = require('mock-require');
56
57
// Mock with custom object
58
mock('http', {
59
request: function() {
60
console.log('http.request called');
61
}
62
});
63
64
// Mock with custom function
65
mock('./utils', function() {
66
return 'mocked utility';
67
});
68
69
// Redirect one module to another
70
mock('fs', 'path'); // require('fs') will return require('path')
71
72
// Mock non-existent modules
73
mock('fake-module', { fake: true });
74
```
75
76
**Supported Mock Types:**
77
- **Objects**: Custom object implementations
78
- **Functions**: Function replacements
79
- **Strings**: Path to another module to use as replacement
80
- **Any Value**: Primitives, arrays, null, undefined, or any JavaScript value
81
82
### Stop Mocking
83
84
Remove the mock for a specific module, restoring its original behavior.
85
86
```javascript { .api }
87
/**
88
* Stop mocking a specific module
89
* @param {string} path - Module path to stop mocking
90
*/
91
mock.stop(path);
92
```
93
94
**Usage Example:**
95
96
```javascript
97
const mock = require('mock-require');
98
99
mock('./module', { mocked: true });
100
const mockVersion = require('./module');
101
102
mock.stop('./module');
103
const realVersion = require('./module');
104
105
// mockVersion !== realVersion
106
```
107
108
### Stop All Mocking
109
110
Remove all registered mocks without the need to stop them individually.
111
112
```javascript { .api }
113
/**
114
* Remove all registered mocks
115
*/
116
mock.stopAll();
117
```
118
119
**Usage Example:**
120
121
```javascript
122
const mock = require('mock-require');
123
124
mock('fs', {});
125
mock('path', {});
126
mock('http', {});
127
128
// Clean up all mocks at once
129
mock.stopAll();
130
```
131
132
### Re-require Module
133
134
Clear Node.js require cache for a module and require it again, useful for applying mocks to already-cached modules.
135
136
```javascript { .api }
137
/**
138
* Clear require cache and re-require a module
139
* @param {string} path - Module path to refresh from cache
140
* @returns {*} The freshly required module
141
*/
142
mock.reRequire(path);
143
```
144
145
**Usage Example:**
146
147
```javascript
148
const mock = require('mock-require');
149
150
// Module is already cached
151
const fs = require('fs');
152
const fileToTest = require('./fileToTest');
153
154
// Apply mock after initial require
155
mock('fs', { mocked: true });
156
157
// Re-require to apply the mock
158
const updatedFileToTest = mock.reRequire('./fileToTest');
159
// updatedFileToTest now uses the mocked fs
160
```
161
162
## Advanced Features
163
164
### Path Resolution
165
166
Mock Require intelligently handles different types of module paths:
167
168
- **Local modules**: `./file.js`, `../utils/helper.js` - Resolved relative to the calling file
169
- **External modules**: `lodash`, `express` - Resolved from node_modules
170
- **Built-in modules**: `fs`, `http`, `path` - Node.js core modules
171
- **Node path modules**: Modules in NODE_PATH environment variable
172
- **Non-existent modules**: Modules that don't exist in the filesystem can still be mocked
173
174
**Path Resolution Behavior:**
175
- Paths are normalized using `normalize-path` for cross-platform compatibility
176
- Local modules are resolved relative to the file calling `mock()`, not the current working directory
177
- External and built-in modules are resolved using Node's standard resolution algorithm
178
- Non-existent local modules can be mocked and will be resolved to their expected path
179
180
### Cascade Mocking
181
182
Mocks can depend on other mocks, creating a cascade effect:
183
184
```javascript
185
mock('path', { mocked: true });
186
mock('fs', 'path'); // fs will use the mocked path
187
const fs = require('fs'); // Returns { mocked: true }
188
```
189
190
### Error Handling
191
192
Mock Require handles various error scenarios gracefully:
193
194
**Module Not Found:**
195
When you stop mocking a non-existent module, subsequent require attempts will throw the standard `MODULE_NOT_FOUND` error:
196
197
```javascript
198
mock('non-existent-module', { fake: true });
199
mock.stop('non-existent-module');
200
201
try {
202
require('non-existent-module');
203
} catch (e) {
204
console.log(e.code); // 'MODULE_NOT_FOUND'
205
}
206
```
207
208
### Test Isolation
209
210
Perfect for test scenarios where you need to isolate dependencies:
211
212
```javascript
213
// In test setup
214
afterEach(() => {
215
mock.stopAll(); // Clean up all mocks between tests
216
});
217
218
it('should handle file operations', () => {
219
mock('fs', {
220
readFileSync: () => 'test content',
221
writeFileSync: () => {}
222
});
223
224
// Test code that uses fs
225
const result = myFunction();
226
assert.equal(result, 'expected');
227
});
228
```