Learn Istanbul

Learn how to use Istanbul to check/track Code Coverage in your JavaScript projects.

---

Why?

Like the road sign that is "Not In Use" too much code being written never gets executed.

There are a few obvious issues with this:

1. if un-tested code remains in the codebase it can contain unknown behaviour e.g. bugs.
2. untested features are more difficult to maintain without introducing breaking changes.
3. un-tested code can clutter a project and accumulates technical debt that wastes time.

What?

Code coverage tells you when code you have written is being executed so you can decide if un-covered lines are superfluous (and can be removed) or require additional testing.

The rest of this page will focus on practical usage example, so if you are completely new to Code Coverage we recommend you read the wikipedia article: http://en.wikipedia.org/wiki/Code_coverage first.

Istanbul is a code coverage analysis script you run when executing your unit tests: https://github.com/gotwarlost/istanbul/ we like it because it's simple and prints out nice html reports (see below)

How?

Installation

We prefer to install istanbul as a "devDependencies" in each of our projects:

npm install istanbul --save-dev

to check if the installation worked, (copy-paste and) run the following command in your terminal:

node_modules/.bin/istanbul help

Simple Example

For our first example create a file called test.js.

vi test.js

type (or copy-paste) the following code in the test.js file:

x = 42;
if(false)
     x =-1;

Now run the istanbul command to generate a coverage report:

node ./node_modules/.bin/istanbul cover test.js

Alternatively you can insert the line

"coverage": "node ./node_modules/.bin/istanbul cover test.js"

into the scripts section of your package.json and run

npm run coverage

This will create a directory in your project called coverage where you will find the generated coverage reports. In our case: learn-istanbul/coverage/lcov-report/learning-istanbul/test1.js.html If you open the test1.js**.html** file in your browser you will see a visual coverage report:

Istanbul gives us four code coverage metrics:

• Statements: How many of the statements in you code are executed.
• Branches: Conditional statements create branches of code which may not be executed (e.g. if/else). This metric tells you how many of your branches have been executed.
• Functions: The proportion of the functions you have defined which have been called.
• Lines: The proportion of lines of code which have been executed.

when you click test.js to view the coverage for the file you see:

Two things to note in the example above:

• we only get 66.67% coverage because the only 2/3 of the code is being run
• the 3rd line never gets executed because false is always false!

This may be a trivial example but it shows exactly where the useless code is.

A more "Real World" Example

Try executing the mischief.js file by running npm test:

What is wrong with the following picture?

There are plenty of developers/organisations that can only dream about getting 96% code coverage! and yet when we inspect the detail, there's something big slipping through the net!

We have 100% functional code coverage, but only 50% "Branch" Coverage. This means one or more conditional execution branches is not being executed.

Most of the time it will be something innocuous but what if a disgruntled person slipped in something like:

if(employee.status === 'terminated' && employee.left - today() > 90) {
    selfDestuct();
}

The 97% Coverage is not looking so hot anymore ...

What if we add a Test that follows the branch containing the rogue code? We reach our mythical 100% Coverage:

And if we simply allow this code to be promoted without further checks, the rogue code will be in production and soon forgotten.

The solution here is to not rely (solely) on tools such as Istanbul to check code. Its essential would advocate a separation between the people writing the tests and the developers who write the code.

And there is still no substitute for Code Review!

Notes

• Ariay's basic tutorial: http://ariya.ofilabs.com/2012/12/javascript-code-coverage-with-istanbul.html
• Jasmine Test Coverage: http://architects.dzone.com/articles/code-coverage-jasmine-tests

Istanbul (the JavaScript Code Coverage tool) https://github.com/gotwarlost/istanbul should not to be confused with istanbul the desktop screen recorder, they are totally diferent animals! Shame about the name collision... :-(