Code coverage report for istanbul/lib/hook.js

Statements: 100% (44 / 44)      Branches: 95.83% (23 / 24)      Functions: 100% (10 / 10)      Lines: 100% (44 / 44)     

All files » istanbul/lib/ » hook.js
1 /*
2 Copyright (c) 2012, Yahoo! Inc. All rights reserved.
3 Copyrights licensed under the New BSD License. See the accompanying LICENSE file for terms.
4 */
5
6 /**
7 * provides a mechanism to transform code in the scope of `require` or `vm.createScript`.
8 * This mechanism is general and relies on a user-supplied `matcher` function that determines when transformations should be
9 * performed and a user-supplied `transformer` function that performs the actual transform.
10 * Instrumenting code for coverage is one specific example of useful hooking.
11 *
12 * Note that both the `matcher` and `transformer` must execute synchronously.
13 *
14 * For the common case of matching filesystem paths based on inclusion/ exclusion patterns, use the `matcherFor`
15 * function in the istanbul API to get a matcher.
16 *
17 * It is up to the transformer to perform processing with side-effects, such as caching, storing the original
18 * source code to disk in case of dynamically generated scripts etc. The `Store` class can help you with this.
19 *
20 * Usage
21 * -----
22 *
23 * var hook = require('istanbul').hook,
24 * myMatcher = function (file) { return file.match(/foo/); },
25 * myTransformer = function (code, file) { return 'console.log("' + file + '");' + code; };
26 *
27 * hook.hookRequire(myMatcher, myTransformer);
28 *
29 * var foo = require('foo'); //will now print foo's module path to console
30 *
31 * @class Hook
32 */
33 /*jslint nomen: true */
34 1 var path = require('path'),
35 fs = require('fs'),
36 Module = require('module'),
37 vm = require('vm'),
38 originalLoader = Module._extensions['.js'],
39 originalCreateScript = vm.createScript,
40 lastMatcher;
41
42 1 function transformFn(matcher, transformer, verbose) {
43
44 9 return function (code, filename) {
45 6 var shouldHook = matcher(filename),
46 transformed,
47 changed = false;
48
49 6 if (shouldHook) {
50 5 if (verbose) {
51 1 console.error('Module load hook: transform [' + filename + ']');
52 }
53 5 try {
54 5 transformed = transformer(code, filename);
55 4 changed = true;
56 } catch (ex) {
57 1 console.error('Transformation error; return original code');
58 1 console.error(ex);
59 1 transformed = code;
60 }
61 } else {
62 1 transformed = code;
63 }
64 6 return { code: transformed, changed: changed };
65 };
66 }
67
68 1 function unloadRequireCache(matcher) {
69 11 Eif (matcher && typeof require !== 'undefined' && require && require.cache) {
70 11 Object.keys(require.cache).forEach(function (filename) {
71 1343 if (matcher(filename)) {
72 3 delete require.cache[filename];
73 }
74 });
75 }
76 }
77 /**
78 * hooks `require` to return transformed code to the node module loader.
79 * Exceptions in the transform result in the original code being used instead.
80 * @method hookRequire
81 * @static
82 * @param matcher {Function(filePath)} a function that is called with the absolute path to the file being
83 * `require`-d. Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise
84 * @param transformer {Function(code, filePath)} a function called with the original code and the associated path of the file
85 * from where the code was loaded. Should return the transformed code.
86 * @param options {Object} options Optional.
87 * @param {Boolean} [options.verbose] write a line to standard error every time the transformer is called
88 */
89 1 function hookRequire(matcher, transformer, options) {
90 8 options = options || {};
91 8 lastMatcher = matcher;
92 8 var fn = transformFn(matcher, transformer, options.verbose),
93 postLoadHook = options.postLoadHook
94 && typeof options.postLoadHook === 'function' ? options.postLoadHook : null;
95
96 8 Module._extensions['.js'] = function (module, filename) {
97 5 var ret = fn(fs.readFileSync(filename, 'utf8'), filename);
98 5 if (ret.changed) {
99 3 module._compile(ret.code, filename);
100 } else {
101 2 originalLoader(module, filename);
102 }
103 5 if (postLoadHook) {
104 1 postLoadHook(filename);
105 }
106 };
107 8 unloadRequireCache(matcher);
108 }
109 /**
110 * unhook `require` to restore it to its original state. Also unloads the modules in
111 * the `require` cache that would have matched the matcher provide in the
112 * `hookRequire` method.
113 * @method unhookRequire
114 * @static
115 */
116 1 function unhookRequire() {
117 3 Module._extensions['.js'] = originalLoader;
118 3 unloadRequireCache(lastMatcher);
119 }
120 /**
121 * hooks `vm.createScript` to return transformed code out of which a `Script` object will be created.
122 * Exceptions in the transform result in the original code being used instead.
123 * @method hookCreateScript
124 * @static
125 * @param matcher {Function(filePath)} a function that is called with the filename passed to `vm.createScript`
126 * Should return a truthy value when transformations need to be applied to the code, a falsy value otherwise
127 * @param transformer {Function(code, filePath)} a function called with the original code and the filename passed to
128 * `vm.createScript`. Should return the transformed code.
129 * @param options {Object} options Optional.
130 * @param {Boolean} [options.verbose] write a line to standard error every time the transformer is called
131 */
132 1 function hookCreateScript(matcher, transformer, opts) {
133 1 opts = opts || {};
134 1 var fn = transformFn(matcher, transformer, opts.verbose);
135 1 vm.createScript = function (code, file) {
136 1 var ret = fn(code, file);
137 1 return originalCreateScript(ret.code, file);
138 };
139 }
140
141 /**
142 * unhooks vm.createScript, restoring it to its original state.
143 * @method unhookCreateScript
144 * @static
145 */
146 1 function unhookCreateScript() {
147 1 vm.createScript = originalCreateScript;
148 }
149
150 1 module.exports = {
151 hookRequire: hookRequire,
152 unhookRequire: unhookRequire,
153 hookCreateScript: hookCreateScript,
154 unhookCreateScript: unhookCreateScript
155 };
156
157
158