nyc

When self-coverage is enabled, nyc uses index.covered.js instead of the normal files. This means changes to your standard source files (like index.js) will not be reflected until the self-coverage files are removed. To revert to regular files, run the clean script in the nyc directory.

# Go to nyc directory and remove the self coverage scripts
cd /user/dev/nyc
npm run clean

For optimal setup, use the recommended presets:

• Babel: Use @istanbuljs/nyc-config-babel.
• TypeScript: Use @istanbuljs/nyc-config-typescript.

You can extend these presets in your configuration files using the extends key.

{
  "extends": "@istanbuljs/nyc-config-typescript",
  "all": true,
  "check-coverage": true
}

To integrate coverage reporting into your workflow using npm scripts (e.g., for Travis CI), follow these steps:

1. Install the necessary dependencies:

   npm install codecov nyc --save-dev

2. Update your package.json scripts. Ensure your test script is wrapped by nyc with the --reporter=lcov flag, and add a coverage script to run codecov:

   {
      "scripts": {
        "test": "nyc --reporter=lcov mocha",
        "coverage": "codecov"
      }
   }

   (Note: Replace mocha with your actual test runner.)

3. For private repositories, ensure the CODECOV_TOKEN environment variable is configured in your CI environment.

4. Configure your CI (e.g., .travis.yml) to run the coverage script after tests succeed:

   after_success: npm run coverage

By default, nyc only instruments files visited during tests. To change this behavior:

1. Instrument all files: Set all: true or use the --all flag.
2. Filter files: Use include and exclude arrays with glob patterns (matched via minimatch).
3. Negated globs: Use ! in the exclude array to restore specific sub-paths that were previously excluded.

CLI Tip: When using globs in the CLI, wrap them in single quotes to prevent OS shell expansion.

{
  "all": true,
  "include": [
    "src/**/*.js"
  ],
  "exclude": [
    "**/*.spec.js"
  ]
}

To profile how nyc performs in real-world test suites, you must create self-coverage instrumented files using a local clone of the nyc repository. This requires linking the local version globally and running the build script.

Note: Replace /user/dev/nyc with the actual path to your local nyc clone.

# Go to the local clone of nyc
cd /user/dev/nyc

# Link the local clone globally
npm link

# Create the self-coverage instrumented files
node ./build-self-coverage

Use the nyc instrument command to create instrumented versions of your source files. This is useful for client-side deployment during end-to-end testing.

Syntax: nyc instrument <input> [output]

• <input>: A file or directory within the project root.
• [output]: (Optional) The directory where instrumented files will be stored. If omitted, instrumented code is sent to stdout.

Available flags:

• --delete: Removes the existing output directory before instrumentation starts.
• --in-place: Allows running the instrument command in-place.
• --complete-copy: Copies all remaining files from the input directory to the output directory (excluding .git folders). Note that this dereferences symlinks, which may affect script execution in the output directory.

nyc instrument . ./output

Install nyc as a development dependency using npm or yarn. You can use it to wrap your test scripts (e.g., mocha, ava) to generate coverage reports.

Note: If you are using jest or tap, you do not need to install nyc as they have built-in IstanbulJS support.

npm i -D nyc
# or
yarn add -D nyc

If you have multiple test runs (e.g., unit and integration tests), you can combine them into a single report.

1. Run your tests using nyc with the --no-clean flag to prevent nyc from deleting previous coverage data.
2. Use the nyc report command to generate the final combined report.

Example workflow in package.json scripts:

{
  "scripts": {
    "cover": "npm run cover:unit && npm run cover:integration && npm run cover:report",
    "cover:unit": "nyc --silent npm run test:unit",
    "cover:integration": "nyc --silent --no-clean npm run test:integration",
    "cover:report": "nyc report --reporter=lcov --reporter=text"
  }
}

If your npm test command does not already run nyc, you can generate an LCOV report and upload it to Codecov by executing nyc with the lcov reporter followed by the codecov command. This requires npm v5.2+ for npx support.

npx nyc --reporter=lcov npm test && npx codecov

If you are using a pre-instrumented codebase (rather than JIT transpilation), nyc supports inline source-maps and .map files.

Important: When using pre-instrumented code, you must set the configuration option --exclude-after-remap to false. If left as default, nyc may exclude files that source-maps remap to directories covered by your exclude rules.

To profile a specific test project (e.g., a test suite like ava), link your globally linked nyc into that project's node_modules.

Important for tap users: If using tap --coverage, tap may attempt to use its own internal version of nyc. To ensure your linked version is used, modify your package.json to call the nyc binary directly and use the --no-cov flag to disable tap's built-in coverage.

{
  "scripts" : {
    "test": "nyc tap --no-cov test/*.js"
  }
}

To send coverage reports from nyc to coveralls.io, follow these steps:

1. Install the required dependencies:

   npm install coveralls nyc --save-dev

2. Update your package.json scripts to include a coverage command that pipes the lcov report to coveralls:

   {
      "scripts": {
        "test": "nyc mocha",
        "coverage": "nyc report --reporter=text-lcov | coveralls"
      }
   }

3. If you are using a private repository, ensure you add the COVERALLS_REPO_TOKEN environment variable to your CI environment (e.g., Travis CI).

4. Configure your CI (e.g., .travis.yml) to run the coverage script after tests succeed:

   after_success: npm run coverage