Istanbul Reporter Shields.io Badge

Built for developers out there who do not want to (or cannot) rely on (and/or use) third-party services like http://codecov.io/ or http://coveralls.io/.

Generates a shields.io url representing the coverage of your tests suit. Also generates the markdown equivalent code. More importantly, it updates automatically your README.md file with the generated markdown each time you are running your tests.

Project Health

Install

npm install --save-dev istanbul-reporter-shield-badge

Usage

Register the report using the istanbul Report factory:

var shieldBadgeReporter = require('istanbul-reporter-shield-badge');
var istanbul = require('istanbul');
istanbul.Report.register(shieldBadgeReporter);

Create a report after istanbul has collected coverage information:

var report = require('istanbul').Report.create('shield-badge');

Add to your karma config file:

config.set({
    reporters: ['coverage'],
    coverageReporter: {
      dir: './coverage',
      reporters: [
        { type: 'lcov', subdir: '.' },
        { type: 'text-summary' },
        { type: function() {
          var shieldBadgeReporter = require('istanbul-reporter-shield-badge')
          var istanbul = require('istanbul')
          istanbul.Report.register(shieldBadgeReporter)
          return 'shield-badge'
        }(), subdir: '.' }
      ]
    }
  })

Config options

|name |default |description | |--------------|-------------------------|----------------------------------------------------------------------------------------------------------------------------------| |file |coverage.shield.badge.md |the file where the url of the badge will be generated | |subject |coverage |the text that will appear on the left of the shield badge; cannot contain the character ']' (closed bracket) | |range |[50, 80] |must be a JavaScript Array representing medium and high levels of coverage | |coverageType |lines |must be one of: statements, lines, branches, functions; will be used to display the coverage percentage of the chosen type | |readmeFilename|null |the name of your readme file; MUST BE readme.md (only) in any case | |readmeDir |null |the absolute path of the folder where is located your readme.md file |

N.b: if you supply the readmeFilename configuration, the reporter will add the markdown of the badge into your Readme.md file at the very beginning of the file. Once added, you are free to move the markdown code anywhere within the Readme.md file and the next time the reporter will run, it will automatically replace the previous badge with the new generated one.

Standalone Usage Example

Please refer to the sample script.

It was used in the package.json file as the 'npm test script' as follows:

istanbul cover _mocha test && node update-readme-with-shield-badge.js

Karma Configuration File Example

config.set({
    reporters: ['coverage'],
    coverageReporter: {
      dir: './coverage',
      reporters: [
        { type: 'lcov', subdir: '.' },
        { type: 'text-summary' },
        { type: function() {
                  var shieldBadgeReporter = require('istanbul-reporter-shield-badge')
                  var istanbul = require('istanbul')
                  istanbul.Report.register(shieldBadgeReporter)
                  return 'shield-badge'
                }(),
          subdir: '.',
          coverageType: 'statements',
          range: [75, 90],
          subject: 'Code Coverage', 
          readmeFilename: 'README.md',
          readmeDir: path.resolve(__dirname, '../..') // i.e. if karma.conf.js is located in test/unit from the root folder of your project
        }
      ]
    }
  })

The example above will generate the following shields.io badge for a coverage percentage of 88% at the statements level:

It will also include it in the README.md file located at the root of your project.

LICENSE

MIT License

Copyright (c) 2017

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.