rewiremock

Guided mocking allows you to use standard import or require statements to resolve filenames, letting Rewiremock handle the transformation behind the scenes.

Important constraints:

1. Synchronous API: Resolution happens during .enable(). If you use a synchronous rewiremock(() => require(...)) call, it must happen before rewiremock.enable().
2. Async API: Using import() inside a synchronous rewiremock() call will throw an error.
3. Async Requirements: If you need to mock an async import, you must use the async APIs: rewiremock.module() or rewiremock.around().

// Correct: Synchronous require inside guided mock
rewiremock(() => require('./fileToMock1'));
rewiremock.enable();

// Correct: Using async API for async imports
rewiremock.module(() => import('file'));

// Correct: Using around for complex async setups
rewiremock.around(..., rw => rw.mock(() => import('file2')));

To preconfigure rewiremock for all tests, it is recommended to create a central configuration file (e.g., rewiremock.js) rather than importing it directly in every test. The setup depends on your runtime/module system:

TS/ES6/ESM

Use import. You must call rewiremock.overrideEntryPoint(module) to transfer the module parent to rewiremock.

CommonJS/Node.js

Use require('rewiremock/node'). You must call rewiremock.overrideEntryPoint(module).

Webpack

Use import rewiremock from 'rewiremock/webpack'. You must call rewiremock.overrideEntryPoint(module) and add necessary plugins to your webpack test configuration.

// rewiremock.es6.js (TS/ES6/ESM)
import rewiremock from 'rewiremock';
// settings...
rewiremock.overrideEntryPoint(module); 
export { rewiremock }

// rewiremock.cjs.js (CommonJS/Node.js)
const rewiremock = require('rewiremock/node'); 
// settings...
rewiremock.overrideEntryPoint(module);
module.exports = rewiremock;

// rewiremock.es6.js (Webpack)
import rewiremock from 'rewiremock/webpack';
// settings...
rewiremock.overrideEntryPoint(module);
export { rewiremock }

Rewiremock and Jest are generally incompatible because Jest has its own mocking system. If you must use them together, follow these steps at the beginning of your test file:

1. Disable Jest's auto-mocking.
2. Restore module nesting using rewiremock.overrideEntryPoint(module).
3. Override the global require with rewiremock.requireActual to bypass Jest's sandboxing/transformation (Note: this may disable Jest magics).
4. If using ES6/imports, you must manually apply Babel (e.g., via babel-register) inside describe or it blocks, as Jest's sandboxing will reset settings to default at the top level.

// better to disable auto mock
jest.disableAutomock();

// Jest breaks the rules, and you have to restore nesting of modules.
rewiremock.overrideEntryPoint(module);

// There is no way to use overload by Jest require or requireActual.
// use the version provided by rewiremock.
require = rewiremock.requireActual;

// To use ES6/imports, apply Babel inside the test block
describe('block of tests', () => {
  require("babel-register");
})

Rewiremock can run inside a webpack environment (client-side mocking). To enable this, you must include three specific plugins in your webpack configuration:

1. webpack.NamedModulesPlugin(): Ensures modules use real names instead of numeric IDs.
2. webpack.HotModuleReplacementPlugin(): Provides module connection information.
3. rewiremock.webpackPlugin: The core plugin for Rewiremock magic.

Webpack Configuration:

plugins: [
    new webpack.NamedModulesPlugin(),
    new webpack.HotModuleReplacementPlugin(),
    new (require("rewiremock/webpack/plugin"))()
]

Developer Experience Tip: Import rewiremock/webpack for a better development experience.

Troubleshooting:

• If you see TypeError: Cannot read property 'webpackHotUpdate' of undefined, avoid using babel-register when running webpack bundles; use babel to create bundles instead.
• If you see TypeError: Cannot read property 'call' of undefined, import rewiremock/webpack/interceptor in your scaffolding to ensure the interceptor is included in the bundle.