1 | /*
|
2 | Copyright 2012-2015, Yahoo Inc.
|
3 | Copyrights licensed under the New BSD License. See the accompanying LICENSE file for terms.
|
4 | */
|
5 | const { transformSync } = require('@babel/core');
|
6 | const { defaults } = require('@istanbuljs/schema');
|
7 | const programVisitor = require('./visitor');
|
8 | const readInitialCoverage = require('./read-coverage');
|
9 |
|
10 | /**
|
11 | * Instrumenter is the public API for the instrument library.
|
12 | * It is typically used for ES5 code. For ES6 code that you
|
13 | * are already running under `babel` use the coverage plugin
|
14 | * instead.
|
15 | * @param {Object} opts optional.
|
16 | * @param {string} [opts.coverageVariable=__coverage__] name of global coverage variable.
|
17 | * @param {boolean} [opts.reportLogic=false] report boolean value of logical expressions.
|
18 | * @param {boolean} [opts.preserveComments=false] preserve comments in output.
|
19 | * @param {boolean} [opts.compact=true] generate compact code.
|
20 | * @param {boolean} [opts.esModules=false] set to true to instrument ES6 modules.
|
21 | * @param {boolean} [opts.autoWrap=false] set to true to allow `return` statements outside of functions.
|
22 | * @param {boolean} [opts.produceSourceMap=false] set to true to produce a source map for the instrumented code.
|
23 | * @param {Array} [opts.ignoreClassMethods=[]] set to array of class method names to ignore for coverage.
|
24 | * @param {Function} [opts.sourceMapUrlCallback=null] a callback function that is called when a source map URL
|
25 | * is found in the original code. This function is called with the source file name and the source map URL.
|
26 | * @param {boolean} [opts.debug=false] - turn debugging on.
|
27 | * @param {array} [opts.parserPlugins] - set babel parser plugins, see @istanbuljs/schema for defaults.
|
28 | */
|
29 | class Instrumenter {
|
30 | constructor(opts = {}) {
|
31 | this.opts = {
|
32 | ...defaults.instrumenter,
|
33 | ...opts
|
34 | };
|
35 | this.fileCoverage = null;
|
36 | this.sourceMap = null;
|
37 | }
|
38 | /**
|
39 | * instrument the supplied code and track coverage against the supplied
|
40 | * filename. It throws if invalid code is passed to it. ES5 and ES6 syntax
|
41 | * is supported. To instrument ES6 modules, make sure that you set the
|
42 | * `esModules` property to `true` when creating the instrumenter.
|
43 | *
|
44 | * @param {string} code - the code to instrument
|
45 | * @param {string} filename - the filename against which to track coverage.
|
46 | * @param {object} [inputSourceMap] - the source map that maps the not instrumented code back to it's original form.
|
47 | * Is assigned to the coverage object and therefore, is available in the json output and can be used to remap the
|
48 | * coverage to the untranspiled source.
|
49 | * @returns {string} the instrumented code.
|
50 | */
|
51 | instrumentSync(code, filename, inputSourceMap) {
|
52 | if (typeof code !== 'string') {
|
53 | throw new Error('Code must be a string');
|
54 | }
|
55 | filename = filename || String(new Date().getTime()) + '.js';
|
56 | const { opts } = this;
|
57 | let output = {};
|
58 | const babelOpts = {
|
59 | configFile: false,
|
60 | babelrc: false,
|
61 | ast: true,
|
62 | filename: filename || String(new Date().getTime()) + '.js',
|
63 | inputSourceMap,
|
64 | sourceMaps: opts.produceSourceMap,
|
65 | compact: opts.compact,
|
66 | comments: opts.preserveComments,
|
67 | parserOpts: {
|
68 | allowReturnOutsideFunction: opts.autoWrap,
|
69 | sourceType: opts.esModules ? 'module' : 'script',
|
70 | plugins: opts.parserPlugins
|
71 | },
|
72 | plugins: [
|
73 | [
|
74 | ({ types }) => {
|
75 | const ee = programVisitor(types, filename, {
|
76 | coverageVariable: opts.coverageVariable,
|
77 | reportLogic: opts.reportLogic,
|
78 | coverageGlobalScope: opts.coverageGlobalScope,
|
79 | coverageGlobalScopeFunc:
|
80 | opts.coverageGlobalScopeFunc,
|
81 | ignoreClassMethods: opts.ignoreClassMethods,
|
82 | inputSourceMap
|
83 | });
|
84 |
|
85 | return {
|
86 | visitor: {
|
87 | Program: {
|
88 | enter: ee.enter,
|
89 | exit(path) {
|
90 | output = ee.exit(path);
|
91 | }
|
92 | }
|
93 | }
|
94 | };
|
95 | }
|
96 | ]
|
97 | ]
|
98 | };
|
99 |
|
100 | const codeMap = transformSync(code, babelOpts);
|
101 |
|
102 | if (!output || !output.fileCoverage) {
|
103 | const initialCoverage =
|
104 | readInitialCoverage(codeMap.ast) ||
|
105 | /* istanbul ignore next: paranoid check */ {};
|
106 | this.fileCoverage = initialCoverage.coverageData;
|
107 | this.sourceMap = inputSourceMap;
|
108 | return code;
|
109 | }
|
110 |
|
111 | this.fileCoverage = output.fileCoverage;
|
112 | this.sourceMap = codeMap.map;
|
113 | const cb = this.opts.sourceMapUrlCallback;
|
114 | if (cb && output.sourceMappingURL) {
|
115 | cb(filename, output.sourceMappingURL);
|
116 | }
|
117 |
|
118 | return codeMap.code;
|
119 | }
|
120 | /**
|
121 | * callback-style instrument method that calls back with an error
|
122 | * as opposed to throwing one. Note that in the current implementation,
|
123 | * the callback will be called in the same process tick and is not asynchronous.
|
124 | *
|
125 | * @param {string} code - the code to instrument
|
126 | * @param {string} filename - the filename against which to track coverage.
|
127 | * @param {Function} callback - the callback
|
128 | * @param {Object} inputSourceMap - the source map that maps the not instrumented code back to it's original form.
|
129 | * Is assigned to the coverage object and therefore, is available in the json output and can be used to remap the
|
130 | * coverage to the untranspiled source.
|
131 | */
|
132 | instrument(code, filename, callback, inputSourceMap) {
|
133 | if (!callback && typeof filename === 'function') {
|
134 | callback = filename;
|
135 | filename = null;
|
136 | }
|
137 | try {
|
138 | const out = this.instrumentSync(code, filename, inputSourceMap);
|
139 | callback(null, out);
|
140 | } catch (ex) {
|
141 | callback(ex);
|
142 | }
|
143 | }
|
144 | /**
|
145 | * returns the file coverage object for the last file instrumented.
|
146 | * @returns {Object} the file coverage object.
|
147 | */
|
148 | lastFileCoverage() {
|
149 | return this.fileCoverage;
|
150 | }
|
151 | /**
|
152 | * returns the source map produced for the last file instrumented.
|
153 | * @returns {null|Object} the source map object.
|
154 | */
|
155 | lastSourceMap() {
|
156 | return this.sourceMap;
|
157 | }
|
158 | }
|
159 |
|
160 | module.exports = Instrumenter;
|