0
# Istanbul Lib Coverage
1
2
Istanbul Lib Coverage is a data library for Istanbul coverage objects providing a read-only API with the ability to merge and summarize coverage information. It supersedes `object-utils` and `collector` from the v0 Istanbul API and serves as a foundational component for code coverage analysis and reporting.
3
4
## Package Information
5
6
- **Package Name**: istanbul-lib-coverage
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install istanbul-lib-coverage`
10
11
## Core Imports
12
13
```javascript
14
const {
15
createCoverageMap,
16
createFileCoverage,
17
createCoverageSummary
18
} = require('istanbul-lib-coverage');
19
```
20
21
For ES modules:
22
23
```javascript
24
import {
25
createCoverageMap,
26
createFileCoverage,
27
createCoverageSummary
28
} from 'istanbul-lib-coverage';
29
```
30
31
## Basic Usage
32
33
```javascript
34
const libCoverage = require('istanbul-lib-coverage');
35
36
// Create a coverage map from global coverage data
37
const map = libCoverage.createCoverageMap(globalCoverageVar);
38
39
// Create a summary to aggregate coverage statistics
40
const summary = libCoverage.createCoverageSummary();
41
42
// Merge another coverage map
43
map.merge(otherCoverageMap);
44
45
// Process all files and aggregate summaries
46
map.files().forEach(function(f) {
47
const fc = map.fileCoverageFor(f);
48
const s = fc.toSummary();
49
summary.merge(s);
50
});
51
52
console.log('Global summary', summary);
53
```
54
55
## Architecture
56
57
Istanbul Lib Coverage is built around three core components:
58
59
- **Coverage Maps**: Collections of file coverage objects keyed by file path, providing operations for merging and filtering coverage data across multiple files
60
- **File Coverage**: Individual file coverage objects containing statement, function, and branch coverage data with methods for analysis and merging
61
- **Coverage Summaries**: Aggregated coverage statistics with totals, covered counts, and percentages for lines, statements, functions, and branches
62
63
## Capabilities
64
65
### Factory Functions
66
67
Core factory functions for creating coverage objects with validation and type coercion.
68
69
```javascript { .api }
70
/**
71
* Creates a coverage summary object
72
* @param {Object} [obj] - Optional coverage summary data
73
* @returns {CoverageSummary}
74
*/
75
function createCoverageSummary(obj);
76
77
/**
78
* Creates a CoverageMap object
79
* @param {Object} [obj] - Optional coverage map data
80
* @returns {CoverageMap}
81
*/
82
function createCoverageMap(obj);
83
84
/**
85
* Creates a FileCoverage object
86
* @param {Object|String} [obj] - File path or coverage data
87
* @returns {FileCoverage}
88
*/
89
function createFileCoverage(obj);
90
```
91
92
### Classes Export
93
94
Access to the underlying classes for advanced usage scenarios.
95
96
```javascript { .api }
97
/**
98
* Classes exported for reuse
99
*/
100
const classes = {
101
FileCoverage: FileCoverage // The FileCoverage constructor class
102
};
103
```
104
105
**Usage Examples:**
106
107
```javascript
108
const { classes } = require('istanbul-lib-coverage');
109
110
// Direct instantiation using the class constructor
111
const fileCoverage = new classes.FileCoverage('/src/file.js');
112
113
// Access class for type checking
114
if (coverageObj instanceof classes.FileCoverage) {
115
console.log('This is a FileCoverage instance');
116
}
117
```
118
119
### Coverage Maps
120
121
Map-like collections of file coverage objects with merging, filtering, and analysis capabilities.
122
123
```javascript { .api }
124
class CoverageMap {
125
constructor(obj);
126
merge(obj): void;
127
filter(callback): void;
128
files(): string[];
129
fileCoverageFor(file): FileCoverage;
130
addFileCoverage(fc): void;
131
getCoverageSummary(): CoverageSummary;
132
toJSON(): Object;
133
}
134
```
135
136
[Coverage Maps](./coverage-maps.md)
137
138
### File Coverage
139
140
Individual file coverage objects with detailed coverage analysis and merging capabilities.
141
142
```javascript { .api }
143
class FileCoverage {
144
constructor(pathOrObj, reportLogic);
145
getLineCoverage(): Object;
146
getUncoveredLines(): string[];
147
getBranchCoverageByLine(): Object;
148
merge(other): void;
149
resetHits(): void;
150
toSummary(): CoverageSummary;
151
toJSON(): Object;
152
}
153
```
154
155
[File Coverage](./file-coverage.md)
156
157
### Coverage Summaries
158
159
Aggregated coverage statistics with merging capabilities for comprehensive reporting.
160
161
```javascript { .api }
162
class CoverageSummary {
163
constructor(obj);
164
merge(obj): CoverageSummary;
165
isEmpty(): boolean;
166
toJSON(): Object;
167
}
168
```
169
170
[Coverage Summaries](./coverage-summaries.md)
171
172
## Types
173
174
```javascript { .api }
175
// Coverage data structure for individual files
176
interface FileCoverageData {
177
path: string; // File path
178
statementMap: Object; // Statement location mapping
179
fnMap: Object; // Function metadata mapping
180
branchMap: Object; // Branch metadata mapping
181
s: Object; // Statement hit counts
182
f: Object; // Function hit counts
183
b: Object; // Branch hit counts
184
bT?: Object; // Branch truthiness (optional)
185
}
186
187
// Coverage summary statistics
188
interface CoverageStats {
189
total: number; // Total count
190
covered: number; // Covered count
191
skipped: number; // Skipped count
192
pct: number | string; // Coverage percentage
193
}
194
195
// Complete coverage summary
196
interface CoverageSummaryData {
197
lines: CoverageStats; // Line coverage
198
statements: CoverageStats; // Statement coverage
199
functions: CoverageStats; // Function coverage
200
branches: CoverageStats; // Branch coverage
201
branchesTrue?: CoverageStats; // Branch truthiness (optional)
202
}
203
```