0
# Coverage Maps
1

2
Coverage maps are collections of file coverage objects keyed by file path, providing operations for merging, filtering, and analyzing coverage data across multiple files.
3

4
## Capabilities
5

6
### CoverageMap Constructor
7

8
Creates a new coverage map from existing coverage data or another coverage map.
9

10
```javascript { .api }
11
/**
12
 * Creates a CoverageMap instance
13
 * @param {Object|CoverageMap} [obj] - Coverage map data or existing CoverageMap
14
 */
15
constructor(obj)
16
```
17

18
**Usage Examples:**
19

20
```javascript
21
const { createCoverageMap } = require('istanbul-lib-coverage');
22

23
// Create empty coverage map
24
const map = createCoverageMap();
25

26
// Create from global coverage variable
27
const map = createCoverageMap(global.__coverage__);
28

29
// Create from existing coverage map
30
const map = createCoverageMap(existingMap);
31
```
32

33
### Merge Coverage Maps
34

35
Merges another coverage map into the current one, combining coverage data for matching files.
36

37
```javascript { .api }
38
/**
39
 * Merges another coverage map into this one
40
 * @param {CoverageMap|Object} obj - Coverage map to merge
41
 */
42
merge(obj): void
43
```
44

45
**Usage Examples:**
46

47
```javascript
48
const map1 = createCoverageMap(coverage1);
49
const map2 = createCoverageMap(coverage2);
50

51
// Merge map2 into map1
52
map1.merge(map2);
53

54
// Merge raw coverage data
55
map1.merge(rawCoverageData);
56
```
57

58
### Filter Coverage Map
59

60
Filters the coverage map based on file paths using a callback function.
61

62
```javascript { .api }
63
/**
64
 * Filters coverage map based on callback
65
 * @param {Function} callback - Returns true if path should be included
66
 */
67
filter(callback): void
68
```
69

70
**Usage Examples:**
71

72
```javascript
73
const map = createCoverageMap(globalCoverage);
74

75
// Keep only JavaScript files
76
map.filter(filePath => filePath.endsWith('.js'));
77

78
// Exclude test files
79
map.filter(filePath => !filePath.includes('test'));
80

81
// Keep specific directory
82
map.filter(filePath => filePath.startsWith('/src/'));
83
```
84

85
### Get File List
86

87
Returns an array of file paths for which the map has coverage data.
88

89
```javascript { .api }
90
/**
91
 * Returns array of file paths with coverage
92
 * @returns {string[]} Array of file paths
93
 */
94
files(): string[]
95
```
96

97
**Usage Examples:**
98

99
```javascript
100
const map = createCoverageMap(globalCoverage);
101
const files = map.files();
102

103
console.log(`Coverage available for ${files.length} files:`);
104
files.forEach(file => console.log(file));
105
```
106

107
### Get File Coverage
108

109
Returns the file coverage object for a specified file path.
110

111
```javascript { .api }
112
/**
113
 * Returns file coverage for specified file
114
 * @param {string} file - File path
115
 * @returns {FileCoverage} File coverage object
116
 * @throws {Error} If file not found in map
117
 */
118
fileCoverageFor(file): FileCoverage
119
```
120

121
**Usage Examples:**
122

123
```javascript
124
const map = createCoverageMap(globalCoverage);
125

126
try {
127
  const fileCoverage = map.fileCoverageFor('/src/index.js');
128
  console.log('Line coverage:', fileCoverage.getLineCoverage());
129
} catch (error) {
130
  console.error('File not found:', error.message);
131
}
132
```
133

134
### Add File Coverage
135

136
Adds a file coverage object to the map, merging with existing coverage if the path already exists.
137

138
```javascript { .api }
139
/**
140
 * Adds file coverage to map, merging if path exists
141
 * @param {FileCoverage} fc - File coverage object to add
142
 */
143
addFileCoverage(fc): void
144
```
145

146
**Usage Examples:**
147

148
```javascript
149
const { createCoverageMap, createFileCoverage } = require('istanbul-lib-coverage');
150

151
const map = createCoverageMap();
152
const fileCoverage = createFileCoverage('/src/utils.js');
153

154
// Add new file coverage
155
map.addFileCoverage(fileCoverage);
156

157
// Adding duplicate path will merge coverage
158
const anotherFileCoverage = createFileCoverage('/src/utils.js');
159
map.addFileCoverage(anotherFileCoverage); // Merges with existing
160
```
161

162
### Get Coverage Summary
163

164
Returns an aggregated coverage summary for all files in the map.
165

166
```javascript { .api }
167
/**
168
 * Returns coverage summary for all files in map
169
 * @returns {CoverageSummary} Aggregated coverage summary
170
 */
171
getCoverageSummary(): CoverageSummary
172
```
173

174
**Usage Examples:**
175

176
```javascript
177
const map = createCoverageMap(globalCoverage);
178
const summary = map.getCoverageSummary();
179

180
console.log('Overall coverage:');
181
console.log(`Lines: ${summary.lines.pct}%`);
182
console.log(`Statements: ${summary.statements.pct}%`);
183
console.log(`Functions: ${summary.functions.pct}%`);
184
console.log(`Branches: ${summary.branches.pct}%`);
185
```
186

187
### JSON Serialization
188

189
Returns a JSON-serializable representation of the coverage map.
190

191
```javascript { .api }
192
/**
193
 * Returns JSON-serializable POJO
194
 * @returns {Object} Raw coverage map data
195
 */
196
toJSON(): Object
197
```
198

199
**Usage Examples:**
200

201
```javascript
202
const map = createCoverageMap(globalCoverage);
203
const jsonData = map.toJSON();
204

205
// Save to file
206
const fs = require('fs');
207
fs.writeFileSync('coverage.json', JSON.stringify(jsonData, null, 2));
208

209
// Send over network
210
response.json(jsonData);
211
```