rewiremock

/$$      /$$ /$$                     /$$      /$$                     /$$      
                    | $$  /$ | $$|__/                    | $$$    /$$$                    | $$      
  /$$$$$$   /$$$$$$ | $$ /$$$| $$ /$$  /$$$$$$   /$$$$$$ | $$$$  /$$$$  /$$$$$$   /$$$$$$$| $$   /$$
 /$$__  $$ /$$__  $$| $$/$$ $$ $$| $$ /$$__  $$ /$$__  $$| $$ $$/$$ $$ /$$__  $$ /$$_____/| $$  /$$/
| $$  \__/| $$$$$$$$| $$$$_  $$$$| $$| $$  \__/| $$$$$$$$| $$  $$$| $$| $$  \ $$| $$      | $$$$$$/ 
| $$      | $$_____/| $$$/ \  $$$| $$| $$      | $$_____/| $$\  $ | $$| $$  | $$| $$      | $$_  $$ 
| $$      |  $$$$$$$| $$/   \  $$| $$| $$      |  $$$$$$$| $$ \/  | $$|  $$$$$$/|  $$$$$$$| $$ \  $$
|__/       \_______/|__/     \__/|__/|__/       \_______/|__/     |__/ \______/  \_______/|__/  \__/

1. Install

• yarn add --dev rewiremock or npm i --save-dev rewiremock

1. Setup

for ts/es6/esm use import

// rewiremock.es6.js
import rewiremock from 'rewiremock';
// settings
// ....
rewiremock.overrideEntryPoint(module); // this is important. This command is "transfering" this module parent to rewiremock
export { rewiremock }

for commonjs/nodejs use require('rewiremock/node')

// rewiremock.cjs.js
const rewiremock = require('rewiremock/node'); 
// nothng more than `plugins.node`, but it might change how filename resolution works
/// settings
rewiremock.overrideEntryPoint(module); // this is important
module.exports = rewiremock;

for webpack

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

If you import rewiremock directly from your tests, you dont need overrideEntryPoint

1. Use

proxyquire - like

const file = rewiremock.proxy('file.js', {
  'dependency':  stub
});
// or
const file = rewiremock.proxy(() => require('file.js'), {
   'dependency':  stub
 });

import rewiremock, { addPlugin, plugins } from 'rewiremock';
addPlugin(plugins.relative);

mockery - like

rewiremock('dependency').with(stub);
rewiremock(() => require('dependency')).with(stub);
rewiremock(() => import('dependency')).with(stub); // works with async API only
rewiremock.enable(); 
const file = require('file.js');
rewiremock.disable();

jest - like

// just place it next to `imports` and add a rewiremock/babel plugin 
rewiremock('dependency').with(stub); 

1. Tune

import { resolve } from 'path';
import rewiremock, { addPlugin, overrideEntryPoint, plugins } from 'rewiremock';
import { configure } from 'rewiremock/lib/plugins/webpack-alias'; // actually dont use it

configure(resolve(`${__dirname}/../../webpack.config.test.js`));

overrideEntryPoint(module);
// we need webpack aliases
addPlugin(plugins.webpackAlias);
// and all stub names would be a relative
addPlugin(plugins.relative);
// and all stubs should be used. Lets make it default!
addPlugin(plugins.usedByDefault);

export { rewiremock };

What command to use???!!!

// use `require` instead of just the filename to maintain type information
const mock = rewiremock.proxy(() => require('somemodule'), r => {
   'dep1': { name: 'override' },
   // use all power of rewiremock to mock something as you want...
   'dep2': r.with({name: 'override' }).toBeUsed().directChildOnly(), // use all `mocking API`
}));

• You can use require or import to specify the file to require and the file to mock. This helps to resolve file names and maintain type information(if you have it). See Guided Mocking below.
• You can mix simplified helpers (like .proxy) and the main API.

ESM modules

• use .module - an "async" version of .proxy

const mock = await rewiremock.module(() => import('somemodule'), {...});

• or just use import - that would

rewiremock(() => require('xxx').with({});
rewiremock('yyy').with({});

const file = await import('somemodule');

- `.enable/disable()` - to enable or disable mock (enabled by default).
- `.with(stubs: function | Object)` - overloads module with a value
- `.withDefault(stub: function | Object)` - overload `default` es6 export
- `.es6()` - marks module as ES6( __esModule )
- `.by(otherModule: string| function)` - overload by another module(if string provider) or by result of a function call. 
- `.callThrough()` - first load the original module, and next extend it by provided stub.
- `.mockThrough([stubFactory])` - first load the original module, and then replaces all exports by stubs.
- `.dynamic()` - enables hot mock updates.     
- `.toBeUsed()` - enables usage checking.  
- `.directChildOnly` - will do mock only direct dependencies.
- `.calledFromMock` - will do mock only dependencies of mocked dependencies.    

rewiremock('fileName.js').disable();

A common way to mock.

All the mocks await you to provide "stubs" to override the real implementation. If you want just to ensure you have called endpoints – use rewiremock('someFile').mockThrough.

• proxy will load a file by its own ( keep in mind - name resolution is a complex thing)

const mock = rewiremock.proxy('somemodule', (r) => ({
   'dep1': { name: 'override' },
   'dep2': r.with({name: 'override' }).toBeUsed().directChildOnly(), // use all `mocking API`
   'dep3': r.mockThrough() // automatically create a test double  
}));

• you can require a file by yourself. ( yep, proxy is a "god" function)

const mock = rewiremock.proxy(() => require('somemodule'), {
   'dep1': { name: 'override' },
   'dep2': { onlyDump: 'stubs' }  
}));

• or use es6 import (not for Node.js mjs real es6 modules)

const mock = await rewiremock.module(() => import('somemodule'), {
   'dep1': { name: 'override' },
   'dep2': { onlyDump: 'stubs' }  
}));

• around - another version of .module, where you can do just ~anything~.

const mock = await rewiremock.around(() => import('somemodule'), () => {
   rewiremock('dep1').with('something');  
   callMom();
   // prepare mocking behavior
}));

• enable/disable - Low level API

In all the cases you can specify what exactly you want to mock, or just mock anything 
```js
   addPlugin(plugins.mockThroughByDefault);  

import sinon from 'sinon';
import rewiremock from 'rewiremock';
import Component1 from 'common/Component1';
import selectors from 'common/selectors';

rewiremock('common/Component1').by('common/Component2');
rewiremock('common/Component2/action').with({ action: () => {} });
rewiremock('common/selectors').mockThrough(() => sinon.stub());

selectors.findUser.returns("cat"); // this is sinon stub.
``` 
As result Component1 will be replaced by Component2, action with empty function and 
all selectors by sinon stubs, with one configured.

This is only possible via babel plugin, and without it, this code will be executed without any sense, as long mocking
will be configured after the files required.

### Limitations
- Other babel plugins, including JSX, won't work inside webpack _hoisted_ code. But you may define
any _specific_ code in "functions", and let JavaScript hoist it.
- Most variables, that you have defined in the file, are not visible to __hoisted__ code, as long they are __not yet defined__.
Only functions will be hoisted.

1. Add `rewiremock/babel` into the plugin section of your `.babelrc` or `babel.config.js` file
```js
// .babelrc
{
  "presets": [
    //.....
  ],
  "plugins": [
    "rewiremock/babel"
  ]
}

1. This example will be transpiled into

import sinon from 'sinon';
import rewiremock from 'rewiremock';

rewiremock('common/Component1').by('common/Component2');
rewiremock('common/Component2/action').with({ action: () => {} });
rewiremock('common/selectors').mockThrough(() => sinon.stub());

rewiremock.enabled();

import Component1 from 'common/Component1';
import selectors from 'common/selectors';

rewiremock.disable();

selectors.findUser.returns("cat"); // this is sinon stub.
``` 

Keep in mind - rewiremock will hoist mock definition next to rewiremock import.
 - You can __use__ anything __above__ rewiremock import
 - You can __mock__ anything __below__ rewiremock import
 
### Changing the mocks after the mocking
It is possible to partially change mocking already being applied.
```js
 rewiremock('./foo')
  .callThrough()
  .with({ action1: action1Stub1 })
  .dynamic();

 const foo = require('./foo');
 foo.action == action1Stub1;
 
 rewiremock.getMock('./foo')
   .with({ action1: action1Stub2 });
 
 //while will RESET the mock, and could not change existing ones.
 rewiremock('./foo')
    .with({ action1: action1Stub2 });
 
 foo.action == action1Stub2;
 
 rewiremock('./foo')
    .with({ });
 
 foo.action == theRealFoo;
```   

#### Changing the hoisted mocks
```js
 import rewiremock from 'rewiremock';
 import foo from './foo';
 
 rewiremock('./foo') 
   .with({ action1: action1Stub1 })
   .dynamic();

 const fooMock = rewiremock.getMock('./foo');
 
 describe(..., () => {
   it('...', () => {
     fooMock.with({ });
     
     // while may NOT found the mock
     rewiremock.getMock('./foo').with({ });
   });
 })

Guided mocking

1. Resolution of synchronous API happens on .enable

rewiremock(() => require('./fileToMock1')); // this mock would work
rewiremock.enable();
rewiremock(() => require('./fileToMock2')); //this mock WOULD NOT WORK!

1. Using async API will throw an error

rewiremock(() => import('./fileToMock1'));  
rewiremock.enable(); // this is an exception

1. Async API requires async API

rewiremock.module( () => import('file')) // this is ok
rewiremock.around(..., rw => rw.mock(() => import('file2'))) // this is ok

1. Use TypeScript or Flow.
2. Use dynamic import syntax.
3. Use rewiremock.around or rewiremock.module to perform a mock.
4. Use the async form of rewiremock mock declaration.

// @flow

import rewiremock  from 'rewiremock';

rewiremock.around(
  () => import('./a.js'), 
  mock => {
  mock(() => import('./b.js'))
    .withDefault(() => "4")
    .with({testB: () => 10})
    .nonStrict() // turn off type system
    .with({ absolutely: "anything" })
  }
);

rewiremock.around(
  () => import('./a.js'), 
  mock => {
  // just before loader function rewiremock enabled itself
  mock(() => import('./b.js').then(mock=>mock)) // mocks `live` one `tick` more
  // just after loader function resolved rewiremock disables itself
    mock => {
    ....
    }
  }
);

rewiremock: mocked export "somethingMissing" does not exist in ./b.js
rewiremock: exported type mismatch: ./b.js:default. Expected function, got number

rewiremock('somemoduname')
  .toMatchOrigin(); // to activate
  
// or
import rewiremock, { addPlugin, removePlugin, plugins } from 'rewiremock';
addPlugin(plugins.alwaysMatchOrigin);   

To run with Node.js

```js
const rewiremock = require('rewiremock/node');

// meanwhile
const rewiremock = require('rewiremock').default;
```

To run inside webpack environment.

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

Hint

import rewiremock from 'rewiremock/webpack';

webpack troubleshooting

• TypeError: Cannot read property 'webpackHotUpdate' of undefined

• TypeError: Cannot read property 'call' of undefined

To actually... mock

import rewiremock from 'rewiremock';
...

// totaly mock `fs` with your stub 
rewiremock('fs')
   .with({
       readFile: yourFunction
   });
 
// replace path, by other module 
rewiremock('path')
   .by('path-mock');

// replace enzyme by preconfigured one  (from https://medium.com/airbnb-engineering/unlocking-test-performance-migrating-from-mocha-to-jest-2796c508ec50)
 rewiremock('enzyme')
    .by(({requireActual}) => {
   // see rest of possible params in d.ts file
        const enzyme = requireActual('enzyme');         
        if (!mockSetup) {
          const chai = requireActual('chai');
          const chaiEnzyme = requireActual('chai-enzyme');
          chai.use(chaiEnzyme());           
        }
        return enzyme;
    });
 
// replace default export of ES6 module 
rewiremock('reactComponent')
   .withDefault(MockedComponent)
    
// replace only part of some library and keep the rest 
rewiremock('someLibrary')
   .callThrough() 
   .with({
       onlyOneMethod
   })
   
// secure yourself and from 'unexpected' mocks
rewiremock('myDep')
    .with(mockedDep) 
    .calledFromMock()
```   
  
# Running
There is a simply way to do it: Just enable it, and dont forget to disable it later.
```javascript
 //in mocha tests
 beforeEach( () => rewiremock.enable() );
 //...
 // here you will get some advantage in type casting and autocompleting.
 // it will actually works...
 const someModule = require('someModule'); 
 //...
 afterEach( () => rewiremock.disable() );
```
Once enabled, rewiremock will wipe all mocked modules from cache, and all modules which require them.

Including your test.

Once disabled it will restore everything. 

All unrelated to test dependencies will be kept. Node modules, react, common files - everything.

As a result - it will run faster.
 
# inScope
Sometimes you will have independent tests in a single file, and you might need separate mocks for each one.
`inScope` execute callback inside a sandbox, and all mocks or plugins or anything else you have added will not leaks away.
```javascript
 rewiremock.inScope( () => {
   rewiremock('something').with(something);
   rewiremock.enable();
   // is 'something' mocked? Yes
   ....
   rewiremock.disable();
   // is 'something' mocked? No
   // is it still listed as mock? Yes
 }); 
 // is 'something' mocked or listed? No
```

# Around
And there is a bit harder way to do it - scope.
inScope will create a new internal scope, next you can add something new to it, and then it will be destroyed.
It will also enable/disable rewiremock just in time.

This helps keep tests in isolation.

PS: scopes are nesting each other as javascript prototypes do.
```javascript
rewiremock.around(
   () => import('somemodule'), // load a module. Using import or require.
   // just before it you can specify mocks or anything else
   (mock) => { 
       addPlugin(nodePlugin);

       mock('./lib/a/foo').with(() => 'aa');
       mock('./lib/a/../b/bar').with(() => 'bb');
       mock('./lib/a/../b/baz').with(() => 'cc');
   }
) // at this point scope is dead
   .then((mockedBaz) => { 
       expect(mockedBaz()).to.be.equal('aabbcc');
   });
```  
or just 
```javascript
rewiremock.around(() => import('somemodule')).then(mockedModule => doSomething)  

rewiremock.around(
    () => import('somemodule').then( mockedModule => doSomething),    
    (mock) => aPromise   
);

// preferred way - create stubs using a function, where R is mock creator
rewiremock.proxy('somemodule', (r) => ({
   'dep1': { name: 'override' },
   'dep2': r.with({name: 'override' }).toBeUsed().directChildOnly() // same powerfull syntax
}));

// straight way - just provide stubs.
rewiremock.proxy('somemodule', {
   'dep1': { name: 'override' },
   'dep2': { name: 'override' }
 }));

// require babel-register in describe or it block.
// NOT! On top level. Jest sandboxing and isolation are still in action,
// and will reset all settings to default
require("babel-register");

PS: Jest will set BABEL_ENV to `test`.

It is better just to use `rewiremock.requireActual`, without overriding global require.
 


# Your own setup.
 In most cases you have to:
  - add plugin
  - setup default passBy rules
  - add some common mocks
  - do something else.
  
  And it is not a good idea to do it in every test you have.
  
  It is better to have one setup file, which will do everything for you
  * Part 1 - man in the middle
```javascript
 // this is your test file
 
 // instead of importing original file - import your own one
 // import rewiremock from 'rewiremock';
 import rewiremock from 'test/rewiremock';    

// this tests/rewiremock.js

import rewiremock, { addPlugin, overrideEntryPoint} from 'rewiremock';
// do anything you need
addPlugin(something);
rewiremock('somemodule').with(/*....*/);   

// but don't forget to add some magic
overrideEntryPoint(module); // <-- set yourself as top module
// PS: rewiremock will wipe this module from cache to keep magic alive.
   
export default rewiremock;
``` 
 * Part 3 - enjoy.
 You extract some common code into a helper. And things become a lot easier.
 
 # Default configuration
 Absolutely the same - preconfiguring rewiremock one can achieve via default configuration.
 
 Just put __rewiremock.config.js__ in the root dir, next to project.json, and export a configuration function
```js
// rewiremock.config.js
import wrongrewiremock, {plugins} from 'rewiremock';

export default rewiremock => {
  // do everything with "right" rewiremock
  rewiremock.addPlugin(plugins.nodejs)
}

import {resolveExtensions} from 'rewiremock';
resolveExtensions(['.wasm', '.mjs', '.js', '.json']);

• give the ability to mock everything - CommonJS, ES6, inside Node.js or webpack.
• give the ability to do correctly - isolation, type checking, powerful API
• give the ability to do it easy - simple API to cover all the cases.

• mockery - rewiremock is a better mockery, with the same interface.
• proxyquire - rewiremock is a better proxyquire, with the same interface.
• mock-require - things must not be complex, rewiremock is not.
• jest.mocks - jest is awesome. As well as rewiremock.