From 26599ff914301f38bdc6433bd4f37e6e5948fc99 Mon Sep 17 00:00:00 2001 From: Johannes Ewald Date: Thu, 10 Jul 2014 20:16:59 +0200 Subject: Update README - Add documentation for revert feature - Reformat docs --- README.md | 92 +++++++++++++++++++++++++++++++++++++++++---------------------- 1 file changed, 60 insertions(+), 32 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 077e754..c0571eb 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,11 @@ rewire ===== **Easy dependency injection for node.js unit testing**. +[![Build Status](https://travis-ci.org/jhnns/rewire.svg?branch=master)](http://travis-ci.org/jhnns/rewire) +[![Dependency Status](https://david-dm.org/jhnns/rewire.svg)](https://david-dm.org/jhnns/rewire) +[![Coverage Status](https://img.shields.io/coveralls/jhnns/rewire.svg)](https://coveralls.io/r/jhnns/rewire) +[![Gittip Donate Button](http://img.shields.io/gittip/peerigon.svg)](https://www.gittip.com/peerigon/) + rewire adds a special setter and getter to modules so you can modify their behaviour for better unit testing. You may - inject mocks for other modules or globals like `process` @@ -17,28 +22,17 @@ case CoffeeScript needs to be listed in your devDependencies. If you want to use rewire also on the client-side take a look at [client-side bundlers](https://github.com/jhnns/rewire#client-side-bundlers) -[![Build Status](https://travis-ci.org/jhnns/rewire.svg?branch=master)](http://travis-ci.org/jhnns/rewire) -[![Dependency Status](https://david-dm.org/jhnns/rewire.svg)](https://david-dm.org/jhnns/rewire) -[![Coverage Status](https://img.shields.io/coveralls/jhnns/rewire.svg)](https://coveralls.io/r/jhnns/rewire) -[![Gittip Donate Button](http://img.shields.io/gittip/peerigon.svg)](https://www.gittip.com/peerigon/) +[![npm status](https://nodei.co/npm/rewire.svg?downloads=true&stars=true)](https://npmjs.org/package/rewire)
-Installation ------------- - -`npm install rewire` - -
- -Examples +Introduction -------- Imagine you want to test this module: +`lib/myModule.js` ```javascript -// lib/myModule.js - // With rewire you can change all these variables var fs = require("fs"), path = "/somewhere/on/the/disk"; @@ -53,9 +47,8 @@ exports.readSomethingFromFileSystem = readSomethingFromFileSystem; Now within your test module: +`test/myModule.test.js` ```javascript -// test/myModule.test.js - var rewire = require("rewire"); var myModule = rewire("../lib/myModule.js"); @@ -68,7 +61,7 @@ myModule.__set__("path", "/dev/null"); myModule.__get__("path"); // = '/dev/null' ``` -This allows you to mock everything in the top-level scope of the module, like the fs-module for example. Just pass the variable name as first parameter and your mock as second. +This allows you to mock everything in the top-level scope of the module, like the fs module for example. Just pass the variable name as first parameter and your mock as second. ```javascript var fsMock = { @@ -84,7 +77,7 @@ myModule.readSomethingFromFileSystem(function (err, data) { }); ``` -You can also set different variables with one call. +You can also set multiple variables with one call. ```javascript myModule.__set__({ @@ -106,6 +99,40 @@ myModule.__set__({ }); ``` +`__set__` returns a function which reverts the changes introduced by this particular `__set__` call + +```javascript +var revert = myModule.__set__("port", 3000); + +// port is now 3000 +revert(); +// port is now the previous value +``` + +For your convenience you can also use the `__with__` method which reverts the given changes after it finished. + +```javascript +myModule.__with__({ + port: 3000 +})(function () { + // within this function port is 3000 +}); +// now port is the previous value again +``` + +The `__with__` method is also aware of promises. If a thenable is returned all changes stay until the promise has either been resolved or rejected. + +```javascript +myModule.__with__({ + port: 3000 +})(function () { + return new Promise(...); +}).then(function () { + // now port is the previous value again +}); +// port is still 3000 here because the promise hasn't been resolved yet +``` + ### Caveats **Difference to require()**
@@ -126,27 +153,28 @@ myModule.__set__("console.log", function () { /* be quiet */ });
-##API +API +------ + +### rewire(filename: String): rewiredModule + +Returns a rewired version of the module found at `filename`. Use `rewire()` exactly like `require()`. + +### rewiredModule.__set__(name: String, value: *): Function -###rewire(filename): rewiredModule +Sets the internal variable `name` to the given `value`. Returns a function which can be called to revert the change. -- *filename*:
-Path to the module that shall be rewired. Use it exactly like require(). +### rewiredModule.__set__(obj: Object): Function -###rewiredModule.__set__(name, value) +Takes all enumerable keys of `obj` as variable names and sets the values respectively. Returns a function which can be called to revert the change. -- *name*:
-Name of the variable to set. The variable should be global or defined with `var` in the top-leve scope of the module. -- *value*:
-The value to set. +### rewiredModule.__get__(name: String): * -###rewiredModule.__set__(env) -- *env*:
-Takes all keys as variable names and sets the values respectively. +Returns the private variable with the given `name`. -###rewiredModule.__get__(name): value +### rewiredModule.__with__(obj: Object): Function<callback: Function> -Returns the private variable. +Returns a function which - when being called - sets `obj`, executes the given `callback` and reverts `obj`. If `callback` returns a promise, `obj` is only reverted after the promise has been resolved or rejected. For your convenience the returned function passes the received promise through.
-- cgit v1.2.3