bs-rewire
BuckleScript bindings for Rewire
Rewire adds a special setter and getter to modules so you can modify their behaviour for better unit testing. bs-rewire provides the bindings to allow you to use the familiar rewire approach to test your ReasonML and OCaml code when targetting the Node ecosystem through Bucklescript (damn, that was amouthful, wasn't it?).
Installation
npm install --save-dev @gmmorris/bs-rewire
Then add @gmmorris/bs-rewire
to bs-dev-dependencies
in your bsconfig.json
:
{
...
"bs-dev-dependencies": ["@gmmorris/bs-rewire"]
}
API
rewire(filename: String): Rewire.RewiredModule
Returns a rewired version of the module found at filename
.
Use Rewire.rewire()
exactly like the JS version rewire()
.
Rewired.set(Rewire.RewiredModule, name : string, value: 'a) : (Rewired.reset: unit => unit)
Sets the internal variable name
to the given value
. Returns a function which can be called to revert the change.
Rewired.setAll(Rewire.RewiredModule, values : Js.Dict.t('a)) : (Rewired.reset: unit => unit)
Takes all keys of dict
as variable names and sets the values respectively. Returns a function which can be called to revert the change.
Rewired.get(Rewire.RewiredModule, name : string) : 'a
Returns the private variable with the given name
.
Rewired.withRewiring(Rewire.RewiredModule, values : Js.Dict.t('a)) : (Rewired.rewiringExecutor : unit => unit => unit)
Returns a function which - when being called - sets obj
, executes the given callback
and reverts obj
.
Rewired.withAsyncRewiring(Rewire.RewiredModule, values : Js.Dict.t('a)) : (Rewired.rewiringAsyncExecutor : unit => Js.Promise.t('x))
Returns a function which - when being called - sets obj
, executes the given callback
and expects a Promise to be returned.
obj
is only reverted after the promise has been resolved or rejected. For your convenience the returned function passes the received promise through.
Rewired.MakeRewired & Rewired.MakeModuleRewiring
The MakeRewired & MakeModuleRewiring Functors allow you to create a custom Rewire module tailerd to your Javscript module's API.
Examples In ReasonML
Example #1 : Basic Use Case
The following is the basic use case. In this use case the following approach is being taken:
-
Rewire.rewire
is called with a local module file being rewired at./testAsset.js
. - A global variable in the
testAsset
is then overridden using theRewire.set
API which takes the rewired module, the name of the variable being overridden and the mock value. - The mock value is a JS object created using Bucklescript's jsConverter generator.
- As the rewiredModule only has the Rewire API we then need to use some Raw JS to trick the Reason compiler into letting us call the 'getParam' within the testAsset module.
testAsset.js
The module we wish to rewire
/*
* This module returns a simple object: { param: "someValue" }
*/
let someModule = require('./someModule.js');
module.exports = {
getParam: function () {
return someModule.param;
}
};
Test.re
The test file which uses rewire to test the testAsset.js file
open Jest;
[@bs.deriving jsConverter]
type oneParamModule = {param: string};
describe("testAsset.getParam", () => {
open Expect;
let getParam = [%raw
{|
function(rewiredModule) {
return rewiredModule.getParam();
}
|}
];
test("getParam returns the value in the global `someModule.param`", () => {
let rewiredModule = Rewire.rewire("./testAsset.js");
Rewire.set(
rewiredModule,
"someModule",
oneParamModuleToJs({param: "someMockedValue"}),
);
expect(
getParam(rewiredModule)
) |> toEqual("someMockedValue");
})
});
Example #2 : Custom JS API of module
The downside to Example #1 is that we have to use Raw JS to trick the compiler. This means our tests are no longer type safe - seems to defeat the purpose of using ReasonML, doesn't it?
MakeRewired
Start by defining a custom API which mirrors the API of the JS module you're testing.
If we take our testAsset.js as an example, we have a single function, getParam
, which returns a string.
module TestAssetModule = {
include
MakeRewired(
{
type t;
},
);
[@bs.send] external getParam : t => string = "";
};
Using MakeRewired
allows us to define our single function on our module and extend this module with the Rewire API.
MakeModuleRewiring
Now that we have a type which mirrors our JS module, we can use MakeModuleRewiring
to create a custom 'Rewire.rewire()' function which will return our custom module type.
This makes it possible for us to call getParam
directly.
open Jest;
open Rewire;
module TestAssetModule = {
include
MakeRewired(
{
type t;
},
);
[@bs.send] external getParam : t => string = "";
};
module TestAssetRewiring = {
include MakeModuleRewiring(TestAssetModule);
};
describe("testAsset.getParam", () =>
Expect.(
test(
"getParam returns the value in the global `someModule.param`",
() => {
let rewiredModule = TestAssetRewiring.rewire("./assets/testAsset.js");
expect(TestAssetModule.getParam(rewiredModule))
|> toEqual("someValue");
})
)
);
See the tests for more examples.