1 | # coverage-node
|
2 |
|
3 | [![npm version](https://badgen.net/npm/v/coverage-node)](https://npm.im/coverage-node) [![CI status](https://github.com/jaydenseric/coverage-node/workflows/CI/badge.svg)](https://github.com/jaydenseric/coverage-node/actions)
|
4 |
|
5 | A simple CLI to run [Node.js](https://nodejs.org) and report code coverage.
|
6 |
|
7 | - ✨ Zero config.
|
8 | - 🏁 Tiny [SLOC](https://en.wikipedia.org/wiki/Source_lines_of_code), written from scratch to use [code coverage features](https://nodejs.org/api/cli.html#cli_node_v8_coverage_dir) built into Node.js v10+.
|
9 | - 📦 [Lean install size](https://packagephobia.com/result?p=coverage-node), compared to [2.2 MB for `c8` v7.7.1](https://packagephobia.com/result?p=c8@7.7.1) or [8.84 MB for `nyc` v15.1.0](https://packagephobia.com/result?p=nyc@15.1.0).
|
10 | - 🖱 Displays ignored or uncovered source code ranges as paths, clickable in IDEs such as [VS Code](https://code.visualstudio.com).
|
11 |
|
12 | ## Installation
|
13 |
|
14 | To install with [npm](https://npmjs.com/get-npm), run:
|
15 |
|
16 | ```sh
|
17 | npm install coverage-node --save-dev
|
18 | ```
|
19 |
|
20 | In a [`package.json` script](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#scripts), replace the `node` command with [`coverage-node`](#command-coverage-node):
|
21 |
|
22 | ```diff
|
23 | {
|
24 | "scripts": {
|
25 | - "test": "node test.mjs"
|
26 | + "test": "coverage-node test.mjs"
|
27 | }
|
28 | }
|
29 | ```
|
30 |
|
31 | ## Requirements
|
32 |
|
33 | - Operating system:
|
34 | - Linux
|
35 | - macOS
|
36 | - [Node.js](https://nodejs.org): `^12.22.0 || ^14.17.0 || >= 16.0.0`, but for Node.js versions < v13.3 that produce [unreliable coverage data](https://github.com/nodejs/node/issues/25937#issuecomment-563115421) the command [`coverage-node`](#command-coverage-node) skips code coverage and logs a warning.
|
37 |
|
38 | ## Ignored files
|
39 |
|
40 | Code coverage analysis ignores:
|
41 |
|
42 | - `node_modules` directory files, e.g. `node_modules/foo/index.mjs`.
|
43 | - `test` directory files, e.g. `test/index.mjs`.
|
44 | - Files with `.test` prefixed before the extension, e.g. `foo.test.mjs`.
|
45 | - Files named `test` (regardless of extension), e.g. `test.mjs`.
|
46 |
|
47 | ## Ignored lines
|
48 |
|
49 | In source code, a comment (case insensitive) can be used to ignore code coverage ranges that start on the the next line:
|
50 |
|
51 | ```js
|
52 | // coverage ignore next line
|
53 | if (false) console.log("Never runs.");
|
54 | ```
|
55 |
|
56 | ## CLI
|
57 |
|
58 | ### Command `coverage-node`
|
59 |
|
60 | Substitutes the normal `node` command; any [`node` CLI options](https://nodejs.org/api/cli.html#cli_options) can be used to run a test script. If the script doesn’t error a code coverage analysis is reported to the console, and if coverage is incomplete and there isn’t a truthy `ALLOW_MISSING_COVERAGE` environment variable the process exits with code `1`.
|
61 |
|
62 | #### Examples
|
63 |
|
64 | [`npx`](https://docs.npmjs.com/cli/v8/commands/npx) can be used to quickly check code coverage for a script:
|
65 |
|
66 | ```sh
|
67 | npx coverage-node test.mjs
|
68 | ```
|
69 |
|
70 | A [`package.json` script](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#scripts):
|
71 |
|
72 | ```json
|
73 | {
|
74 | "scripts": {
|
75 | "test": "coverage-node test.mjs"
|
76 | }
|
77 | }
|
78 | ```
|
79 |
|
80 | A [`package.json` script](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#scripts) that allows missing coverage:
|
81 |
|
82 | ```json
|
83 | {
|
84 | "scripts": {
|
85 | "test": "ALLOW_MISSING_COVERAGE=1 coverage-node test.mjs"
|
86 | }
|
87 | }
|
88 | ```
|
89 |
|
90 | ## Exports
|
91 |
|
92 | These ECMAScript modules are published to [npm](https://npmjs.com) and exported via the [`package.json`](./package.json) `exports` field:
|
93 |
|
94 | - [`analyseCoverage.mjs`](./analyseCoverage.mjs)
|
95 | - [`coverageSupported.mjs`](./coverageSupported.mjs)
|
96 | - [`coverageSupportedMinNodeVersion.mjs`](./coverageSupportedMinNodeVersion.mjs)
|
97 | - [`reportCoverage.mjs`](./reportCoverage.mjs)
|
98 |
|
\ | No newline at end of file |