1 | # proxyquireify [![build status](https://secure.travis-ci.org/thlorenz/proxyquireify.png)](http://travis-ci.org/thlorenz/proxyquireify)
|
2 |
|
3 | browserify v2 version of [proxyquire](https://github.com/thlorenz/proxyquire).
|
4 |
|
5 | Proxies browserify's require in order to make overriding dependencies during testing easy while staying **totally unobstrusive**.
|
6 |
|
7 | **Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
|
8 |
|
9 | - [Features](#features)
|
10 | - [Installation](#installation)
|
11 | - [Example](#example)
|
12 | - [API](#api)
|
13 | - [proxyquire.browserify()](#proxyquirebrowserify)
|
14 | - [proxyquire(request: String, stubs: Object)](#proxyquirerequest:-string-stubs:-object)
|
15 | - [Important Magic](#important-magic)
|
16 | - [noCallThru](#nocallthru)
|
17 | - [More Examples](#more-examples)
|
18 |
|
19 | ## Features
|
20 |
|
21 | - **no changes to your code** are necessary
|
22 | - non overriden methods of a module behave like the original
|
23 | - mocking framework agnostic, if it can stub a function then it works with proxyquireify
|
24 | - "use strict" compliant
|
25 | - [automatic injection](https://github.com/thlorenz/proxyquireify#important-magic) of `require` calls to ensure the
|
26 | module you are testing gets bundled
|
27 |
|
28 | ## Installation
|
29 |
|
30 | npm install proxyquireify
|
31 |
|
32 | ## Example
|
33 |
|
34 | **foo.js**:
|
35 |
|
36 | ```js
|
37 | var bar = require('./bar');
|
38 |
|
39 | module.exports = function () {
|
40 | return bar.kinder() + ' ist ' + bar.wunder();
|
41 | };
|
42 | ```
|
43 |
|
44 | **foo.test.js**:
|
45 |
|
46 | ```js
|
47 | var proxyquire = require('proxyquireify')(require);
|
48 |
|
49 | var stubs = {
|
50 | './bar': {
|
51 | wunder: function () { return 'wirklich wunderbar'; }
|
52 | , kinder: function () { return 'schokolade'; }
|
53 | }
|
54 | };
|
55 |
|
56 | var foo = proxyquire('./src/foo', stubs);
|
57 |
|
58 | console.log(foo());
|
59 | ```
|
60 |
|
61 | **browserify.build.js**:
|
62 |
|
63 | ```js
|
64 | var proxyquire = require('proxyquireify');
|
65 |
|
66 | proxyquire.browserify()
|
67 | .require(require.resolve('./foo.test'), { entry: true })
|
68 | .bundle({ debug: true })
|
69 | .pipe(fs.createWriteStream(__dirname + '/bundle.js'));
|
70 | ```
|
71 |
|
72 | load it in the browser and see:
|
73 |
|
74 | schokolade ist wirklich wunderbar
|
75 |
|
76 | ## API
|
77 |
|
78 | ### proxyquire.browserify()
|
79 |
|
80 | To be used in build script instead of `browserify()`, autmatically adapts browserify to work for tests and injects
|
81 | require overrides into all modules via a browserify transform.
|
82 |
|
83 | ```js
|
84 | proxyquire.browserify()
|
85 | .require(require.resolve('./test'), { entry: true })
|
86 | .bundle()
|
87 | .pipe(fs.createWriteStream(__dirname + '/bundle.js'));
|
88 | ```
|
89 |
|
90 | ### proxyquire(request: String, stubs: Object)
|
91 |
|
92 | - **request**: path to the module to be tested e.g., `../lib/foo`
|
93 | - **stubs**: key/value pairs of the form `{ modulePath: stub, ... }`
|
94 | - module paths are relative to the tested module **not** the test file
|
95 | - therefore specify it exactly as in the require statement inside the tested file
|
96 | - values themselves are key/value pairs of functions/properties and the appropriate override
|
97 |
|
98 | ```js
|
99 | var proxyquire = require('proxyquireify')(require);
|
100 | var barStub = { wunder: function () { 'really wonderful'; } };
|
101 |
|
102 | var foo = proxyquire('./foo', { './bar': barStub })
|
103 | ```
|
104 |
|
105 | #### Important Magic
|
106 |
|
107 | In order for browserify to include the module you are testing in the bundle, proxyquireify will inject a
|
108 | `require()` call for every module you are proxyquireing. So in the above example `require('./foo')` will be injected at
|
109 | the top of your test file.
|
110 |
|
111 | ### noCallThru
|
112 |
|
113 | By default proxyquireify calls the function defined on the *original* dependency whenever it is not found on the stub.
|
114 |
|
115 | If you prefer a more strict behavior you can prevent *callThru* on a per module or per stub basis.
|
116 |
|
117 | If *callThru* is disabled, you can stub out modules that weren't even included in the bundle. **Note**, that unlike in
|
118 | proxquire, there is no option to prevent call thru globally.
|
119 |
|
120 | ```js
|
121 | // Prevent callThru for path module only
|
122 | var foo = proxyquire('./foo', {
|
123 | path: {
|
124 | extname: function (file) { ... }
|
125 | , '@noCallThru': true
|
126 | }
|
127 | , fs: { readdir: function (..) { .. } }
|
128 | });
|
129 |
|
130 | // Prevent call thru for all contained stubs (path and fs)
|
131 | var foo = proxyquire('./foo', {
|
132 | path: {
|
133 | extname: function (file) { ... }
|
134 | }
|
135 | , fs: { readdir: function (..) { .. } }
|
136 | , '@noCallThru': true
|
137 | });
|
138 |
|
139 | // Prevent call thru for all stubs except path
|
140 | var foo = proxyquire('./foo', {
|
141 | path: {
|
142 | extname: function (file) { ... }
|
143 | , '@noCallThru': false
|
144 | }
|
145 | , fs: { readdir: function (..) { .. } }
|
146 | , '@noCallThru': true
|
147 | });
|
148 | ```
|
149 |
|
150 | ## More Examples
|
151 |
|
152 | - [foobar](https://github.com/thlorenz/proxyquireify/tree/master/examples/foobar)
|