{"id":13454865,"url":"https://github.com/istanbuljs/nyc","last_synced_at":"2026-02-22T23:16:03.709Z","repository":{"id":31746383,"uuid":"35312458","full_name":"istanbuljs/nyc","owner":"istanbuljs","description":"the Istanbul command line interface","archived":false,"fork":false,"pushed_at":"2024-12-06T05:42:03.000Z","size":2622,"stargazers_count":5664,"open_issues_count":216,"forks_count":362,"subscribers_count":53,"default_branch":"main","last_synced_at":"2025-05-05T14:53:55.434Z","etag":null,"topics":["code-coverage","istanbul","javascript"],"latest_commit_sha":null,"homepage":"https://istanbul.js.org/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/istanbuljs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"tidelift":"npm/istanbul-reports"}},"created_at":"2015-05-09T02:55:45.000Z","updated_at":"2025-04-30T08:45:16.000Z","dependencies_parsed_at":"2023-02-18T22:45:59.331Z","dependency_job_id":"a984cc1c-7a0e-4e58-8848-9cdc78fc231f","html_url":"https://github.com/istanbuljs/nyc","commit_stats":{"total_commits":745,"total_committers":102,"mean_commits":7.303921568627451,"dds":0.621476510067114,"last_synced_commit":"ab7c53b2f340b458789a746dff2abd3e2e4790c3"},"previous_names":["bcoe/nyc"],"tags_count":117,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/istanbuljs%2Fnyc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/istanbuljs%2Fnyc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/istanbuljs%2Fnyc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/istanbuljs%2Fnyc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/istanbuljs","download_url":"https://codeload.github.com/istanbuljs/nyc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253777086,"owners_count":21962629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-coverage","istanbul","javascript"],"created_at":"2024-07-31T08:00:58.735Z","updated_at":"2026-02-22T23:16:03.298Z","avatar_url":"https://github.com/istanbuljs.png","language":"JavaScript","funding_links":["https://tidelift.com/funding/github/npm/istanbul-reports","https://tidelift.com/subscription/pkg/npm-nyc?utm_source=npm-nyc\u0026utm_medium=referral\u0026utm_campaign=enterprise\u0026utm_term=repo"],"categories":["Packages","JavaScript","Repository","javascript","📦 Modules/Packages","包","TDD, Tests with JS"],"sub_categories":["Testing",":curly_loop: Typography","测试","VUE Vida Real (Boilerplates)"],"readme":"# nyc\n\n[![ci](https://github.com/istanbuljs/nyc/actions/workflows/ci.yaml/badge.svg)](https://github.com/bcoe/c8/actions/workflows/ci.yaml)\n[![NPM version](https://img.shields.io/npm/v/nyc.svg)](https://www.npmjs.com/package/nyc)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\n_Having problems? want to contribute? join our [community slack](https://devtoolscommunity.herokuapp.com)_.\n\nIstanbul's state of the art command line interface, with support for:\n\n* applications that spawn subprocesses.\n* source mapped coverage of Babel and TypeScript projects\n\n## How Istanbul works\n\nIstanbul instruments your ES5 and ES2015+ JavaScript code with line counters, so that you can track how well your unit-tests exercise your codebase.\n\nThe `nyc` command-line-client for Istanbul works well with most JavaScript testing frameworks: tap, mocha, AVA, etc.\n\n## Installation \u0026 Usage\n\nUse your package manager to add it as a dev dependency: `npm i -D nyc` or `yarn add -D nyc`.\nYou can use nyc to call npm scripts (assuming they don't already have nyc executed in them), like so (replace `mocha` with your test runner everywhere you see it):\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"mocha\",\n    \"coverage\": \"nyc npm run test\"\n  }\n}\n```\n\nYou can use also `npx` instead of installing nyc as a dependency, but you might get updates you are not ready for; to get around this, pin to a specific major version by specifying, e.g. `nyc@14`.\n\n```json\n{\n  \"scripts\": {\n    \"test\": \"npx nyc@latest mocha\"\n  }\n}\n```\n\nThis is a good way of testing upcoming releases of nyc, usually on the `next` tag.\n\n**Note**: If you use [`jest`](https://npm.im/jest) or [`tap`](https://www.node-tap.org/), you do not need to install `nyc`.\nThose runners already have the IstanbulJS libraries to provide coverage for you.\nFollow their documentation to enable and configure coverage reporting.\n\n## Configuring `nyc`\n\nnyc accepts a wide variety of configuration arguments, run `npx nyc --help` for thorough documentation.\n\nConfiguration arguments on the command-line should be provided prior to the program that nyc is executing.\nAs an example, the following command executes `ava`, and indicates to nyc that it should output both an `lcov` (`lcov.info` + html report) and a `text-summary` coverage report.\n\n```shell\nnyc --reporter=lcov --reporter=text-summary ava\n```\n\n### Babel projects\n\nPlease start with the pre-configured [`@istanbuljs/nyc-config-babel`] preset.\nYou can add your custom configuration options as shown below.\n\n### TypeScript projects\n\nPlease start with the pre-configured [`@istanbuljs/nyc-config-typescript`](https://www.npmjs.com/package/@istanbuljs/nyc-config-typescript) preset.\n\n#### Adding your overrides\n\nnyc allows you to inherit other configurations using the key `extends` in the `package.json` stanza, `.nycrc`, or YAML files.\nYou can then add the specific configuration options you want that aren't in that particular shared config, e.g.\n\n```json\n{\n  \"extends\": \"@istanbuljs/nyc-config-typescript\",\n  \"all\": true,\n  \"check-coverage\": true\n}\n```\n\n### Configuration files\n\nAny configuration options that can be set via the command line can also be specified in the `nyc` stanza of your package.json, or within a separate configuration file - a variety of flavors are available:\n\n| File name       | File Association |\n|-----------------|------------------|\n| `.nycrc`        | JSON             |\n| `.nycrc.json`   | JSON             |\n| `.nycrc.yaml`   | YAML             |\n| `.nycrc.yml`    | YAML             |\n| `nyc.config.js` | CommonJS export  |\n\n### Common Configuration Options\n\nSee `nyc --help` for all options available.\nYou can set these in any of the files listed above, or from the command line.\nThis table is a quick TLDR for the rest of this readme and there are more advanced docs available.\n\n| Option name | Description | Type | Default |\n| ----------- | ----------- | ---- | ------- |\n| `all` | Whether or not to instrument all files (not just the ones touched by your test suite) | `Boolean` | `false` |\n| `check-coverage` | Check whether coverage is within thresholds, fail if not | `Boolean` | `false` |\n| `extension` | List of extensions that nyc should attempt to handle in addition to `.js` | `Array\u003cString\u003e` | `['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx']` |\n| `include` | See [selecting files for coverage] for more info | `Array\u003cString\u003e` | `['**']`|\n| `exclude` | See [selecting files for coverage] for more info | `Array\u003cString\u003e` | [list](https://github.com/istanbuljs/schema/blob/master/default-exclude.js) |\n| `reporter` | May be set to a [built-in coverage reporter](https://istanbul.js.org/docs/advanced/alternative-reporters/) or an npm package (dev)dependency | `Array\u003cString\u003e` | `['text']` |\n| `report-dir` | Where to put the coverage report files | `String` | `./coverage` |\n| `skip-full` | Don't show files with 100% statement, branch, and function coverage | `Boolean` | `false` |\n| `temp-dir` | Directory to output raw coverage information to | `String` | `./.nyc_output` |\n\nConfiguration can also be provided by `nyc.config.js` if programmed logic is required:\n\n```js\n'use strict';\n\nconst defaultExclude = require('@istanbuljs/schema/default-exclude');\nconst isWindows = require('is-windows');\n\nlet platformExclude = [\n  isWindows() ? 'lib/posix.js' : 'lib/win32.js'\n];\n\nmodule.exports = {\n  exclude: platformExclude.concat(defaultExclude)\n};\n```\n\n### Publish and reuse your nyc configuration(s)\n\nTo publish and reuse your own `nyc` configuration, simply create an npm module that exports your JSON config (via [`index.json`](https://github.com/istanbuljs/istanbuljs/blob/master/packages/nyc-config-typescript/) or a CJS [`index.js`](https://github.com/istanbuljs/istanbuljs/blob/master/packages/nyc-config-hook-run-in-this-context/)).\n\nA more advanced use case would be to combine multiple shared configs in a `nyc.config.js` file:\n\n```js\n'use strict';\n\nconst babelConfig = require('@istanbuljs/nyc-config-babel');\nconst hookRunInThisContextConfig = require('@istanbuljs/nyc-config-hook-run-in-this-context');\n\nmodule.exports = {\n  ...babelConfig,\n  ...hookRunInThisContextConfig,\n  all: true,\n  'check-coverage': true\n};\n```\n\n## Selecting files for coverage\n\nBy default, nyc only collects coverage for source files that are visited during a test.\nIt does this by watching for files that are `require()`'d during the test.\nWhen a file is `require()`'d, nyc creates and returns an instrumented version of the source, rather than the original.\nOnly source files that are visited during a test will appear in the coverage report and contribute to coverage statistics.\n\nnyc will instrument all files if the `--all` flag is set or if running `nyc instrument`.\nIn this case all files will appear in the coverage report and contribute to coverage statistics.\n\nnyc will only collect coverage for files that are located under `cwd`, and then only files with extensions listed in the `extension` array.\n\nYou can reduce the set of instrumented files by adding `include` and `exclude` filter arrays to your config.\nThese allow you to shape the set of instrumented files by specifying glob patterns that can filter files from the default instrumented set.\nThe `exclude` array may also use exclude negated glob patterns, these are specified with a `!` prefix, and can restore sub-paths of excluded paths.\n\nGlobs are matched using [minimatch](https://www.npmjs.com/package/minimatch).\n\nWe use the following process to remove files from consideration:\n\n1. Limit the set of instrumented files to those files in paths listed in the `include` array.\n2. Remove any files that are found in the `exclude` array.\n3. Restore any exclude negated files that have been excluded in step 2.\n\n### Using include and exclude arrays\n\nIf there are paths specified in the `include` array, then the set of instrumented files will be limited to eligible files found in those paths.\nIf the `include` array is left undefined all eligible files will be included, equivalent to setting `include: ['**']`.\nMultiple `include` globs can be specified on the command line, each must follow a `--include`, `-n` switch.\n\nIf there are paths specified in the `exclude` array, then the set of instrumented files will not feature eligible files found in those paths.\nYou can also specify negated paths in the `exclude` array, by prefixing them with a `!`.\nNegated paths can restore paths that have been already been excluded in the `exclude` array.\nMultiple `exclude` globs can be specified on the command line, each must follow a `--exclude`, `-x` switch.\n\nThe default `exclude` list is defined in the [@istanbuljs/schema module](https://github.com/istanbuljs/schema/blob/master/default-exclude.js).\nSpecifying your own exclude property completely replaces these defaults.\n\nFor example, the following `nyc` config will collect coverage for every file in the `src` directory regardless of whether it is `require()`'d in a test.\nIt will also exclude any files with the extension `.spec.js`.\n\n```json\n{\n  \"all\": true,\n  \"include\": [\n    \"src/**/*.js\"\n  ],\n  \"exclude\": [\n    \"**/*.spec.js\"\n  ]\n}\n```\n\n**Note:** Be wary of automatic OS glob expansion when specifying include/exclude globs with the CLI.\nTo prevent this, wrap each glob in single quotes.\n\n### Including files within `node_modules`\n\nWe always add `**/node_modules/**` to the exclude list, even if not specified in the config.\nYou can override this by setting `--exclude-node-modules=false`.\n\nFor example, `\"excludeNodeModules: false\"` in the following `nyc` config will prevent `node_modules` from being added to the exclude rules.\nThe set of include rules then restrict nyc to only consider instrumenting files found under the `lib/` and `node_modules/@my-org/` directories.\nThe exclude rules then prevent nyc instrumenting anything in a `test` folder and the file `node_modules/@my-org/something/unwanted.js`.\n\n```json\n{\n  \"all\": true,\n  \"include\": [\n    \"lib/**\",\n    \"node_modules/@my-org/**\"\n  ],\n  \"exclude\": [\n    \"node_modules/@my-org/something/unwanted.js\",\n    \"**/test/**\"\n  ],\n  \"excludeNodeModules\": false\n}\n```\n\n## Setting the project root directory\n\nnyc runs a lot of file system operations relative to the project root directory.\nDuring startup nyc will look for the *default* project root directory.\nThe *default* project root directory is the first directory found that contains a `package.json` file when searching from the current working directory up.\nIf nyc fails to find a directory containing a `package.json` file, it will use the current working directory as the *default* project root directory.\nYou can change the project root directory with the `--cwd` option.\n\nnyc uses the project root directory when:\n\n* looking for source files to instrument\n* creating globs for include and exclude rules during file selection\n* loading custom require hooks from the `require` array\n\nnyc may create artifact directories within the project root, with these defaults:\n\n* the report directory, `\u003cproject-root\u003e/coverage`\n* the cache directory, `\u003cproject-root\u003e/node_modules/.cache/nyc`\n* the temp directory, `\u003cproject-root\u003e/.nyc_output`\n\n## Require additional modules\n\nThe `--require` flag can be provided to `nyc` to indicate that additional modules should be required in the subprocess collecting coverage:\n\n```shell\nnyc --require esm mocha\n```\n\n### Interaction with `--all` flag\n\nThe `--require` flag also operates on the main nyc process for use by `--all`.\nFor example, in situations with `nyc --all --instrument false` and [`babel-plugin-istanbul`] setup the `--all` option only works if `--require @babel/register` is passed to nyc.\nPassing it to mocha would cause the tests to be instrumented but unloaded sources would not be seen.\nThe [`@istanbuljs/nyc-config-babel`] package handles this for you!\n\n## Caching\n\n`nyc`'s default behavior is to cache instrumented files to disk to prevent instrumenting source files multiple times, and speed `nyc` execution times.\nYou can disable this behavior by running `nyc` with the `--cache false` flag.\nYou can also change the default cache directory from `./node_modules/.cache/nyc` by setting the `--cache-dir` flag.\n\n## Coverage thresholds\n\nYou can set custom coverage thresholds that will fail if `check-coverage` is set to `true` and your coverage drops below those thresholds.\nFor example, in the following `nyc` configuration, dropping below 80% branch, line, functions, or statements coverage would fail the build (you can have any combination of these):\n\n```json\n{\n  \"branches\": 80,\n  \"lines\": 80,\n  \"functions\": 80,\n  \"statements\": 80\n}\n```\n\nTo do this check on a per-file basis (as opposed to in aggregate), set the `per-file` option to `true`.\n\n### High and low watermarks\n\nSeveral of the coverage reporters supported by nyc display special information for high and low watermarks:\n\n* high-watermarks represent healthy test coverage (in many reports this is represented with green highlighting).\n* low-watermarks represent sub-optimal coverage levels (in many reports this is represented with red highlighting).\n\nYou can specify custom high and low watermarks in nyc's configuration:\n\n```json\n{\n  \"watermarks\": {\n    \"lines\": [80, 95],\n    \"functions\": [80, 95],\n    \"branches\": [80, 95],\n    \"statements\": [80, 95]\n  }\n}\n```\n\n## Parsing Hints (Ignoring Lines)\n\nThere may be some sections of your codebase that you wish to purposefully\nexclude from coverage tracking, to do so you can use the following parsing\nhints:\n\n* `/* istanbul ignore if */`: ignore the next if statement.\n* `/* istanbul ignore else */`: ignore the else portion of an if statement.\n* `/* istanbul ignore next */`: ignore the next _thing_ in the source-code (\n functions, if statements, classes, you name it).\n* `/* istanbul ignore file */`: ignore an entire source-file (this should be\n  placed at the top of the file).\n\n## Ignoring Methods\n\nYou can ignore every instance of a method simply by adding its name to the `ignore-class-method` array in your `nyc` config.\n\n```json\n{\n  \"ignore-class-method\": [\"render\"]\n}\n```\n\n## Combining reports from multiple runs\n\nIf for whatever reason you have different test runners in your project or a different series of test runs for different kinds of tests, nyc will automatically combine the coverage report for you if configured correctly with the `--no-clean` flag and the `report` command.\nOriginally inspired by @janiukjf in #1001, here's an example, where the `test:*` scripts (not shown) invoke only your test runner(s) and not nyc:\n\n```json\n{\n  \"scripts\": {\n    \"cover\": \"npm run cover:unit \u0026\u0026 npm run cover:integration \u0026\u0026 npm run cover:report\",\n    \"cover:unit\": \"nyc --silent npm run test:unit\",\n    \"cover:integration\": \"nyc --silent --no-clean npm run test:integration\",\n    \"cover:report\": \"nyc report --reporter=lcov --reporter=text\"\n  }\n}\n```\n\n### What about `nyc merge`?\n\nThe `nyc merge` command is for producing one _raw coverage output file_ that combines the results from many test runs.\nSo if you had the above setup and needed to produce a single `coverage.json` for some external tool, you could do:\n\n```json\n{\n  \"scripts\": {\n    \"cover:merge\": \"npm run cover:unit \u0026\u0026 npm run cover:integration \u0026\u0026 nyc merge .nyc_output coverage.json\"\n  }\n}\n```\n\n## Source-Map support for pre-instrumented codebases\n\nIf you opt to pre-instrument your source-code (rather than using a just-in-time transpiler like [`@babel/register`]) nyc supports both inline source-maps and `.map` files.\n\n_Important: If you are using nyc with a project that pre-instruments its code, run nyc with the configuration option `--exclude-after-remap` set to `false`.\nOtherwise nyc's reports will exclude any files that source-maps remap to folders covered under exclude rules._\n\n## [Integrating with coveralls](./docs/setup-coveralls.md)\n\n## [Integrating with codecov](./docs/setup-codecov.md)\n\n## [Producing instrumented source](./docs/instrument.md)\n\n## Integrating with TAP formatters\n\nMany testing frameworks (Mocha, Tape, Tap, etc.) can produce [TAP](https://en.wikipedia.org/wiki/Test_Anything_Protocol) output. [tap-nyc](https://github.com/MegaArman/tap-nyc) is a TAP formatter designed to look nice with nyc.\n\n## Tutorials and Advanced Documentation\n\nSee [more nyc tutorials](https://istanbul.js.org/docs/tutorials) and [advanced nyc documentation](https://istanbul.js.org/docs/advanced/).\n\nPlease feel free to [contribute documentation](https://github.com/istanbuljs/istanbuljs.github.io/tree/development/content) to help us improve.\n\n## `nyc` for enterprise\n\nAvailable as part of the Tidelift Subscription.\n\nThe maintainers of `nyc` and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-nyc?utm_source=npm-nyc\u0026utm_medium=referral\u0026utm_campaign=enterprise\u0026utm_term=repo)\n\n[`@babel/register`]: https://www.npmjs.com/package/@babel/register\n[`babel-plugin-istanbul`]: https://github.com/istanbuljs/babel-plugin-istanbul\n[`@istanbuljs/nyc-config-babel`]: https://www.npmjs.com/package/@istanbuljs/nyc-config-babel\n[selecting files for coverage]: #selecting-files-for-coverage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fistanbuljs%2Fnyc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fistanbuljs%2Fnyc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fistanbuljs%2Fnyc/lists"}