0
# Karma Coverage Istanbul Reporter
1

2
Karma Coverage Istanbul Reporter is a Karma reporter plugin that integrates with Istanbul.js 1.x APIs to generate comprehensive code coverage reports with full sourcemap support. It serves as a bridge between the Karma test runner and Istanbul coverage reporting, providing advanced features for modern JavaScript testing workflows.
3

4
## Package Information
5

6
- **Package Name**: karma-coverage-istanbul-reporter
7
- **Package Type**: npm
8
- **Language**: JavaScript (Node.js)
9
- **Installation**: `npm install karma-coverage-istanbul-reporter --save-dev`
10

11
## Core Imports
12

13
The package is used as a Karma plugin and does not provide direct imports. It exports a Karma plugin configuration:
14

15
```javascript
16
// Automatically loaded by Karma as karma-*
17
// No explicit import needed
18
```
19

20
For manual plugin registration:
21

22
```javascript
23
// karma.conf.js
24
module.exports = function(config) {
25
  config.set({
26
    plugins: ['karma-coverage-istanbul-reporter'],
27
    // ... other config
28
  });
29
};
30
```
31

32
## Basic Usage
33

34
```javascript
35
// karma.conf.js
36
const path = require('path');
37

38
module.exports = function(config) {
39
  config.set({
40
    reporters: ['coverage-istanbul'],
41
    
42
    coverageIstanbulReporter: {
43
      reports: ['html', 'lcovonly', 'text-summary'],
44
      dir: path.join(__dirname, 'coverage'),
45
      combineBrowserReports: true,
46
      fixWebpackSourcePaths: true,
47
      skipFilesWithNoCoverage: true,
48
      thresholds: {
49
        global: {
50
          statements: 80,
51
          lines: 80,
52
          branches: 80,
53
          functions: 80
54
        }
55
      }
56
    }
57
  });
58
};
59
```
60

61
## Architecture
62

63
The reporter works within the Karma plugin ecosystem:
64

65
- **Plugin Registration**: Registers the `coverage-istanbul` reporter with Karma
66
- **Coverage Collection**: Collects coverage data from instrumented code during test execution
67
- **Source Map Processing**: Handles webpack source paths and fixes sourcemap references
68
- **Report Generation**: Uses Istanbul.js libraries to generate coverage reports in multiple formats
69
- **Threshold Enforcement**: Validates coverage against configured thresholds and fails builds when not met
70

71
## Capabilities
72

73
### Karma Plugin Configuration
74

75
The main export provides the Karma plugin registration.
76

77
```javascript { .api }
78
/**
79
 * Karma plugin configuration object
80
 * Registers the coverage-istanbul reporter with Karma
81
 */
82
module.exports = {
83
  'reporter:coverage-istanbul': ['type', CoverageIstanbulReporter]
84
};
85
```
86

87
### Coverage Istanbul Reporter
88

89
The core reporter class that implements the Karma reporter interface.
90

91
```javascript { .api }
92
/**
93
 * Main reporter class for handling Istanbul coverage reporting
94
 * @param {Function} baseReporterDecorator - Karma base reporter decorator
95
 * @param {Object} logger - Karma logger instance
96
 * @param {Object} config - Karma configuration object with coverageIstanbulReporter settings
97
 */
98
function CoverageIstanbulReporter(baseReporterDecorator, logger, config);
99
```
100

101
### Configuration Options
102

103
The reporter accepts configuration through the `coverageIstanbulReporter` key in Karma config.
104

105
```javascript { .api }
106
interface CoverageIstanbulReporterConfig {
107
  /** Report types to generate (e.g., 'html', 'lcov', 'text-summary') */
108
  reports?: string[];
109
  
110
  /** Output directory for reports. Use %browser% placeholder for browser-specific paths */
111
  dir?: string;
112
  
113
  /** Combine reports from multiple browsers into one report */
114
  combineBrowserReports?: boolean;
115
  
116
  /** Fix webpack sourcemap paths for correct source mapping */
117
  fixWebpackSourcePaths?: boolean;
118
  
119
  /** Omit files with no coverage from reports */
120
  skipFilesWithNoCoverage?: boolean;
121
  
122
  /** Enable verbose logging for debugging */
123
  verbose?: boolean;
124
  
125
  /** Coverage thresholds configuration */
126
  thresholds?: {
127
    /** Emit warnings instead of errors for failed thresholds */
128
    emitWarning?: boolean;
129
    
130
    /** Global coverage thresholds */
131
    global?: CoverageThresholds;
132
    
133
    /** Per-file coverage thresholds */
134
    each?: CoverageThresholds & {
135
      /** Pattern-based threshold overrides */
136
      overrides?: { [pattern: string]: CoverageThresholds };
137
    };
138
  };
139
  
140
  /** Per-report configuration options */
141
  'report-config'?: { [reportType: string]: any };
142
  
143
  /** Istanbul watermark configuration */
144
  watermarks?: any;
145
  
146
  /** Istanbul instrumentation options */
147
  instrumentation?: any;
148
  
149
  /** Summary generation strategy */
150
  summarizer?: string;
151
}
152

153
interface CoverageThresholds {
154
  /** Statement coverage percentage threshold */
155
  statements?: number;
156
  
157
  /** Line coverage percentage threshold */
158
  lines?: number;
159
  
160
  /** Branch coverage percentage threshold */
161
  branches?: number;
162
  
163
  /** Function coverage percentage threshold */
164
  functions?: number;
165
}
166
```
167

168
### Utility Functions
169

170
The package provides utility functions for handling webpack and path-related operations.
171

172
```javascript { .api }
173
/**
174
 * Fixes webpack loader syntax and query parameters from file paths
175
 * @param {string} filePath - File path to clean
176
 * @returns {string} Cleaned file path
177
 */
178
function fixWebpackFilePath(filePath);
179

180
/**
181
 * Normalizes path separators for Windows compatibility
182
 * @param {string} filePath - File path to normalize
183
 * @returns {string} Normalized file path
184
 */
185
function fixPathSeparators(filePath);
186

187
/**
188
 * Fixes webpack source map paths for correct sourcemap resolution
189
 * @param {Object} sourceMap - Source map object
190
 * @param {Object} webpackConfig - Webpack configuration
191
 * @returns {Object} Fixed source map with corrected paths
192
 */
193
function fixWebpackSourcePaths(sourceMap, webpackConfig);
194

195
/**
196
 * Applies pattern-based threshold overrides using minimatch
197
 * @param {string} key - File path to match against patterns
198
 * @param {Object} overrides - Pattern-to-threshold mapping
199
 * @param {string} basePath - Base path for relative path resolution
200
 * @returns {Object} Matching threshold configuration
201
 */
202
function overrideThresholds(key, overrides, basePath);
203
```
204

205
### Supported Report Types
206

207
The reporter supports all Istanbul.js report types:
208

209
```javascript { .api }
210
/**
211
 * Available report types for coverage output
212
 */
213
type ReportType = 
214
  | 'clover'        // Clover XML format
215
  | 'cobertura'     // Cobertura XML format  
216
  | 'html'          // HTML report with file details
217
  | 'html-spa'      // Single-page HTML report
218
  | 'json'          // Raw JSON coverage data
219
  | 'json-summary'  // Summary JSON format
220
  | 'lcov'          // LCOV format with HTML
221
  | 'lcovonly'      // LCOV format only
222
  | 'teamcity'      // TeamCity service messages
223
  | 'text'          // Console text output
224
  | 'text-lcov'     // Text LCOV format
225
  | 'text-summary'  // Text summary output
226
  | 'none';         // No output
227
```
228

229
## Usage Examples
230

231
### Basic Configuration
232

233
```javascript
234
// karma.conf.js
235
module.exports = function(config) {
236
  config.set({
237
    reporters: ['progress', 'coverage-istanbul'],
238
    
239
    coverageIstanbulReporter: {
240
      reports: ['html', 'text-summary'],
241
      dir: 'coverage/'
242
    }
243
  });
244
};
245
```
246

247
### Advanced Configuration with Thresholds
248

249
```javascript
250
// karma.conf.js
251
module.exports = function(config) {
252
  config.set({
253
    reporters: ['coverage-istanbul'],
254
    
255
    coverageIstanbulReporter: {
256
      reports: ['html', 'lcovonly', 'text-summary'],
257
      dir: 'coverage/%browser%',
258
      combineBrowserReports: false,
259
      fixWebpackSourcePaths: true,
260
      skipFilesWithNoCoverage: true,
261
      verbose: true,
262
      
263
      thresholds: {
264
        emitWarning: false,
265
        global: {
266
          statements: 90,
267
          lines: 90,
268
          branches: 85,
269
          functions: 90
270
        },
271
        each: {
272
          statements: 85,
273
          lines: 85,
274
          branches: 80,
275
          functions: 85,
276
          overrides: {
277
            'src/utils/**/*.js': {
278
              statements: 75
279
            }
280
          }
281
        }
282
      },
283
      
284
      'report-config': {
285
        html: {
286
          subdir: 'html-report'
287
        }
288
      }
289
    }
290
  });
291
};
292
```
293

294
### Webpack Integration
295

296
```javascript
297
// karma.conf.js for webpack projects
298
module.exports = function(config) {
299
  config.set({
300
    reporters: ['coverage-istanbul'],
301
    
302
    // Webpack preprocessing with istanbul loader
303
    preprocessors: {
304
      'src/**/*.js': ['webpack', 'sourcemap']
305
    },
306
    
307
    webpack: {
308
      module: {
309
        rules: [
310
          {
311
            test: /\.js$/,
312
            exclude: /node_modules/,
313
            loader: 'coverage-istanbul-loader',
314
            enforce: 'post'
315
          }
316
        ]
317
      }
318
    },
319
    
320
    coverageIstanbulReporter: {
321
      fixWebpackSourcePaths: true,
322
      reports: ['html', 'lcovonly'],
323
      dir: 'coverage/'
324
    }
325
  });
326
};
327
```