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
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.
SourceMap Support
c8 can handle source-maps, for remapping coverage from generated code to original source files (useful for TypeScript, JSX, etc).
Source map files versus inline source maps
Just-in-time instrumented codebases will often insert source maps inline with the .js code they generate at runtime (e.g, @babel/register can be configured to insert a source map footer).
Pre-instrumented codebases, e.g., running tsc to generate .js in a build folder, may generate either inline source maps, or a separate .map file stored on disk.
c8 can handle loading both types of source maps.
Exclude after remap
Depending on the size and configuration of your project, it may be preferable to apply exclusion logic either before or after source-maps are used to remap compiled to original source files.
--exclude-after-remap is used to control this behaviour.
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:
The --100 flag can be set for the check-coverage as well:
c8 check-coverage --100
Using Monocart coverage reports (experimental)
Monocart is an alternate library for outputting v8 code coverage data as Istanbul reports.
Monocart also provides reporters based directly on v8's byte-offset-based output. Such as, console-details and v8. This removes a complex transformation step and may be less bug prone for some environments.
NOTE: Monocart requires additional monocart-coverage-reports to be installed:
npm i monocart-coverage-reports@2 --save-dev
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: