-
Notifications
You must be signed in to change notification settings - Fork 16
/
istanbul.node_cli.txt
517 lines (400 loc) · 29.8 KB
/
istanbul.node_cli.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
ISTANBUL
ALTERNATIVES ==> # - istanbul (prefered): high-profile
# - blanket.js: not maintained
# - v8 and NODE_V8_COVERAGE (see its doc):
# - directly integrated, i.e. faster
# - only instrumentation + source maps
# - to do reporting, checks, must convert to istanbul
# - source maps support not great
# - still a little buggy
# - Node >=10.12
NYC ==> #17.0.0
ISTANBUL-API ==> #2.1.7
NYC VS ISTANBUL-API ==> #NYC is CLI, ISTANBUL-API is programmatic usage.
#They both use same core libraries, however NYC does not use ISTANBUL-API directly
SUMMARY ==> # - instrument JavaScript code to count lines|statements|functions|branches[True] coverage
# - do it by adding VAR++ statements before each line (by parsing JavaScript with @babel/parser)
# - also monkey patches require() to automatically instrument
# - can both read and write source maps
# - report coverage using different formats (including LCOV, console, HTML)
# - can check coverage against specific thresholds
/=+===============================+=\
/ : : \
)==: RUN :==(
\ :_______________________________: /
\=+===============================+=/
nyc ... #nyc have a default command documented like this
#I.e. nyc ... (default command) is different from nyc [MANY_COMMANDS] ... (all commands)
nyc [MANY_COMMANDS] ... #
--include|n 'GLOB' #Whitelists files
#Def: files that are run (for nyc ...) or everything in --cwd (for other nyc commands)
#Can use '!GLOB'
#Can be done several times
#Based on monopackage "test-exclude" (which uses micromatch)
--exclude|x 'GLOB' #Same but for blacklisting
#Def: 'coverage|__tests__|test[s]/**/*.{js,cjs,mjs,ts}', '[*-]test[-*].{js,cjs,mjs,ts}' and 'ava|babel|jest|nyc|rollup|webpack.config.js'
#Can be done several times
--exclude-node-modules #Always exclude 'node_modules/**' (def: true)
--exclude-after-remap #If true (def), apply --exclude after applying source maps as well
--extension|e '.EXT' #Def: ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx']
#Can be done several times
--cwd DIR #Used for several purposes
#Def: ENV_VAR NYC_CWD, package root, or process.cwd()
--require|i 'PATH|MODULE' #Do require('PATH|MODULE') first
#Can be done several times
/=+===============================+=\
/ : : \
)==: CONFIG :==(
\ :_______________________________: /
\=+===============================+=/
NYC_CONF #Can be:
# - package.json "nyc" NYC_CONF
# - --nycrc-path JSON_NYC_CONF_FILE
# - [.../]./.nycrc[.json] JSON_NYC_CONF_FILE
# - [.../]./.nycrc.y[a]ml YAML_NYC_CONF_FILE
# - [.../]./.nycrc.config.js JS_NYC_CONF_FILE
#Should be like CLI flags but camelCase
NYC_CONFIG NYC_CONF #ENVVAR set by nyc ...
NYC_CONF.extends #'PACKAGE', to merge another NYC_CONF2
nyc-config-typescript #Package of example NYC_CONF for TypeScript
nyc-config-babel #Package of example NYC_CONF with @babel/register
API_CONF_OBJ #Plain object
API_CONF #CLASS
API_CONF.PROP()->VAL #Gets API_CONF_OBJ.PROP (camelCase instead of dasherized)
ISTANBUL-API.config.loadObject
([API_CONF_OBJ], [API_CONF_OBJ2])
->API_CONF #API_CONF_OBJ has less priority than default conf, API_CONF_OBJ2 has more
ISTANBUL-API.config.loadFile
(['API_CONFFILE'],[API_CONFOBJ2])
->API_CONF #Same with a YAML|JSON FILE (def: './.istanbul.yml')
API_CONF.verbose #BOOL. Add debug console.log()
/=+===============================+=\
/ : : \
)==: CACHING/TEMP :==(
\ :_______________________________: /
\=+===============================+=/
nyc [MANY_COMMANDS] ... #
--temp-dir DIR #Def: './.nyc_output'
--cache|c #Caches instrumentation to cache directory
#Def: true
--cache-dir #Def: uses FIND-CACHE-DIR (see its doc)
--babel-cache #Sets ENVVAR BABEL_DISABLE_CACHE '1'
#Def: false
nyc ... #Creates temp directory and cache directory
--clean #First removes temp directory
/=+===============================+=\
/ : : \
)==: GENERIC :==(
\ :_______________________________: /
\=+===============================+=/
nyc [OPTS] ... #Do:
# - instrument through hooks like COVER_OBJ.hookFn()
# - run ...
# - nyc check-coverage (if --check-coverage)
# - nyc report
#Can use same options as nyc instrument|report, plus some extra
--all|a #Like API_CONF.includeAllSources
--eager #Delay initialization code until instrumentation (useless performance optimization)
--hook-run-in-[this]-context #Def: false
ISTANBUL-API.instrument.cover
(API_CONF[, 'GLOB'_ARR], #Retrieves COVER_OBJ, used to instrument through hooks then reports (see below)
FUNC(ERROR, COVER_OBJ)) #Targets 'GLOB'_ARR (def: '**/*.js')
API_CONF.instrumentation.root #Def: '.'
API_CONF.excludes #Def: []
#Also excludes ['**/node_modules|test|tests/**'] if API_CONF.defaultExcludes true (def)
#Also excludes API_CONF.reporting.dir 'DIR' (def: './coverage')
API_CONF.includeAllSources #Also targets files that are never run
COVER_OBJ.hookFn() #Monkey patches require() (using deprecated require.extensions) so that it instruments code
COVER_OBJ.unhookFn() #Removes it and remove require()'s cache
API_CONF.hooks.
hookRunIn[This]Context #Also monkey patches VM.runIn[This]Context()
CHILD_PROCESS.spawn[Sync] ==> #Is monkey patched by node-preload library, used by nyc
--use-spawn-wrap=true #Use spawn-wrap library instead of node-preload
COVER_OBJ.coverageFinderFn()
->COVMAP #Gets current COVMAP (from global variable tracking it)
COVER_OBJ.exitFn() #Writes current COVMAP to 'DIR/coverage[-PID].raw-json'
# - DIR is API_CONF.reporting.dir
# - PID if API_CONF.instrumentation.includePid true (def: false)
#Then reports it like ISTANBUL-API.reports.run() using 'FORMAT's:
# - 'lcov'
# - 'text' and|or 'text-summary' according to API_CONF.reporting.print 'detail|summary|none|both' (def: 'summary')
ISTANBUL-LIB-HOOK ==> #3.0.0
#Underlying require() monkey-patching logic. Not documented here because too low-level
/=+===============================+=\
/ : : \
)==: INSTRUMENTATION :==(
\ :_______________________________: /
\=+===============================+=/
// istanbul ignore file [COMMENT] #Skip instrumentation for current file
// istanbul ignore next [COMMENT] #Skip instrumentation for next block|structure
// istanbul ignore if|else [COMT] #Skip instrumentation for next if|else
API_CONF.instrumentation.
ignoreClassMethods #Skip instrumentation for 'FUNC'_ARR
nyc instrument [OPTS] 'FILE|DIR' #Like ISTANBUL-API.instrument.run() except:
['FILE2|DIR2'] # - def API_CONF.instrumentatin.preseveComments true
--instrument #If false, do not instrument
--es-modules #Def: true
--compact #
--preserve-comments #
--exit-on-error #process.exit(1) if instrumentation throws
--delete #Delete 'FILE2|DIR2' at the end.
--complete-copy #Copy source files to output as well.
--in-place #Modify input files directly
ISTANBUL-API.instrument.run #Instrument OPTS.input 'PATH|DIR' and writes result to OPTS.output 'PATH2|DIR2' (def: stdout)
(API_CONF, OPTS, FUNC()) #In a nutshell, for each file:
# - set a global FILECOV recording source code's line|column|name information
# - add FILECOV.s|f|b.CID++ before each statement|function|branch
OPTS.includes 'GLOB'[_ARR] #Def ['**/*'] if API_CONF.completeCopy true (def: false)
#Otherwise [**/*.EXT] using API_CONF.extensions '.EXT'_ARR (def: ['.js'])
API_CONF|OPTS.excludes 'GLOB'[ARR]#Def: []
#Also excludes ['**/node_modules/**'] if API_CONF.defaultExcludes true (def)
OPTS.saveBaseline #If true (def: false), saves a COVEMAP with empty counters to OPTS.baselineFile
#(def: './coverage/coverage-baseline.raw.json')
API_CONF.instrumentation.esModules#Make @babel/parser parse with sourceType 'script' (false) or 'module' (true, def)
API_CONF.instrumentation.autoWrap #Make @babel/parser parse with allowReturnOutsideFunction (def: true)
API_CONF.instrumentation.compact #Make @babel/generator minify whitespaces with compact BOOL (def: true)
API_CONF.instrumentation.
preserveComments #Make @babel/generator keep comments BOOL (def: true)
API_CONF.instrumentation.
parserPlugins
NYC_CONF.parserPlugins #Babel plugins (def: ['asyncGenerators', 'dynamicImport', 'objectRestSpread', 'optionalCatchBinding'])
INSTRUMENTATION LOGIC ==> #For each file:
# - prepends code that create a new FILECOV:
# - referenced by global.__coverage__ COVMAP
# - all FILECOV.statement|fn|branchMap.CID are set to their related source code's line|column|name
# - all FILECOV.s|f|b.CID are initialized to 0
# - adds counters:
# - FILECOV.s.CID++ before each statement
# - FILECOV.f.CID++ before each function
# - FILECOV.b.CID[INDEX]++ before each child branch
# - all this is compile-time, but counters will be hit|incremented runtime
#Do it by:
# - parsing JavaScript 'CODE' to AST (with @babel/parser with several plugins, see its doc)
# - traversing and transforming AST (with @babel/traverse, see its doc)
# - generating JavaScript 'CODE' from AST (with @babel/generator, see its doc)
ISTANBUL-LIB-INSTRUMENT ==> #6.0.2
#Underlying logic. Not documented here because too low-level
/=+===============================+=\
/ : : \
)==: BABEL-PLUGIN-ISTANBUL :==(
\ :_______________________________: /
\=+===============================+=/
VERSION ==> #6.1.1
#Babel plugin that instrument code
#There is a related Babel configuration available also at monopackage "nyc-config-babel" (3.0.0)
PLUGIN_OPTS.include|exclude
'GLOB'[_ARR] #Same as API_CONF.include|exclude
PLUGIN_OPTS.excludeNodeModules #Same as --exclude-node-modules
PLUGIN_OPTS.useInlineSourceMaps #BOOL (def: true)
PLUGIN_OPTS.onCover
(FUNC('PATH', FILECOV)) #Optional event handler
/=+===============================+=\
/ : : \
)==: SOURCE MAPS :==(
\ :_______________________________: /
\=+===============================+=/
nyc instrument ...
--source-map #If true (def), take into account existing source maps (using CONVERT-SOURCE-MAP, see its doc)
--produce-source-map #If true (def: false), creates source maps during instrumentation (as base64 sourceMappingURL)
#If some files already contained a base64|external sourceMappingURL, does source map multi-mapping.
#Uses mozilla source-map's (see its doc)
nyc [COMMAND] ... #Other commands automatically handle source maps
API_CONF.instrumentation.
produceSourceMap #BOOL (def: true)
ISTANBUL-LIB-SOURCE-MAPS ==> #5.0.4
#Underlying logic. Not documented here because too low-level
REMAP-ISTANBUL ==> ##Apply source map on a COVMAP. Should not be needed
/=+===============================+=\
/ : : \
)==: CHECK :==(
\ :_______________________________: /
\=+===============================+=/
nyc ...
--check-coverage #Run nyc check-coverage ... before reporting
nyc check-coverage #Same as ISTANBUL-API.checkCoverage() but CLI and:
# - if under thresholds, prints it and exit code 1
# - uses COVMAPs from --temp-dir
# - def --lines is 90 (0 for others)
--statements|lines|functions|
branches[True] #
--per-file #
ISTANBUL-API.checkCoverage
(API_CONF[,OPTS], #Check coverage of combined COVMAPs against API_CONF.check.global.*
FUNC(ERROR|'ERROR')) #If under thresholds, ERROR|'ERROR'
#Uses COVMAPs from:
# - OPTS.includes (def: '**/coverage*.json')
# - at OPTS.root (def: API_CONF.instrumentation.root (def: '.'))
API_CONF.check.global.statements|
lines|functions|branches[True] #0-100. Def: 0
API_CONF.check.each.* #Like API_CONF.check.global.* but for each file's FILECOV instead of combined COVMAPs
API_CONF.check.excludes #'PATH'_ARR
/=+===============================+=\
/ : : \
)==: REPORTING :==(
\ :_______________________________: /
\=+===============================+=/
nyc ... #Runs nyc report ... at end
--silent|s #Do not run nyc-report
nyc report #Same as ISTANBUL-API.reports.run() except gets all COVMAPs from --temp-dir
--reporter|r 'FORMAT' #Def: 'text'
--report-dir 'DIR' #Def: 'coverage'
--skip-empty #FORMAT's OPTS.skipEmpty (def: false)
--skip-full #FORMAT's OPTS.skipFull (def: false)
--show-process-tree #Show all Node.js spawn during reporting
--watermarks.statements|lines|
functions|branches[True] #
ISTANBUL-API.reports.run #Gets all COVMAPs from OPTS:
('FORMAT'_ARR, API_CONF[, OPTS], # - root 'DIR' (def: process.cwd())
FUNC()) # - includes (def: '**/coverage*.raw.json')
# - excludes ['**/node_modules/**']
#For each COVMAP, report it with ISTANBUL-API.createReporter()
ISTANBUL-API.createReporter
(API_CONF[, OPTS])->REPORTER #
REPORTER.addAll('FORMAT'_ARR)
REPORTER.add('FORMAT') #Specify 'FORMAT'
REPORTER.write(COVMAP, OPTS) #Report a COVMAP with each 'FORMAT'
#OPTS is API_CONF.reporting.report-config
API_CONF.reporting.reports #'FORMAT'_ARR
API_CONF.reporting.dir #Output dir (def: './coverage')
API_CONF|OPTS.summarizer #How files organization is reported:
# - 'flat': no nesting
# - 'nested': nested according to directory structure
# - 'pkg' (def):
# - same except directories are not nested inside each other
# - instead they are all siblings, i.e. depth level is 2
API_CONF.reporting.watermarks.
statements|lines|functions|
branches[True] #[NUM, NUM2] for green|orange|red color (def: [50, 80])
API_CONF.reporting.report-config #FORMAT's OPTS
#All FORMATs have OPTS:
# - file 'FILENAME'
# - '-'|null for process.stdout
# - def is different for each FORMAT
ISTANBUL-REPORTS ==> #3.1.7
#Reporters (based on ISTANBUL-LIB-REPORT)
#Not documented here because too low level
ISTANBUL-LIB-REPORT ==> #3.0.1
#Base helpers for reporters:
# - FILEWRITER: writing to file|console, raw or XML
# - summarizers|TREE: organizing and visiting FILECOVs as a tree
# - few utilities (e.g. watermarks)
#Not documented here because too low level
/=+===============================+=\
/ : : \
)==: FORMATS :==(
\ :_______________________________: /
\=+===============================+=/
FORMAT 'none' #Nothing|silent
FORMAT 'json' #Like { 'PATH': FILECONV, ... } as JSON string
#Def 'FILENAME': 'coverage-final.json'
FORMAT 'json-summary' #{ 'PATH': SUMMARY, ..., total: SUMMARY } as JSON string
#Def 'FILENAME': 'coverage-summary.json'
FORMAT 'text' #ASCII table with:
# - 'FILE' as lines
# - columns: SUMMARY.lines|statements|functions|branches[True].pct NUM, FILECOV.getUncoveredFiles()
#Def 'FILENAME': null
#OPTS:
# - maxCols NUM (def: 0)
# - skipEmpty BOOL (def: false): skip empty files
# - skipFull BOOL (def: false): skip files with full coverage
FORMAT 'text-summary' #SUMMARY.lines|statements|functions|branches[True].pct NUM for all files
#Def 'FILENAME': null
FORMAT 'html' #Similar to 'text' but as HTML
#OPTS:
# - subdir 'DIR': output sub-'DIR'
# - skipEmpty BOOL (def: false): skip empty files
# - linkMapper OBJ: customize URLs by mapping them
# - verbose BOOL (def: false): debugging console.log()
# - metricsToShow STR_ARR (def: ['lines', 'branches[True]', 'functions'])
FORMAT 'lcovonly' #LCOV (see its doc)
#Def 'FILENAME': 'lconv.info'
FORMAT 'lcov' #lcovonly + html
FORMAT 'text-lcov' #Like lcovonly file OPTS.file '-'
FORMAT 'teamcity' #Teamcity's format
#Def 'FILENAME': null
#OPTS: blockName STR (def: 'Code Coverage Summary')
FORMAT 'clover' #Atlassian clover's format
#Def 'FILENAME': 'clover.xml'
#OPTS: projectRoot 'DIR' (def: process.cwd())
FORMAT 'cobertura' #Cobertura's format
#Def 'FILENAME': 'cobertura-coverage.xml'
#OPTS: projectRoot 'DIR' (def: process.cwd())
/=+===============================+=\
/ : : \
)==: DATA :==(
\ :_______________________________: /
\=+===============================+=/
nyc merge [DIR] [FILE] #Get all COVMAPs from DIR (def: '.nyc_output') and merge them to FILE (def: 'coverage.json')
COVMAP #{ 'PATH': FILECOV, ... }
FILECOV #Detailed single file coverage information
#OBJ:
# - path 'PATH'
# (number of times statement|function|branch was executed)
# - s.CID NUM
# - f.CID NUM
# - b.CID NUM_ARR (each child branch)
# (line|column information and metadata)
# - statementMap.CID:
# - start|end.line|column NUM
# - fnMap.CID:
# - loc.start|end.line|column NUM: of the FUNC body
# - decl.start|end.line|column NUM: of the 'FUNC' name
# - name 'FUNC'
# - branchMap.CID:
# - loc.start|end.line|column NUM (the parent branch)
# - locations OBJ_ARR: start|end.line|column NUM (each child branch)
# - type 'if|switch|cond-expr|binary-expr|default-arg': type of node
# (IfStatement|SwitchStatement|ConditionalExpression|LogicalExpression|AssignmentPattern)
#CID:
# - same statement|function|branch uses same CID between the counter and the *Map
# - incrementing 'NUM' for statement|function|branch
SUMMARY #Summarized single|multiple file[s] coverage information.
#OBJ:
# - lines|statements|functions|branches[True]:
# - total NUM: executed or not
# - covered NUM: executed
# - skipped NUM: when using /* istanbul ignore */
# - pct NUM|'Unknown':
# - covered / total
# - 0-100 with 2 decimal digits precision
# - 100 if total 0
ISTANBUL-LIB-COVERAGE ==> #Underlying data model for file coverage information. Not documented here because too low-level
#3.2.2
/=+===============================+=\
/ : : \
)==: JEST :==(
\ :_______________________________: /
\=+===============================+=/
JEST ==> #Instruments using babel-istanbul-plugin (as part of babel-jest) and ISTANBUL-LIB-INSTRUMENT
--coverage
CONF.collectCoverage #BOOL (def: false): whether coverage is enabled
--collectCoverageFrom
CONF.collectCoverage[Only]From #[Only] includes 'GLOB'_ARR (def: run files)
CONF.forceCoverageMatch #Includes 'GLOB'_ARR even if not run
CONF.coveragePathIgnorePatterns #Excludes 'GLOB'_ARR (def: ['node_modules/**'])
CONF.coverageDirectory #'DIR' (def: 'coverage')
CONF.coverageReporters #ARR of 'FORMAT' (def: ['json', 'text', 'lcov', 'clover']) or ['FORMAT', OPTS]
CONF.coverageThreshold #API_CONF.check OBJ (make tests fail if under threshold)
/=+===============================+=\
/ : : \
)==: NODE-TAP :==(
\ :_______________________________: /
\=+===============================+=/
NODE-TAP ==> #Part of node-tap (see its doc)
--[no-]cov[erage] #Uses nyc ...
#Def: on
--[no-]coverage-report=FORMAT #Def: 'text'
--no-browser #Unless set, --coverage-report=html will open browser afterwards
--nyc-arg=ARG #Pass CLI argument to nyc ...
#Can be done several times
--check-coverage
--show-process-tree
--branches[True]|functions|lines|
statements NUM #Specific nyc arguments
--100 #Same as --branches[True]|functions|lines|statements 100
--[no-]coverage-map FILE #FILE that exports FUNC('FILE2')->'FILE3'[_ARR]|false
#Decides which files to cover.
#FUNC() is fired for any required 'FILE2'
#'FILE3' are files to cover.