UNPKG

3.22 kBMarkdownView Raw
1# c8 - native V8 code-coverage
2
3![ci](https://github.com/bcoe/c8/workflows/ci/badge.svg)
4![nycrc config on GitHub](https://img.shields.io/nycrc/bcoe/c8)
5[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
6
7Code-coverage using [Node.js' built in functionality](https://nodejs.org/dist/latest-v10.x/docs/api/cli.html#cli_node_v8_coverage_dir)
8that's compatible with [Istanbul's reporters](https://istanbul.js.org/docs/advanced/alternative-reporters/).
9
10Like [nyc](https://github.com/istanbuljs/nyc), c8 just magically works:
11
12```bash
13npm i c8 -g
14c8 node foo.js
15```
16
17The above example will output coverage metrics for `foo.js`.
18
19## Checking for "full" source coverage using `--all`
20
21By default v8 will only give us coverage for files that were loaded by the engine. If there are source files in your
22project that are flexed in production but not in your tests, your coverage numbers will not reflect this. For example,
23if your project's `main.js` loads `a.js` and `b.js` but your unit tests only load `a.js` your total coverage
24could show as `100%` for `a.js` when in fact both `main.js` and `b.js` are uncovered.
25
26By supplying `--all` to c8, all files in `cwd` that pass the `--include` and `--exclude` flag checks, will be loaded into the
27report. If any of those files remain uncovered they will be factored into the report with a default of 0% coverage.
28
29## c8 report
30
31run `c8 report` to regenerate reports after `c8` has already been run.
32
33## Checking coverage
34
35c8 can fail tests if coverage falls below a threshold.
36After running your tests with c8, simply run:
37
38```shell
39c8 check-coverage --lines 95 --functions 95 --branches 95
40```
41
42c8 also accepts a `--check-coverage` shorthand, which can be used to
43both run tests and check that coverage falls within the threshold provided:
44
45```shell
46c8 --check-coverage --lines 100 npm test
47```
48
49The above check fails if coverage falls below 100%.
50
51To check thresholds on a per-file basis run:
52
53```shell
54c8 check-coverage --lines 95 --per-file
55```
56
57## Ignoring Uncovered Lines, Functions, and Blocks
58
59Sometimes you might find yourself wanting to ignore uncovered portions of your
60codebase. For example, perhaps you run your tests on Linux, but
61there's some logic that only executes on Windows.
62
63To ignore lines, blocks, and functions, use the special comment:
64
65`/* c8 ignore next */`.
66
67### Ignoring the next line
68
69```js
70const myVariable = 99
71/* c8 ignore next */
72if (process.platform === 'win32') console.info('hello world')
73```
74
75### Ignoring the next N lines
76
77```js
78const myVariable = 99
79/* c8 ignore next 3 */
80if (process.platform === 'win32') {
81 console.info('hello world')
82}
83```
84
85### Ignoring all lines until told
86
87```js
88/* c8 ignore start */
89function dontMindMe() {
90 // ...
91}
92/* c8 ignore stop */
93```
94
95### Ignoring a block on the current line
96
97```js
98const myVariable = 99
99const os = process.platform === 'darwin' ? 'OSXy' /* c8 ignore next */ : 'Windowsy'
100```
101
102## Supported Node.js Versions
103
104c8 uses
105[native V8 coverage](https://github.com/nodejs/node/pull/22527),
106make sure you're running Node.js `>= 10.12.0`.
107
108## Contributing to `c8`
109
110See the [contributing guide here](./CONTRIBUTING.md).