1 | # c8 - native V8 code-coverage
|
2 |
|
3 | [![ci](https://github.com/bcoe/c8/actions/workflows/ci.yaml/badge.svg)](https://github.com/bcoe/c8/actions/workflows/ci.yaml)
|
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://www.conventionalcommits.org/)
|
6 |
|
7 | Code-coverage using [Node.js' built in functionality](https://nodejs.org/dist/latest-v10.x/docs/api/cli.html#cli_node_v8_coverage_dir)
|
8 | that's compatible with [Istanbul's reporters](https://istanbul.js.org/docs/advanced/alternative-reporters/).
|
9 |
|
10 | Like [nyc](https://github.com/istanbuljs/nyc), c8 just magically works:
|
11 |
|
12 | ```sh
|
13 | npm i c8 -g
|
14 | c8 node foo.js
|
15 | ```
|
16 |
|
17 | The above example will output coverage metrics for `foo.js`.
|
18 |
|
19 | ## CLI Options / Configuration
|
20 |
|
21 | c8 can be configured via command-line flags, a `c8` section in `package.json`, or a JSON configuration file on disk.
|
22 |
|
23 | 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
|
24 | `cwd` and walking up the filesystem tree.
|
25 |
|
26 | When using `package.json` configuration or a dedicated configuration file, omit the `--` prefix from the long-form of the desired command-line option.
|
27 |
|
28 | Here is a list of common options. Run `c8 --help` for the full list and documentation.
|
29 |
|
30 | | Option | Description | Type | Default |
|
31 | | ------ | ----------- | ---- | ------- |
|
32 | | `-c`, `--config` | path to JSON configuration file | `string` | See above |
|
33 | | `-r`, `--reporter` | coverage reporter(s) to use | `Array<string>` | `['text']` |
|
34 | | `-o`, `--reports-dir`, `--report-dir` | directory where coverage reports will be output to | `string` | `./coverage` |
|
35 | | `--all` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `boolean` | `false` |
|
36 | | `--src` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `Array<string>` | `[process.cwd()]`|
|
37 | | `-n`, `--include` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `Array<string>` | `[]` (include all files) |
|
38 | | `-x`, `--exclude` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `Array<string>` | [list](https://github.com/istanbuljs/schema/blob/master/default-exclude.js) |
|
39 | | `--exclude-after-remap` | see [section below](#exclude-after-remap) for more info | `boolean` | `false` |
|
40 | | `-e`, `--extension` | only files matching these extensions will show coverage | `string \| Array<string>` | [list](https://github.com/istanbuljs/schema/blob/master/default-extension.js) |
|
41 | | `--skip-full` | do not show files with 100% statement, branch, and function coverage | `boolean` | `false` |
|
42 | | `--check-coverage` | check whether coverage is within thresholds provided | `boolean` | `false` |
|
43 | | `--per-file` | check thresholds per file | `boolean` | `false` |
|
44 | | `--temp-directory` | directory V8 coverage data is written to and read from | `string` | `process.env.NODE_V8_COVERAGE` |
|
45 | | `--clean` | should temp files be deleted before script execution | `boolean` | `true` |
|
46 |
|
47 | ## Checking for "full" source coverage using `--all`
|
48 |
|
49 | By default v8 will only give us coverage for files that were loaded by the engine. If there are source files in your
|
50 | project that are flexed in production but not in your tests, your coverage numbers will not reflect this. For example,
|
51 | if your project's `main.js` loads `a.js` and `b.js` but your unit tests only load `a.js` your total coverage
|
52 | could show as `100%` for `a.js` when in fact both `main.js` and `b.js` are uncovered.
|
53 |
|
54 | By supplying `--all` to c8, all files in directories specified with `--src` (defaults to `cwd`) that pass the `--include`
|
55 | and `--exclude` flag checks, will be loaded into the report. If any of those files remain uncovered they will be factored
|
56 | into the report with a default of 0% coverage.
|
57 |
|
58 | ## SourceMap Support
|
59 |
|
60 | `c8` can handle source-maps, for remapping coverage from generated code to original source files (_useful for TypeScript, JSX, etc_).
|
61 |
|
62 | ### Source map files versus inline source maps
|
63 |
|
64 | 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).
|
65 |
|
66 | 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.
|
67 |
|
68 | `c8` can handle loading both types of source maps.
|
69 |
|
70 | ### Exclude after remap
|
71 |
|
72 | 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.
|
73 |
|
74 | `--exclude-after-remap` is used to control this behaviour.
|
75 |
|
76 | ## c8 report
|
77 |
|
78 | run `c8 report` to regenerate reports after `c8` has already been run.
|
79 |
|
80 | ## Checking coverage
|
81 |
|
82 | c8 can fail tests if coverage falls below a threshold.
|
83 | After running your tests with c8, simply run:
|
84 |
|
85 | ```sh
|
86 | c8 check-coverage --lines 95 --functions 95 --branches 95
|
87 | ```
|
88 |
|
89 | c8 also accepts a `--check-coverage` shorthand, which can be used to
|
90 | both run tests and check that coverage falls within the threshold provided:
|
91 |
|
92 | ```sh
|
93 | c8 --check-coverage --lines 100 npm test
|
94 | ```
|
95 |
|
96 | The above check fails if coverage falls below 100%.
|
97 |
|
98 | To check thresholds on a per-file basis run:
|
99 |
|
100 | ```sh
|
101 | c8 check-coverage --lines 95 --per-file
|
102 | ```
|
103 |
|
104 | If you want to check for 100% coverage across all dimensions, use `--100`:
|
105 |
|
106 | ```sh
|
107 | c8 --100 npm test
|
108 | ```
|
109 |
|
110 | Is equivalent to
|
111 |
|
112 | ```sh
|
113 | c8 --check-coverage --lines 100 --functions 100 --branches 100 --statements 100 npm test
|
114 | ```
|
115 |
|
116 | The `--100` flag can be set for the `check-coverage` as well:
|
117 |
|
118 | ```sh
|
119 | c8 check-coverage --100
|
120 | ```
|
121 |
|
122 | ## Ignoring Uncovered Lines, Functions, and Blocks
|
123 |
|
124 | Sometimes you might find yourself wanting to ignore uncovered portions of your
|
125 | codebase. For example, perhaps you run your tests on Linux, but
|
126 | there's some logic that only executes on Windows.
|
127 |
|
128 | To ignore lines, blocks, and functions, use the special comment:
|
129 |
|
130 | `/* c8 ignore next */`.
|
131 |
|
132 | ### Ignoring the next line
|
133 |
|
134 | ```js
|
135 | const myVariable = 99
|
136 | /* c8 ignore next */
|
137 | if (process.platform === 'win32') console.info('hello world')
|
138 | ```
|
139 |
|
140 | ### Ignoring the next N lines
|
141 |
|
142 | ```js
|
143 | const myVariable = 99
|
144 | /* c8 ignore next 3 */
|
145 | if (process.platform === 'win32') {
|
146 | console.info('hello world')
|
147 | }
|
148 | ```
|
149 |
|
150 | ### Ignoring all lines until told
|
151 |
|
152 | ```js
|
153 | /* c8 ignore start */
|
154 | function dontMindMe() {
|
155 | // ...
|
156 | }
|
157 | /* c8 ignore stop */
|
158 | ```
|
159 |
|
160 | ### Ignoring a block on the current line
|
161 |
|
162 | ```js
|
163 | const myVariable = 99
|
164 | const os = process.platform === 'darwin' ? 'OSXy' /* c8 ignore next */ : 'Windowsy'
|
165 | ```
|
166 |
|
167 | ## Supported Node.js Versions
|
168 |
|
169 | c8 uses [native V8 coverage](https://github.com/nodejs/node/pull/22527),
|
170 | make sure you're running Node.js `>= 10.12.0`.
|
171 |
|
172 | ## Contributing to `c8`
|
173 |
|
174 | See the [contributing guide here](./CONTRIBUTING.md).
|