April 24 2015

How to add an Istanbul code coverage badge to your GitHub repository

Badges on GitHub are great. They give potential users an idea of how well maintained a project is. Are there automated tests? Are they all passing? How much of the code is covered by tests? Are the project's dependencies up-to-date?

If you want to add a code coverage badge to your GitHub repository, you can use a service called Coveralls. Coveralls provides code coverage history and statistics and, like Travis CI and GitHub, it's free for open source projects.

Step 1: Sign up with Coveralls and activate your repository

You can easily get started with Coveralls by signing up through your GitHub account. Once you've signed up, activate your repository on the Coveralls site.

Step 2: Sign up with Travis CI and activate your repository

If you don't already have a Travis CI account, sign up for one and activate the GitHub repository you will be using.

Step 3: Install the node dependencies

Assuming you are using Istanbul and Mocha for code coverage and testing, install the following dependencies:

$ npm i istanbul mocha coveralls -D

Step 4: Configure the scripts property in your package.json

You can use two scripts to do testing and code coverage reporting:

npm test: Use this during development to quickly run all tests and get a code coverage report.
npm run coverage: Travis CI will run this after the tests to report code coverage to Coveralls. This script will not work locally without setting up a .coveralls.yml file. Here is some more information on that.

This is my package.json's scripts property:

JSON

"scripts": {
  "test": "./node_modules/istanbul/lib/cli.js cover ./node_modules/.bin/_mocha",
  "coveralls": "cat ./coverage/lcov.info | ./node_modules/.bin/coveralls"
},

Step 5: Configure Travis CI's .travis.yml file

We need to tell Travis CI what language our project is built with and that it should run our coveralls script after every successful build:

YAML

language: node_js
node_js:
    - iojs
after_success: 'npm run coveralls'

Step 6: Add the coverage badge to your readme.md

The format for your badge is as follows. Don't forgt to replace <account> and <repository> with your own:

MARKDOWN

[![Coverage Status](https://coveralls.io/repos/<account>/<repository>/badge.svg?branch=master)](https://coveralls.io/r/<account>/<repository>?branch=master)

Done

Now, just git commit and push everything and your project's GitHub repository will look a lot more professional. To find more badges to add to your repository, check out shields.io.