c8 - native V8 code-coverage
Code-coverage using Node.js' built in functionality that's compatible with Istanbul's reporters.
Like nyc, c8 just magically works:
npm i c8 -g
c8 node foo.js
The above example will output coverage metrics for foo.js
.
CLI Options / Configuration
c8 can be configured via command-line flags, a c8
section in package.json
, or a JSON configuration file on disk.
A configuration file can be specified by passing its path on the command line with --config
or -c
. If no config option is provided, c8 searches for files named .c8rc
, .c8rc.json
, .nycrc
, or .nycrc.json
, starting from
cwd
and walking up the filesystem tree.
When using package.json
configuration or a dedicated configuration file, omit the --
prefix from the long-form of the desired command-line option.
Here is a list of common options. Run c8 --help
for the full list and documentation.
Option | Description | Type | Default |
---|---|---|---|
-c , --config |
path to JSON configuration file | string |
See above |
-r , --reporter |
coverage reporter(s) to use | Array<string> |
['text'] |
-o , --reports-dir , --report-dir |
directory where coverage reports will be output to | string |
./coverage |
--all |
see section below for more info | boolean |
false |
--src |
see section below for more info | Array<string> |
[process.cwd()] |
-n , --include |
see section below for more info | Array<string> |
[] (include all files) |
-x , --exclude |
see section below for more info | Array<string> |
list |
--skip-full |
do not show files with 100% statement, branch, and function coverage | boolean |
false |
--check-coverage |
check whether coverage is within thresholds provided | boolean |
false |
--temp-directory |
directory V8 coverage data is written to and read from | string |
process.env.NODE_V8_COVERAGE |
--clean |
should temp files be deleted before script execution | boolean |
true |
--all
Checking for "full" source coverage using By default v8 will only give us coverage for files that were loaded by the engine. If there are source files in your
project that are flexed in production but not in your tests, your coverage numbers will not reflect this. For example,
if your project's main.js
loads a.js
and b.js
but your unit tests only load a.js
your total coverage
could show as 100%
for a.js
when in fact both main.js
and b.js
are uncovered.
By supplying --all
to c8, all files in directories specified with --src
(defaults to cwd
) that pass the --include
and --exclude
flag checks, will be loaded into the report. If any of those files remain uncovered they will be factored
into the report with a default of 0% coverage.
c8 report
run c8 report
to regenerate reports after c8
has already been run.
Checking coverage
c8 can fail tests if coverage falls below a threshold. After running your tests with c8, simply run:
c8 check-coverage --lines 95 --functions 95 --branches 95
c8 also accepts a --check-coverage
shorthand, which can be used to
both run tests and check that coverage falls within the threshold provided:
c8 --check-coverage --lines 100 npm test
The above check fails if coverage falls below 100%.
To check thresholds on a per-file basis run:
c8 check-coverage --lines 95 --per-file
Ignoring Uncovered Lines, Functions, and Blocks
Sometimes you might find yourself wanting to ignore uncovered portions of your codebase. For example, perhaps you run your tests on Linux, but there's some logic that only executes on Windows.
To ignore lines, blocks, and functions, use the special comment:
/* c8 ignore next */
.
Ignoring the next line
const myVariable = 99
/* c8 ignore next */
if (process.platform === 'win32') console.info('hello world')
Ignoring the next N lines
const myVariable = 99
/* c8 ignore next 3 */
if (process.platform === 'win32') {
console.info('hello world')
}
Ignoring all lines until told
/* c8 ignore start */
function dontMindMe() {
// ...
}
/* c8 ignore stop */
Ignoring a block on the current line
const myVariable = 99
const os = process.platform === 'darwin' ? 'OSXy' /* c8 ignore next */ : 'Windowsy'
Supported Node.js Versions
c8 uses
native V8 coverage,
make sure you're running Node.js >= 10.12.0
.
c8
Contributing to See the contributing guide here.