0
# Coverage Summaries
1

2
Coverage summaries provide aggregated coverage statistics with totals, covered counts, and percentages for lines, statements, functions, and branches.
3

4
## Capabilities
5

6
### CoverageSummary Constructor
7

8
Creates a coverage summary object from existing data or creates an empty summary.
9

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

18
**Usage Examples:**
19

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

23
// Create empty coverage summary
24
const summary = createCoverageSummary();
25

26
// Create from existing summary data
27
const summary = createCoverageSummary(existingSummaryData);
28

29
// Create from another CoverageSummary
30
const summary = createCoverageSummary(existingSummary);
31
```
32

33
### Merge Coverage Summaries
34

35
Merges another coverage summary into this one, combining all statistics.
36

37
```javascript { .api }
38
/**
39
 * Merges another coverage summary into this one
40
 * @param {CoverageSummary} obj - Summary to merge
41
 * @returns {CoverageSummary} This summary (for chaining)
42
 */
43
merge(obj): CoverageSummary
44
```
45

46
**Usage Examples:**
47

48
```javascript
49
const { createCoverageSummary } = require('istanbul-lib-coverage');
50

51
const totalSummary = createCoverageSummary();
52
const fileSummary1 = createCoverageSummary(file1Summary);
53
const fileSummary2 = createCoverageSummary(file2Summary);
54

55
// Merge multiple summaries
56
totalSummary.merge(fileSummary1).merge(fileSummary2);
57

58
console.log('Combined coverage:', totalSummary);
59
```
60

61
### Check If Empty
62

63
Returns true if the summary represents zero lines of code.
64

65
```javascript { .api }
66
/**
67
 * Returns true if summary has no lines of code
68
 * @returns {boolean} True if no lines of code
69
 */
70
isEmpty(): boolean
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
const summary = createCoverageSummary();
77

78
if (summary.isEmpty()) {
79
  console.log('No coverage data available');
80
} else {
81
  console.log('Coverage data present');
82
}
83
```
84

85
### JSON Serialization
86

87
Returns a JSON-serializable representation of the coverage summary.
88

89
```javascript { .api }
90
/**
91
 * Returns JSON-serializable POJO
92
 * @returns {Object} Raw summary data
93
 */
94
toJSON(): Object
95
```
96

97
**Usage Examples:**
98

99
```javascript
100
const summary = createCoverageSummary(summaryData);
101
const jsonData = summary.toJSON();
102

103
// Save summary to file
104
const fs = require('fs');
105
fs.writeFileSync('coverage-summary.json', JSON.stringify(jsonData, null, 2));
106

107
// Send in API response
108
response.json(jsonData);
109
```
110

111
## Data Properties
112

113
Coverage summary objects expose statistics through getter properties:
114

115
```javascript { .api }
116
// Coverage statistics for each metric
117
lines: CoverageStats             // Line coverage statistics
118
statements: CoverageStats        // Statement coverage statistics  
119
functions: CoverageStats         // Function coverage statistics
120
branches: CoverageStats          // Branch coverage statistics
121
branchesTrue: CoverageStats      // Branch truthiness statistics (optional)
122
```
123

124
**Usage Examples:**
125

126
```javascript
127
const summary = createCoverageSummary(summaryData);
128

129
console.log('Coverage Statistics:');
130
console.log(`Lines: ${summary.lines.covered}/${summary.lines.total} (${summary.lines.pct}%)`);
131
console.log(`Statements: ${summary.statements.covered}/${summary.statements.total} (${summary.statements.pct}%)`);
132
console.log(`Functions: ${summary.functions.covered}/${summary.functions.total} (${summary.functions.pct}%)`);
133
console.log(`Branches: ${summary.branches.covered}/${summary.branches.total} (${summary.branches.pct}%)`);
134

135
// Check for branch truthiness data
136
if (summary.branchesTrue && summary.branchesTrue.total > 0) {
137
  console.log(`Branch Truthiness: ${summary.branchesTrue.covered}/${summary.branchesTrue.total} (${summary.branchesTrue.pct}%)`);
138
}
139
```
140

141
## Coverage Statistics Structure
142

143
Each coverage metric (lines, statements, functions, branches) follows this structure:
144

145
```javascript { .api }
146
interface CoverageStats {
147
  total: number;                 // Total count of items
148
  covered: number;               // Count of covered items
149
  skipped: number;               // Count of skipped items
150
  pct: number | 'Unknown';       // Coverage percentage (0-100) or 'Unknown'
151
}
152
```
153

154
## Summary Data Structure
155

156
The complete coverage summary data structure:
157

158
```javascript { .api }
159
interface CoverageSummaryData {
160
  lines: CoverageStats;          // Line coverage statistics
161
  statements: CoverageStats;     // Statement coverage statistics
162
  functions: CoverageStats;      // Function coverage statistics
163
  branches: CoverageStats;       // Branch coverage statistics
164
  branchesTrue?: CoverageStats;  // Branch truthiness statistics (optional)
165
}
166
```
167

168
**Example Summary Object:**
169

170
```javascript
171
{
172
  lines: { total: 100, covered: 85, skipped: 0, pct: 85.0 },
173
  statements: { total: 150, covered: 120, skipped: 0, pct: 80.0 },
174
  functions: { total: 25, covered: 20, skipped: 0, pct: 80.0 },
175
  branches: { total: 50, covered: 30, skipped: 0, pct: 60.0 },
176
  branchesTrue: { total: 50, covered: 25, skipped: 0, pct: 50.0 }
177
}
178
```
179

180
## Common Usage Patterns
181

182
### Aggregating File Summaries
183

184
```javascript
185
const { createCoverageSummary } = require('istanbul-lib-coverage');
186

187
// Aggregate coverage from multiple files
188
const totalSummary = createCoverageSummary();
189

190
fileCoverageObjects.forEach(fc => {
191
  const fileSummary = fc.toSummary();
192
  totalSummary.merge(fileSummary);
193
});
194

195
console.log('Total project coverage:', totalSummary);
196
```
197

198
### Coverage Reporting
199

200
```javascript
201
function generateCoverageReport(summary) {
202
  const metrics = ['lines', 'statements', 'functions', 'branches'];
203
  
204
  console.log('Coverage Report:');
205
  console.log('================');
206
  
207
  metrics.forEach(metric => {
208
    const stats = summary[metric];
209
    const status = stats.pct >= 80 ? '✓' : '✗';
210
    console.log(`${status} ${metric}: ${stats.covered}/${stats.total} (${stats.pct}%)`);
211
  });
212
}
213
```
214

215
### Threshold Checking
216

217
```javascript
218
function checkCoverageThresholds(summary, thresholds = { lines: 80, statements: 80, functions: 80, branches: 80 }) {
219
  const results = {};
220
  
221
  Object.entries(thresholds).forEach(([metric, threshold]) => {
222
    const actual = summary[metric].pct;
223
    results[metric] = {
224
      actual,
225
      threshold,
226
      passed: typeof actual === 'number' && actual >= threshold
227
    };
228
  });
229
  
230
  return results;
231
}
232
```