Setting Up and Using NYC's HTML report

15 Jan 2021 Last modified at: 2021-03-09

I show how to setup and use NYC’s HTML coverage report.

We will setup and use Code Coverage reports

1. How to setup nyc for your project
2. Generating and viewing a report
   1. Windows users
   2. Everyone else
3. Understanding the reports
   1. General terms
   2. Text based terminal report
   3. HTML based report

How to setup nyc for your project

We are first going to update the .gitignore file so that git doesn’t attempt to commit the reports, which can be regenerated on demand.

1. Create and/or update your .gitignore file in the root of your project
   1. Type, on its own line, .nyc_output & coverage
2. Install NYC by running the following $ npm i --save-dev nyc
3. Update your package.json to include the following lines within the scripts section
   1. "coverage": "nyc --reporter=html --reporter=text npm test"
      1. This command presumes that mocha is run within the test script
   2. "view-nyc-report": "npm run coverage && open coverage/index.html"
      1. This will be utilized by users on mac or linux
   3. "view-nyc-win-report": "npm run coverage && start coverage/index.html"
      1. This will be utilized by users on windows machines

We separate coverage script from the view reports because there are other tools that use the reports files generated by NYC but doesn’t open the HTML report.

We should always have both the windows version and mac/linux version of the commands as we have no foresight into what Operating System of a user who runs your project

You can name the scripts whatever you please, this is my suggestion.

Now your script section should look something like

{
  "name": "example",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "mocha test",
    "coverage": "nyc --reporter=html --reporter=text npm test",
    "view-nyc-report": "npm run coverage && open coverage/index.html",
    "view-nyc-win-report": "npm run coverage && start coverage/index.html"
  },
  "devDependencies": {
    "chai": "^4.2.0",
    "mocha": "^8.2.1",
    "nyc": "^15.1.0"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Generating and viewing a report

This presumes the script names have not been changed from my suggestions. When the respective command runs, you will have two reports. A text based report in your terminal. Also the HTML report should open in your default browser.

Windows users

When you are in your project simply run npm run view-nyc-win-report

Everyone else

When you are in your project simply run npm run view-nyc-report

Understanding the reports

First, I prefer the HTML report as I can drill down into the details.

Most of this section was gathered from this Stack Overflow post

General terms

• Function (Funcs) coverage. Has each function (or subroutine) in the program been called?
• Statement (Stmts) coverage. Has each statement in the program been executed?
• Branch coverage. Has each branch (also called DD-path) of each control structure (such as in if and case statements) been executed? For example, given an if statement, have both the true and false branches been executed? Another way of saying this is, has every edge in the program been executed?
• Line coverage. has each executable line in the source file been executed?

For each case, the percentage represents executed code vs not-executed code, which equals each fraction in percent format (e.g: 50% branches, 1/2).

Text based terminal report

Uncovered lines are what needs attention if you are aiming for more coverage of the code

example report:

-----------------|---------|----------|---------|---------|-------------------
File             | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-----------------|---------|----------|---------|---------|-------------------
All files        |   95.58 |    86.08 |     100 |   97.75 |
 caesar.js       |   90.91 |       84 |     100 |      90 | 6-7
 polybius.js     |      94 |    89.66 |     100 |     100 | 20,43-52
 substitution.js |     100 |       84 |     100 |     100 | 17-23,41
-----------------|---------|----------|---------|---------|-------------------

HTML based report

I prefer this report. I can view the code by clicking on the individual file and there are keyboard shortcuts for navigating the file as indicated at the top of the webpage when looking at code.

• ‘E’ stands for ‘else path not taken’, which means that for the marked if/else statement, the ‘if’ path has been tested but not the ‘else’.
• ‘I’ stands for ‘if path not taken’, which is the opposite case: the ‘if’ hasn’t been tested.
• The xN in the left column is the amount of times that line has been executed.
• Not executed lines, or pieces of code, will be highlighted in red.

It also provides some color codes:

Pink: statements not covered.

Orange: functions not covered.

Yellow: branches not covered.