-
Notifications
You must be signed in to change notification settings - Fork 94
/
Copy pathREADME.md
192 lines (131 loc) · 7.57 KB
/
README.md
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
# c8 - native V8 code-coverage
[](https://github.com/bcoe/c8/actions/workflows/ci.yaml)
[](https://www.conventionalcommits.org/)
Code-coverage using [Node.js' built in functionality](https://nodejs.org/dist/latest-v10.x/docs/api/cli.html#cli_node_v8_coverage_dir)
that's compatible with [Istanbul's reporters](https://istanbul.js.org/docs/advanced/alternative-reporters/).
Like [nyc](https://github.com/istanbuljs/nyc), c8 just magically works:
```sh
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](#checking-for-full-source-coverage-using---all) for more info | `boolean` | `false` |
| `--src` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `Array<string>` | `[process.cwd()]`|
| `-n`, `--include` | see [section below](#checking-for-full-source-coverage-using---all) for more info | `Array<string>` | `[]` (include all files) |
| `-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) |
| `--exclude-after-remap` | see [section below](#exclude-after-remap) for more info | `boolean` | `false` |
| `-e`, `--extension` | only files matching these extensions will show coverage | `string \| Array<string>` | [list](https://github.com/istanbuljs/schema/blob/master/default-extension.js) |
| `--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` |
| `--per-file` | check thresholds per file | `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` |
| `--experimental-monocart` | see [section below](#using-monocart-coverage-reports-experimental) for more info | `boolean` | `false` |
## Checking for "full" source coverage using `--all`
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:
```sh
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:
```sh
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:
```sh
c8 check-coverage --lines 95 --per-file
```
If you want to check for 100% coverage across all dimensions, use `--100`:
```sh
c8 --100 npm test
```
Is equivalent to
```sh
c8 --check-coverage --lines 100 --functions 100 --branches 100 --statements 100 npm test
```
The `--100` flag can be set for the `check-coverage` as well:
```sh
c8 check-coverage --100
```
## Using Monocart coverage reports (experimental)
Monocart is an alternate library for outputting [v8 code coverage](https://v8.dev/blog/javascript-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.
**Example usage:**
```sh
c8 --experimental-monocart --reporter=v8 --reporter=console-details node foo.js
```
NOTE: Monocart requires additional `monocart-coverage-reports` to be installed:
```sh
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:
`/* c8 ignore next */`.
### Ignoring the next line
```js
const myVariable = 99
/* c8 ignore next */
if (process.platform === 'win32') console.info('hello world')
```
### Ignoring the next N lines
```js
const myVariable = 99
/* c8 ignore next 3 */
if (process.platform === 'win32') {
console.info('hello world')
}
```
### Ignoring all lines until told
```js
/* c8 ignore start */
function dontMindMe() {
// ...
}
/* c8 ignore stop */
```
### Ignoring a block on the current line
```js
const myVariable = 99
const os = process.platform === 'darwin' ? 'OSXy' /* c8 ignore next */ : 'Windowsy'
```
## Supported Node.js Versions
c8 uses [native V8 coverage](https://github.com/nodejs/node/pull/22527),
make sure you're running Node.js `>= 12`.
## Contributing to `c8`
See the [contributing guide here](./CONTRIBUTING.md).