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 | var MemoryStore = require('./store/memory'),
|
7 | utils = require('./object-utils');
|
8 |
|
9 | /**
|
10 | * a mechanism to merge multiple coverage objects into one. Handles the use case
|
11 | * of overlapping coverage information for the same files in multiple coverage
|
12 | * objects and does not double-count in this situation. For example, if
|
13 | * you pass the same coverage object multiple times, the final merged object will be
|
14 | * no different that any of the objects passed in (except for execution counts).
|
15 | *
|
16 | * The `Collector` is built for scale to handle thousands of coverage objects.
|
17 | * By default, all processing is done in memory since the common use-case is of
|
18 | * one or a few coverage objects. You can work around memory
|
19 | * issues by passing in a `Store` implementation that stores temporary computations
|
20 | * on disk (the `tmp` store, for example).
|
21 | *
|
22 | * The `getFinalCoverage` method returns an object with merged coverage information
|
23 | * and is provided as a convenience for implementors working with coverage information
|
24 | * that can fit into memory. Reporters, in the interest of generality, should *not* use this method for
|
25 | * creating reports.
|
26 | *
|
27 | * Usage
|
28 | * -----
|
29 | *
|
30 | * var collector = new require('istanbul').Collector();
|
31 | *
|
32 | * files.forEach(function (f) {
|
33 | * //each coverage object can have overlapping information about multiple files
|
34 | * collector.add(JSON.parse(fs.readFileSync(f, 'utf8')));
|
35 | * });
|
36 | *
|
37 | * collector.files().forEach(function(file) {
|
38 | * var fileCoverage = collector.fileCoverageFor(file);
|
39 | * console.log('Coverage for ' + file + ' is:' + JSON.stringify(fileCoverage));
|
40 | * });
|
41 | *
|
42 | * // convenience method: do not use this when dealing with a large number of files
|
43 | * var finalCoverage = collector.getFinalCoverage();
|
44 | *
|
45 | * @class Collector
|
46 | * @module main
|
47 | * @constructor
|
48 | * @param {Object} options Optional. Configuration options.
|
49 | * @param {Store} options.store - an implementation of `Store` to use for temporary
|
50 | * calculations.
|
51 | */
|
52 | function Collector(options) {
|
53 | options = options || {};
|
54 | this.store = options.store || new MemoryStore();
|
55 | }
|
56 |
|
57 | Collector.prototype = {
|
58 | /**
|
59 | * adds a coverage object to the collector.
|
60 | *
|
61 | * @method add
|
62 | * @param {Object} coverage the coverage object.
|
63 | * @param {String} testName Optional. The name of the test used to produce the object.
|
64 | * This is currently not used.
|
65 | */
|
66 | add: function (coverage /*, testName */) {
|
67 | var store = this.store;
|
68 | Object.keys(coverage).forEach(function (key) {
|
69 | var fileCoverage = coverage[key];
|
70 | if (store.hasKey(key)) {
|
71 | store.setObject(key, utils.mergeFileCoverage(fileCoverage, store.getObject(key)));
|
72 | } else {
|
73 | store.setObject(key, fileCoverage);
|
74 | }
|
75 | });
|
76 | },
|
77 | /**
|
78 | * returns a list of unique file paths for which coverage information has been added.
|
79 | * @method files
|
80 | * @return {Array} an array of file paths for which coverage information is present.
|
81 | */
|
82 | files: function () {
|
83 | return this.store.keys();
|
84 | },
|
85 | /**
|
86 | * return file coverage information for a single file
|
87 | * @method fileCoverageFor
|
88 | * @param {String} fileName the path for the file for which coverage information is
|
89 | * required. Must be one of the values returned in the `files()` method.
|
90 | * @return {Object} the coverage information for the specified file.
|
91 | */
|
92 | fileCoverageFor: function (fileName) {
|
93 | var ret = this.store.getObject(fileName);
|
94 | utils.addDerivedInfoForFile(ret);
|
95 | return ret;
|
96 | },
|
97 | /**
|
98 | * returns file coverage information for all files. This has the same format as
|
99 | * any of the objects passed in to the `add` method. The number of keys in this
|
100 | * object will be a superset of all keys found in the objects passed to `add()`
|
101 | * @method getFinalCoverage
|
102 | * @return {Object} the merged coverage information
|
103 | */
|
104 | getFinalCoverage: function () {
|
105 | var ret = {},
|
106 | that = this;
|
107 | this.files().forEach(function (file) {
|
108 | ret[file] = that.fileCoverageFor(file);
|
109 | });
|
110 | return ret;
|
111 | },
|
112 | /**
|
113 | * disposes this collector and reclaims temporary resources used in the
|
114 | * computation. Calls `dispose()` on the underlying store.
|
115 | * @method dispose
|
116 | */
|
117 | dispose: function () {
|
118 | this.store.dispose();
|
119 | }
|
120 | };
|
121 |
|
122 | module.exports = Collector; |
\ | No newline at end of file |