0
# Istanbul
1

2
Istanbul is a comprehensive JavaScript code coverage tool that computes statement, line, function and branch coverage with module loader hooks to transparently add coverage when running tests. It supports all JS coverage use cases including unit tests, server side functional tests and browser tests, built for scale.
3

4
## Package Information
5

6
- **Package Name**: istanbul
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install istanbul`
10

11
## Core Imports
12

13
```javascript
14
const istanbul = require('istanbul');
15
const { Instrumenter, Collector, Reporter } = require('istanbul');
16
```
17

18
For ES modules (if supported by your environment):
19

20
```javascript
21
import istanbul from 'istanbul';
22
import { Instrumenter, Collector, Reporter } from 'istanbul';
23
```
24

25
## Basic Usage
26

27
```javascript
28
const fs = require('fs');
29
const istanbul = require('istanbul');
30

31
// Create instrumenter
32
const instrumenter = new istanbul.Instrumenter();
33

34
// Instrument some code
35
const code = fs.readFileSync('myScript.js', 'utf8');
36
const instrumentedCode = instrumenter.instrumentSync(code, 'myScript.js');
37

38
// Run the instrumented code (this will populate global.__coverage__)
39
eval(instrumentedCode);
40

41
// Collect coverage data
42
const collector = new istanbul.Collector();
43
collector.add(global.__coverage__);
44

45
// Generate reports
46
const reporter = new istanbul.Reporter();
47
reporter.addAll(['text', 'lcov', 'html']);
48
reporter.write(collector, true, () => {
49
    console.log('Coverage reports generated!');
50
});
51
```
52

53
## Architecture
54

55
Istanbul is built around several key components:
56

57
- **Instrumenter**: Transforms JavaScript code to track execution coverage
58
- **Collector**: Merges coverage data from multiple test runs and sources
59
- **Reporter**: Generates coverage reports in various formats (HTML, LCOV, text, etc.)
60
- **Hook System**: Intercepts module loading to instrument code at runtime
61
- **Store System**: Pluggable storage backends for coverage data
62
- **CLI Tools**: Command-line interface for common coverage workflows
63

64
## Capabilities
65

66
### Code Instrumentation
67

68
Transform JavaScript code to track statement, line, function, and branch coverage during execution.
69

70
```javascript { .api }
71
class Instrumenter {
72
    constructor(options?: InstrumentOptions);
73
    instrumentSync(code: string, filename: string): string;
74
    instrument(code: string, filename: string, callback: (err: Error, code: string) => void): void;
75
    lastFileCoverage(): Object;
76
}
77

78
interface InstrumentOptions {
79
    coverageVariable?: string;
80
    embedSource?: boolean;
81
    preserveComments?: boolean;
82
    noCompact?: boolean;
83
    esModules?: boolean;
84
    noAutoWrap?: boolean;
85
    codeGenerationOptions?: Object;
86
    debug?: boolean;
87
    walkDebug?: boolean;
88
}
89
```
90

91
[Code Instrumentation](./instrumentation.md)
92

93
### Coverage Collection
94

95
Merge and process coverage data from multiple sources and test runs.
96

97
```javascript { .api }
98
class Collector {
99
    constructor(options?: CollectorOptions);
100
    add(coverage: Object, testName?: string): void;
101
    files(): string[];
102
    fileCoverageFor(fileName: string): Object;
103
    getFinalCoverage(): Object;
104
    dispose(): void;
105
}
106

107
interface CollectorOptions {
108
    store?: Store;
109
}
110
```
111

112
[Coverage Collection](./collection.md)
113

114
### Report Generation
115

116
Generate coverage reports in various formats including HTML, LCOV, text, and JSON.
117

118
```javascript { .api }
119
class Reporter {
120
    constructor(cfg?: Configuration, dir?: string);
121
    add(fmt: string): void;
122
    addAll(fmts: string[]): void;
123
    write(collector: Collector, sync: boolean, callback?: () => void): void;
124
}
125

126
class Report {
127
    static create(type: string, opts?: Object): Report;
128
    static getReportList(): string[];
129
    writeReport(collector: Collector, sync?: boolean): void;
130
}
131
```
132

133
[Report Generation](./reporting.md)
134

135
### Runtime Hooks
136

137
Hook into Node.js module loading system to instrument code transparently at runtime.
138

139
```javascript { .api }
140
const hook = {
141
    hookRequire(matcher: Function, transformer: Function, options?: Object): void;
142
    unhookRequire(): void;
143
    hookCreateScript(matcher: Function, transformer: Function, opts?: Object): void;
144
    unhookCreateScript(): void;
145
    hookRunInThisContext(matcher: Function, transformer: Function, opts?: Object): void;
146
    unhookRunInThisContext(): void;
147
    unloadRequireCache(matcher: Function): void;
148
};
149
```
150

151
[Runtime Hooks](./hooks.md)
152

153
### Configuration Management
154

155
Load and manage Istanbul configuration from files or objects with validation and defaults.
156

157
```javascript { .api }
158
const config = {
159
    loadFile(file: string, overrides?: Object): Configuration;
160
    loadObject(obj: Object, overrides?: Object): Configuration;
161
    defaultConfig(): Object;
162
};
163

164
class Configuration {
165
    constructor(obj: Object, overrides?: Object);
166
    instrumentation: InstrumentationOptions;
167
    reporting: ReportingOptions;
168
    hooks: HookOptions;
169
}
170
```
171

172
[Configuration Management](./configuration.md)
173

174
### Storage System
175

176
Pluggable storage backends for coverage data with memory, filesystem, and temporary storage options.
177

178
```javascript { .api }
179
class Store {
180
    static create(type: string, opts?: Object): Store;
181
    static register(constructor: Function): void;
182
    set(key: string, contents: string): void;
183
    get(key: string): string;
184
    keys(): string[];
185
    hasKey(key: string): boolean;
186
    dispose(): void;
187
    getObject(key: string): Object;
188
    setObject(key: string, object: Object): void;
189
}
190
```
191

192
[Storage System](./storage.md)
193

194
### Coverage Utilities
195

196
Process and manipulate coverage objects including merging, summarization, and format conversion.
197

198
```javascript { .api }
199
const utils = {
200
    addDerivedInfo(coverage: Object): void;
201
    addDerivedInfoForFile(fileCoverage: Object): void;
202
    removeDerivedInfo(coverage: Object): void;
203
    blankSummary(): Object;
204
    summarizeFileCoverage(fileCoverage: Object): Object;
205
    summarizeCoverage(coverage: Object): Object;
206
    mergeFileCoverage(first: Object, second: Object): Object;
207
    mergeSummaryObjects(...summaries: Object[]): Object;
208
};
209
```
210

211
[Coverage Utilities](./utilities.md)
212

213
### Tree Summarization
214

215
Generate hierarchical coverage summaries organized by directory structure for comprehensive coverage analysis and HTML report generation.
216

217
```javascript { .api }
218
class TreeSummarizer {
219
    constructor();
220
    addFileCoverageSummary(filePath: string, metrics: Object): void;
221
    getTreeSummary(): TreeSummary;
222
}
223

224
interface TreeSummary {
225
    prefix: string[];
226
    root: Node;
227
    getNode(shortName: string): Node;
228
    toJSON(): Object;
229
}
230

231
interface Node {
232
    name: string;
233
    relativeName: string;
234
    fullName: string;
235
    kind: 'file' | 'dir';
236
    metrics: Object | null;
237
    packageMetrics: Object | null;
238
    parent: Node | null;
239
    children: Node[];
240
    displayShortName(): string;
241
    addChild(child: Node): void;
242
    toJSON(): Object;
243
}
244
```
245

246
[Tree Summarization](./tree-summarizer.md)
247

248
### Command Line Interface
249

250
Complete command-line tools for instrumenting code, running tests with coverage, and generating reports.
251

252
Available commands:
253
- `istanbul cover` - Run commands with coverage
254
- `istanbul instrument` - Instrument JavaScript files
255
- `istanbul report` - Generate reports from coverage data  
256
- `istanbul check-coverage` - Validate coverage thresholds
257
- `istanbul test` - Run tests with coverage
258
- `istanbul help` - Show command help
259

260
[Command Line Interface](./cli.md)
261

262
## Global Exports
263

264
```javascript { .api }
265
// Main module exports
266
const istanbul = {
267
    Instrumenter: Instrumenter,
268
    Store: Store,
269
    Collector: Collector,
270
    hook: hook,
271
    Report: Report,
272
    config: config,
273
    Reporter: Reporter,
274
    utils: utils,
275
    matcherFor: Function,
276
    VERSION: string,
277
    Writer: Writer,
278
    ContentWriter: ContentWriter,
279
    FileWriter: FileWriter,
280
    TreeSummarizer: TreeSummarizer,
281
    assetsDir: string,
282
    _yuiLoadHook: Object  // Internal YUI loading support (undocumented)
283
};
284
```