grunt-qunit-istanbul

Run QUnit unit tests in a headless PhantomJS instance with code coverage analysis provided by istanbul.

IMPORTANT

This is a fork of the grunt-contrib-qunit repo, adding the ability to generate istanbul test coverage reports. Unfortunately this cannot be handled as a seperate plugin, because it needs to hook into the grunt-contrib-qunit and grunt-lib-phantomjs structure.

This plugin should work as a drop-in replacement for your current qunit task. For any further configuration, please check out the original plugin's repo.

Getting Started

This plugin requires Grunt ~0.4.0.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile, as well as how to install and use Grunt plugins. Once you're familiar with that process, you can install this plugin with this command:

npm install grunt-qunit-istanbul --save-dev

Once the plugin has been installed, it can be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-qunit-istanbul');

QUnit task

Run this task with the grunt qunit command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

When installed by npm, this plugin will automatically download and install PhantomJS locally via the grunt-lib-phantomjs-istanbul library.

Also note that running grunt with the --debug flag will output a lot of PhantomJS-specific debugging information. This can be very helpful in seeing what actual URIs are being requested and received by PhantomJS.

OS Dependencies

This plugin uses PhantomJS to run tests. PhantomJS requires the following dependencies:

On Ubuntu/Debian

apt-get install libfontconfig1 fontconfig libfontconfig1-dev libfreetype6-dev

On CentOS

yum install fontconfig freetype

Options (Coverage object)

src

• Type: array
• Default: []

The js files you would like to end up in the coverage report.

instrumentedFiles

• Type: string

A temporary folder (that will be automatically generated and deleted after the test suite finishes) containing the instrumented source code.

htmlReport

• Type: string [optional]

A folder where the HTML reports should be stored.

coberturaReport

• Type: string [optional]

A folder where the Cobertura reports should be stored.

lcovReport

• Type: string [optional]

A folder where the LCOV reports should be stored.

cloverReport

• Type: string [optional]

A folder where the Clover reports should be stored.

baseUrl

• Type: string [optional]
• Default: .

If you're running your qunit tests with the help of a webserver, you have to point the coverage inspector to the physical path that is the base url of the qunit page you're running.

linesThresholdPct

• Type: number [optional]

Lines coverage percentage threshold to evaluate when running the build. If the actual coverage percentage is less than this value, the build will fail.

statementsThresholdPct

• Type: number [optional]

Statements coverage percentage threshold to evaluate when running the build. If the actual coverage percentage is less than this value, the build will fail.

functionsThresholdPct

• Type: number [optional]

Functions coverage percentage threshold to evaluate when running the build. If the actual coverage percentage is less than this value, the build will fail.

branchesThresholdPct

• Type: number [optional]

Branches coverage percentage threshold to evaluate when running the build. If the actual coverage percentage is less than this value, the build will fail.

disposeCollector

• Type: boolean [optional]
• Default: false

Whether or not to dispose the previous collector and create a new instance of it, discarding the info of previously instrumented files. This is useful if using grunt-qunit-istanbul as a multi task with separate targets generating separate coverage reports. If set to true for a particular target, the plugin will generate a coverage report only for the files specified in the coverage.src property, even when files used by the current target were also instrumented by a previous target. See the related bug report.

@examples

There is support for the @examples JSDoc tag to write small and wonderfully concise tests, just above your code:

/**
 * @examples
 * isInteger(5)     // true
 * isInteger(5.0)   // true
 * isInteger(-5)    // true
 * isInteger(3.14)  // false
 * isInteger('foo') // false
 * isInteger(NaN)   // false
 */
function isInteger(x) {
  return x === Math.floor(x);
}

This feature is enabled by setting the 'addJSDocExamples' option to a qunit html file. Autogenerated tests will then be added to this file. For more information have a look at jsdoc-at-examples.

Usage

qunit: {
  options: {
    '--web-security': 'no',
    coverage: {
      disposeCollector: true,
      src: ['src/js/**/*.js'],
      instrumentedFiles: 'temp/',
      htmlReport: 'report/coverage',
      coberturaReport: 'report/',
      linesThresholdPct: 85
    },
    addJSDocExamples: 'test/runexamples.html'
  },
  all: ['test/**/*.html']
}

Original Task by "Cowboy" Ben Alman

Modified by asciidisco