From a161d23e5cabf1df0b91c26becd557f15cad7a06 Mon Sep 17 00:00:00 2001 From: AndrewFinlay Date: Wed, 6 Mar 2019 09:38:32 +1100 Subject: [PATCH] docs: Update description of how files are selected for instrumentation (#1009) --- README.md | 88 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 8906b4a90..9ed35e72b 100644 --- a/README.md +++ b/README.md @@ -195,52 +195,78 @@ Install custom reporters as a development dependency and you can use the `--repo nyc report --reporter= ``` -## Excluding files +## Selecting files for coverage -You can tell nyc to exclude specific files and directories by adding -an `nyc.exclude` array to your `package.json`. Each element of -the array is a glob pattern indicating which paths should be omitted. +By default, nyc only collects coverage for source files that are visited during a test. +It does this by watching for files that are `require()`'d during the test. +Only source files that are visited during a test will appear in the coverage report and contribute to coverage statistics. -Globs are matched using [minimatch](https://www.npmjs.com/package/minimatch). +nyc will instrument all files if the `--all` flag is set. +In this case all files will appear in the coverage report and contribute to coverage statistics. -For example, the following config will exclude any files with the extension `.spec.js`, -and anything in the `build` directory: +nyc will only collect coverage for files that are located under `cwd`, and then only `*.js` files or files with extensions listed in in the `extension` array. -```json -{ - "nyc": { - "exclude": [ - "**/*.spec.js", - "build" - ] - } -} -``` -> Note: Since version 9.0 files under `node_modules/` are excluded by default. - add the exclude rule `!**/node_modules/` to stop this. +You can reduce the set of covered files by adding `include` and `exclude` filter arrays to your config. +These allow you to shape the set of covered files by specifying glob patterns that can filter files from the covered set. +The `exclude` array may also use exclude negated glob patterns, these are specified with a `!` prefix, and can restore sub-paths of excluded paths. + +Globs are matched using [minimatch](https://www.npmjs.com/package/minimatch). -> Note: exclude defaults to `['coverage/**', 'test/**', 'test{,-*}.js', '**/*.test.js', '**/__tests__/**', '**/node_modules/**']`, -which would exclude `test`/`__tests__` directories as well as `test.js`, `*.test.js`, -and `test-*.js` files. Specifying your own exclude property overrides these defaults. +We use the following process to remove files from consideration: + 1. Limit the set of covered files to those files in paths listed in the `include` array. + 2. Remove any files that are found in the `exclude` array. + 3. Restore any exclude negated files that have been excluded in the second step. + + +### Using include and exclude arrays + +If there are paths specified in the `include` array, then the set of covered files will be limited to eligible files found in those paths. +If the `include` array is left undefined all eligible files will be included, equivalent to setting `include: ['**']`. +Include options can be specified on the command line with the `-n` switch. + +If there are paths specified in the `exclude` array, then the set of covered files will not feature eligible files found in those paths. +You can also specify negated paths in the `exclude` array, by prefixing them with a `!`. +Negated paths can restore paths that have been already been excluded in the `exclude` array. +Exclude options can be specified on the command line with the `-x` switch. + +The `exclude` option has the following defaults settings: +```js +[ + 'coverage/**', + 'packages/*/test/**', + 'test/**', + 'test{,-*}.js', + '**/*{.,-}test.js', + '**/__tests__/**', + '**/node_modules/**', + '**/babel.config.js' +] +``` +These settings exclude `test` and `__tests__` directories as well as `test.js`, `*.test.js`, and `test-*.js` files. +Specifying your own exclude property completely replaces these defaults. -## Including files +**Note:** The exclude list always implicitly contains `**/node_modules/**`, even if not explicitly specified in an overriding `exclude` array. +To reverse this you must add the negated exclude rule `!**/node_modules/`. -As an alternative to providing a list of files to `exclude`, you can provide -an `include` key with a list of globs to specify specific files that should be covered: +For example, the following config will collect coverage for every file in the `src` directory regardless of whether it is `require()`'d in a test. +It will also exclude any files with the extension `.spec.js`. ```json { "nyc": { - "include": ["**/build/umd/moment.js"] + "all": true, + "include": [ + "src/**/*.js" + ], + "exclude": [ + "**/*.spec.js" + ] } } ``` -> `nyc` uses minimatch for glob expansions, you can read its documentation [here](https://www.npmjs.com/package/minimatch). - -> Note: include defaults to `['**']` - -> ### Use the `--all` flag to include files that have not been required in your tests. +**Note:** Be wary of automatic OS glob expansion when specifying include/exclude globs with the CLI. +To prevent this, wrap each glob in single quotes. ## Require additional modules