From bed4729910559ed4c1a52c524dd85d5824406ac2 Mon Sep 17 00:00:00 2001 From: XhmikosR Date: Fri, 27 Dec 2019 23:21:51 +0200 Subject: [PATCH] chore: Minor Markdown tweaks (#1256) --- README.md | 33 +++++++++++++++-------- docs/instrument.md | 6 ++--- docs/profiling.md | 59 ++++++++++++++++++++--------------------- docs/setup-codecov.md | 5 ++-- docs/setup-coveralls.md | 2 +- 5 files changed, 58 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 4983c5f6c..02e28b25e 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ Istanbul's state of the art command line interface, with support for: Use your package manager to add it as a dev dependency: `npm i -D nyc` or `yarn add -D nyc`. You 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): + ```json { "scripts": { @@ -67,6 +68,7 @@ Please start with the pre-configured [`@istanbuljs/nyc-config-typescript`](https nyc allows you to inherit other configurations using the key `extends` in the `package.json` stanza, `.nycrc`, or YAML files. You can then add the specific configuration options you want that aren't in that particular shared config, e.g. + ```json { "nyc": { @@ -108,8 +110,10 @@ This table is a quick TLDR for the rest of this readme and there are more advanc | `temp-dir` | Directory to output raw coverage information to | `String` | `./.nyc_output` | Configuration can also be provided by `nyc.config.js` if programmed logic is required: + ```js 'use strict'; + const defaultExclude = require('@istanbuljs/schema/default-exclude'); const isWindows = require('is-windows'); @@ -127,7 +131,10 @@ module.exports = { To 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/)). A more advanced use case would be to combine multiple shared configs in a `nyc.config.js` file: + ```js +'use strict'; + const babelConfig = require('@istanbuljs/nyc-config-babel'); const hookRunInThisContextConfig = require('@istanbuljs/nyc-config-hook-run-in-this-context'); @@ -158,9 +165,10 @@ The `exclude` array may also use exclude negated glob patterns, these are specif Globs are matched using [minimatch](https://www.npmjs.com/package/minimatch). We use the following process to remove files from consideration: - 1. Limit the set of instrumented 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 step 2. + +1. Limit the set of instrumented 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 step 2. ### Using include and exclude arrays @@ -231,20 +239,22 @@ If nyc fails to find a directory containing a `package.json` file, it will use t You can change the project root directory with the `--cwd` option. nyc uses the project root directory when: - * looking for source files to instrument - * creating globs for include and exclude rules during file selection - * loading custom require hooks from the `require` array -nyc may create artefact directories within the project root, with these defaults: - * the report directory, `/coverage` - * the cache directory, `/node_modules/.cache/nyc` - * the temp directory, `/.nyc_output` +* looking for source files to instrument +* creating globs for include and exclude rules during file selection +* loading custom require hooks from the `require` array + +nyc may create artifact directories within the project root, with these defaults: + +* the report directory, `/coverage` +* the cache directory, `/node_modules/.cache/nyc` +* the temp directory, `/.nyc_output` ## Require additional modules The `--require` flag can be provided to `nyc` to indicate that additional modules should be required in the subprocess collecting coverage: -``` +```shell nyc --require esm mocha ``` @@ -328,6 +338,7 @@ rather than having to ignore every instance of that method: ``` ## Combining reports from multiple runs + If 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. Originally inspired by @janiukjf in #1001, here's an example, where the `test:*` scripts (not shown) invoke only your test runner(s) and not nyc: diff --git a/docs/instrument.md b/docs/instrument.md index bce1a3b4c..06126b992 100644 --- a/docs/instrument.md +++ b/docs/instrument.md @@ -5,9 +5,9 @@ These files are suitable for client side deployment during end to end testing. You can either pre-instrument your source, or write instrumented source to a stream. Run `nyc instrument --help` to display a full list of available command options. - -## Pre-instrumented source - + +## Pre-instrumented source + You can create pre-instrumented source code by running: ```bash diff --git a/docs/profiling.md b/docs/profiling.md index 4d0f0709b..5dfbbad12 100644 --- a/docs/profiling.md +++ b/docs/profiling.md @@ -1,70 +1,70 @@ - -## Profiling: +# Profiling: The self-coverage tool can provide a [fairly interesting information on how nyc performs](https://github.com/bcoe/nyc/pull/101#issuecomment-165337057) in real world test suites. Doing this is a bit involved, detailed steps follow. *Note:* This assumes your locally cloned development version of `nyc` is in `/user/dev/nyc`, and that you are profiling against the AVA test suite in `/user/dev/ava`. Adapt as required. -### Initial Setup (NYC) +## Initial Setup (NYC) We must use `npm link`, and ensure we have fresh "self-coverage" scripts generated. ```sh # Go to the local clone of nyc -$ cd /user/dev/nyc +cd /user/dev/nyc # Link the local clone globally -$ npm link +npm link # Create the self-coverage instrumented files -$ node ./build-self-coverage +node ./build-self-coverage ``` -### Initial Setup (Test Project) +## Initial Setup (Test Project) ```sh # CD to the real world test suite you want to profile against -$ cd /user/dev/ava +cd /user/dev/ava # Link the globally linked nyc into your local node_modules -$ npm link nyc +npm link nyc ``` This will likely not work with `tap --coverage`, since tap will try to use it's own older copy of nyc instead of your globally linked one. Modify the test script in your test project so it uses the `nyc` binary directly, and disable `tap`s version with the `--no-cov` flag: - `package.json`: +`package.json`: + +```json +{ + "scripts" : { + "test": "nyc tap --no-cov test/*.js" + } +} +``` - ```json - { - "scripts" : { - "test": "nyc tap --no-cov test/*.js" - } - } - ``` -### Each Run +## Each Run ```sh # Clear existing self coverage (`trash` ~== `rm -rf`) -$ cd /user/dev/nyc -$ trash ./.self_coverage +cd /user/dev/nyc +trash ./.self_coverage # Clear the `.nyc_cache` folder in your test project -$ cd /user/dev/ava -$ trash ./.nyc_cache +cd /user/dev/ava +trash ./.nyc_cache # Run your test suite -$ npm test +npm test # Go back to the `nyc` folder and create a self-coverage report -$ cd /user/dev/nyc -$ npm run report +cd /user/dev/nyc +npm run report ``` A detailed profile of your test run now exists in `/user/dev/nyc/coverage/lcov-report` -*Note: * `trash` is a safer version of `rm -rf`. Install via `npm i -g trash-cli`. [More info](https://github.com/sindresorhus/guides/blob/master/how-not-to-rm-yourself.md). +*Note:* `trash` is a safer version of `rm -rf`. Install via `npm i -g trash-cli`. [More info](https://github.com/sindresorhus/guides/blob/master/how-not-to-rm-yourself.md). -### WARNING: Self coverage can cause some confusing problems. +## WARNING: Self coverage can cause some confusing problems. If `index.covered.js` exists, it will be used instead of the normal file. This means your changes to `index.js` will not have an effect until you recreate or delete the self coverage files. Unless you are trying to do some profiling, you should probably delete them so the regular files are used. @@ -72,9 +72,8 @@ You can delete the self coverage scripts and use the regular ones as follows: ```sh # Go to nyc directory and remove the self coverage scripts -$ cd /user/dev/nyc -$ npm run clean +cd /user/dev/nyc +npm run clean ``` You can rerun `node ./build-self-coverage` scripts as desired to re-enable self-coverage. - diff --git a/docs/setup-codecov.md b/docs/setup-codecov.md index 2cd44008d..6d6b2ae4d 100644 --- a/docs/setup-codecov.md +++ b/docs/setup-codecov.md @@ -5,11 +5,12 @@ ## Quick start Assuming your `npm test` does not run `nyc` and you have the `npx` executable (npm v5.2+), have your CI runner execute the following: + ```shell npx nyc --reporter=lcov npm test && npx codecov ``` -## Without `npx` - TravisCI example using npm scripts +## Without `npx` - Travis CI example using npm scripts 1. add the codecov and nyc dependencies: @@ -28,7 +29,7 @@ npx nyc --reporter=lcov npm test && npx codecov } ``` -3. For private repos, add the environment variable `CODECOV_TOKEN` to travis. +3. For private repos, add the environment variable `CODECOV_TOKEN` to Travis CI. 4. add the following to your `.travis.yml`: diff --git a/docs/setup-coveralls.md b/docs/setup-coveralls.md index 623bd1bf2..f5f0dbbbf 100644 --- a/docs/setup-coveralls.md +++ b/docs/setup-coveralls.md @@ -21,7 +21,7 @@ integrated with coveralls and travis-ci.org: } ``` -3. For private repos, add the environment variable `COVERALLS_REPO_TOKEN` to travis. +3. For private repos, add the environment variable `COVERALLS_REPO_TOKEN` to Travis CI. 4. add the following to your `.travis.yml`: