diff options
Diffstat (limited to 'node_modules/nyc/README.md')
| -rw-r--r-- | node_modules/nyc/README.md | 452 |
1 files changed, 0 insertions, 452 deletions
diff --git a/node_modules/nyc/README.md b/node_modules/nyc/README.md deleted file mode 100644 index f1c5e0a10..000000000 --- a/node_modules/nyc/README.md +++ /dev/null @@ -1,452 +0,0 @@ -# nyc - -[](https://travis-ci.org/istanbuljs/nyc) -[](https://coveralls.io/r/bcoe/nyc?branch=master) -[](https://www.npmjs.com/package/nyc) -[](https://ci.appveyor.com/project/bcoe/nyc-ilw23) -[](https://conventionalcommits.org) -[](http://devtoolscommunity.herokuapp.com) - -_Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com)_. - -Istanbul's state of the art command line interface, with support for: - -* applications that spawn subprocesses. -* ES2015 transforms, via [babel-plugin-istanbul](https://github.com/istanbuljs/babel-plugin-istanbul), or source-maps. - -## Instrumenting your code - -You can install nyc as a development dependency and add it to the test stanza -in your package.json. - -```shell -npm i nyc --save-dev -``` - -```json -{ - "scripts": { - "test": "nyc mocha" - } -} -``` - -Alternatively, you can install nyc globally and use it to execute `npm test`: - -```shell -npm i nyc -g -``` - -```shell -nyc npm test -``` - -nyc accepts a wide variety of configuration arguments, run `nyc --help` for -thorough documentation. - -Configuration arguments should be provided prior to the program that nyc -is executing. As an example, the following command executes `npm test`, -and indicates to nyc that it should output both an `lcov` -and a `text-lcov` coverage report. - -```shell -nyc --reporter=lcov --reporter=text-lcov npm test -``` - -### Accurate stack traces using source-maps - -When `produce-source-map` is set to true, then the instrumented source files will -include inline source maps for the instrumenter transform. When combined with -[source-map-support](https://github.com/evanw/node-source-map-support), -stack traces for instrumented code will reflect their original lines. - -### Support for custom require hooks (babel, typescript, etc.) - -nyc supports custom require hooks like -[`babel-register`](http://babeljs.io/docs/usage/require/). nyc can -load the hooks for you, [using the `--require` -flag](#require-additional-modules). - -Source maps are used to map coverage information back to the appropriate lines -of the pre-transpiled code. You'll have to configure your custom require hook -to inline the source-map in the transpiled code. For Babel that means setting -the `sourceMaps` option to `inline`. - -### Source-Map support for pre-instrumented codebases - -If you opt to pre-instrument your source-code (rather than using a just-in-time -transpiler like [`babel-register`](http://babeljs.io/docs/usage/require/)) -nyc supports both inline source-maps and `.map` files. - -_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`. -Otherwise nyc's reports will exclude any files that source-maps remap to folders -covered under exclude rules._ - -## Use with `babel-plugin-istanbul` for Babel Support - -We recommend using [`babel-plugin-istanbul`](https://github.com/istanbuljs/babel-plugin-istanbul) if your -project uses the babel tool chain: - -1. enable the `babel-plugin-istanbul` plugin: - - ```json - { - "babel": { - "presets": ["env"], - "env": { - "test": { - "plugins": ["istanbul"] - } - } - } - } - ``` - - Note: With this configuration, the Istanbul instrumentation will only be active when `NODE_ENV` or `BABEL_ENV` is `test`. - - We recommend using the [`cross-env`](https://npmjs.com/package/cross-env) package to set these environment variables - in your `package.json` scripts in a way that works cross-platform. - -2. disable nyc's instrumentation and source-maps, e.g. in `package.json`: - - ```json - { - "nyc": { - "require": [ - "babel-register" - ], - "sourceMap": false, - "instrument": false - }, - "scripts": { - "test": "cross-env NODE_ENV=test nyc mocha" - } - } - ``` - -That's all there is to it, better ES2015+ syntax highlighting awaits: - -<img width="500" src="screen2.png"> - -## Support for alternate file extensions (.jsx, .mjs) - -Supporting file extensions can be configured through either the configuration arguments or with the `nyc` config section in `package.json`. - -```shell -nyc --extension .jsx --extension .mjs npm test -``` - -```json -{ - "nyc": { - "extension": [ - ".jsx", - ".mjs" - ] - } -} -``` - -## Checking coverage - -nyc can fail tests if coverage falls below a threshold. -After running your tests with nyc, simply run: - -```shell -nyc check-coverage --lines 95 --functions 95 --branches 95 -``` - -nyc also accepts a `--check-coverage` shorthand, which can be used to -both run tests and check that coverage falls within the threshold provided: - -```shell -nyc --check-coverage --lines 100 npm test -``` - -The above check fails if coverage falls below 100%. - -To check thresholds on a per-file basis run: - -```shell -nyc check-coverage --lines 95 --per-file -``` - -## Running reports - -Once you've run your tests with nyc, simply run: - -```bash -nyc report -``` - -To view your coverage report: - -<img width="500" src="screen.png"> - -You can use [any reporters that are supported by `istanbul`](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-reports/lib): `clover`, `cobertura`, `html`, `json-summary`, `json`, `lcov`, `lcovonly`, `none`, `teamcity`, `text-lcov`, `text-summary`, `text`. - -```bash -nyc report --reporter=lcov -``` - -You can find examples of the output for various reporters [here](https://istanbul.js.org/docs/advanced/alternative-reporters). - -You also have the choice of using a [custom reporter](https://github.com/pedrocarrico/istanbul-reporter-aws-cloudwatch-metrics). -Install custom reporters as a development dependency and you can use the `--reporter` flag to load and view them: - -```bash -nyc report --reporter=<custom-reporter-name> -``` - -## Excluding files - -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. - -Globs are matched using [micromatch](https://www.npmjs.com/package/micromatch). - -For example, the following config will exclude any files with the extension `.spec.js`, -and anything in the `build` directory: - -```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. - -> 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. - -## Including files - -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: - -```json -{ - "nyc": { - "include": ["**/build/umd/moment.js"] - } -} -``` - -> `nyc` uses micromatch for glob expansions, you can read its documentation [here](https://www.npmjs.com/package/micromatch). - -> Note: include defaults to `['**']` - -> ### Use the `--all` flag to include files that have not been required in your tests. - -## Require additional modules - -The `--require` flag can be provided to `nyc` to indicate that additional -modules should be required in the subprocess collecting coverage: - -`nyc --require babel-register --require babel-polyfill mocha` - -## Caching - -You can run `nyc` with the optional `--cache` flag, to prevent it from -instrumenting the same files multiple times. This can significantly -improve runtime performance. - -## Configuring `nyc` - -Any 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 `.nycrc` file: - -**package.json:** - -```json -{ - "description": "These are just examples for demonstration, nothing prescriptive", - "nyc": { - "check-coverage": true, - "per-file": true, - "lines": 99, - "statements": 99, - "functions": 99, - "branches": 99, - "include": [ - "src/**/*.js" - ], - "exclude": [ - "src/**/*.spec.js" - ], - "ignore-class-method": "methodToIgnore", - "reporter": [ - "lcov", - "text-summary" - ], - "require": [ - "./test/helpers/some-helper.js" - ], - "extension": [ - ".jsx" - ], - "cache": true, - "all": true, - "temp-directory": "./alternative-tmp", - "report-dir": "./alternative" - } -} -``` - -### Publish, and reuse, your nyc configuration - -nyc allows you to inherit other configurations using the key `extends`. As an example, -an alternative way to configure nyc for `babel-plugin-istanbul` would be to use the -[@istanbuljs/nyc-config-babel preset](https://www.npmjs.com/package/@istanbuljs/nyc-config-babel): - -```json -{ - "nyc": { - "extends": "@istanbuljs/nyc-config-babel" - } -} -``` - -To publish and resuse your own `nyc` configuration, simply create an npm module that -exports an `index.json` with your `nyc` config. - -## High and low watermarks - -Several of the coverage reporters supported by nyc display special information -for high and low watermarks: - -* high-watermarks represent healthy test coverage (in many reports - this is represented with green highlighting). -* low-watermarks represent sub-optimal coverage levels (in many reports - this is represented with red highlighting). - -You can specify custom high and low watermarks in nyc's configuration: - -```json -{ - "nyc": { - "watermarks": { - "lines": [80, 95], - "functions": [80, 95], - "branches": [80, 95], - "statements": [80, 95] - } - } -} -``` - -## Parsing Hints (Ignoring Lines) - -There may be some sections of your codebase that you wish to purposefully -exclude from coverage tracking, to do so you can use the following parsing -hints: - -* `/* istanbul ignore if */`: ignore the next if statement. -* `/* istanbul ignore else */`: ignore the else portion of an if statement. -* `/* istanbul ignore next */`: ignore the next _thing_ in the source-code ( - functions, if statements, classes, you name it). -* `/* istanbul ignore file */`: ignore an entire source-file (this should be - placed at the top of the file). - -## Ignoring Methods - -There may be some methods that you want to universally ignore out of your classes -rather than having to ignore every instance of that method: - -```json -{ - "nyc": { - "ignore-class-method": "render" - } -} -``` - -## Integrating with coveralls - -[coveralls.io](https://coveralls.io) is a great tool for adding -coverage reports to your GitHub project. Here's how to get nyc -integrated with coveralls and travis-ci.org: - -1. add the coveralls and nyc dependencies to your module: - - ```shell - npm install coveralls nyc --save-dev - ``` - -2. update the scripts in your package.json to include these bins: - - ```json - { - "scripts": { - "test": "nyc mocha", - "coverage": "nyc report --reporter=text-lcov | coveralls" - } - } - ``` - -3. For private repos, add the environment variable `COVERALLS_REPO_TOKEN` to travis. - -4. add the following to your `.travis.yml`: - - ```yaml - after_success: npm run coverage - ``` - -That's all there is to it! - -> Note: by default coveralls.io adds comments to pull-requests on GitHub, this can feel intrusive. To disable this, click on your repo on coveralls.io and uncheck `LEAVE COMMENTS?`. - -## Integrating with codecov - -`nyc npm test && nyc report --reporter=text-lcov > coverage.lcov && codecov` - -[codecov](https://codecov.io/) is a great tool for adding -coverage reports to your GitHub project, even viewing them inline on GitHub with a browser extension: - -Here's how to get `nyc` integrated with codecov and travis-ci.org: - -1. add the codecov and nyc dependencies to your module: - - ```shell - npm install codecov nyc --save-dev - ``` - -2. update the scripts in your package.json to include these bins: - - ```json - { - "scripts": { - "test": "nyc tap ./test/*.js", - "coverage": "nyc report --reporter=text-lcov > coverage.lcov && codecov" - } - } - ``` - -3. For private repos, add the environment variable `CODECOV_TOKEN` to travis. - -4. add the following to your `.travis.yml`: - - ```yaml - after_success: npm run coverage - ``` - -That's all there is to it! - -## Integrating with TAP formatters - -Many 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. - -## More tutorials - -You can find more tutorials at http://istanbul.js.org/docs/tutorials - -## Other advanced features - -Take a look at http://istanbul.js.org/docs/advanced/ and please feel free to [contribute documentation](https://github.com/istanbuljs/istanbuljs.github.io/tree/development/content). |