Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Istanbul unit test coverage plugin for gulp.
JavaScript
branch: master

Merge pull request #53 from peterjwest/master

Added support for custom reporters
latest commit c53ece227b
@SBoudrias authored

README.md

gulp-istanbul NPM version Build Status Dependency Status

Istanbul unit test coverage plugin for gulp.

Works on top of any Node.js unit test framework.

Installation

npm install --save-dev gulp-istanbul

Example

In your gulpfile.js:

Node.js testing

var istanbul = require('gulp-istanbul');
// We'll use mocha here, but any test framework will work
var mocha = require('gulp-mocha');

gulp.task('test', function (cb) {
  gulp.src(['lib/**/*.js', 'main.js'])
    .pipe(istanbul()) // Covering files
    .pipe(istanbul.hookRequire()) // Force `require` to return covered files
    .on('finish', function () {
      gulp.src(['test/*.js'])
        .pipe(mocha())
        .pipe(istanbul.writeReports()) // Creating the reports after tests runned
        .on('end', cb);
    });
});

Browser testing

For browser testing, you'll need to write the files covered by istanbul in a directory from where you'll serve these files to the browser running the test. You'll also need a way to extract the value of the coverage variable after the test have runned in the browser.

Browser testing is hard. If you're not sure what to do, then I suggest you take a look at Karma test runner - it has built-in coverage using Istanbul.

var istanbul = require('gulp-istanbul');

gulp.task('test', function (cb) {
  gulp.src(['lib/**/*.js', 'main.js'])
  .pipe(istanbul()) // Covering files
  .pipe(gulp.dest('test-tmp/'))
  .on('finish', function () {
    gulp.src(['test/*.html'])
    .pipe(testFramework())
    .pipe(istanbul.writeReports()) // Creating the reports after tests runned
    .on('end', cb);
  });
});

API

istanbul(opt)

Instrument files passed in the stream.

opt

Type: Object (optional)

{
  coverageVariable: 'someVariable',
  ...other Instrumeter options...
}
coverageVariable

Type: String (optional) Default: '$$cov_' + new Date().getTime() + '$$'

The global variable istanbul uses to store coverage

See also:

includeUntested

Type: Boolean (optional) Default: false

Flag to include test coverage of files that aren't required by any tests

See also:

instrumenter

Type: Instrumenter (optional) Default: istanbul.Instrumenter

Custom Instrumenter to be used instead of the default istanbul one.

var isparta = require('isparta');
var istanbul = require('gulp-istanbul');

gulp.src('lib/**.js')
  .pipe(istanbul({
    instrumenter: isparta.Instrumenter
  }));

See also:

Other Istanbul Instrumenter options

See:

istanbul.hookRequire()

Overwrite require so it returns the covered files. The method take an optional option object.

Always use this option if you're running tests in Node.js

istanbul.summarizeCoverage(opt)

get coverage summary details

opt

Type: Object (optional)

{
  coverageVariable: 'someVariable'
}
coverageVariable

Type: String (optional) Default: '$$cov_' + new Date().getTime() + '$$'

The global variable istanbul uses to store coverage

See also:

returns

Type: Object

{
  lines: { total: 4, covered: 2, skipped: 0, pct: 50 },
  statements: { total: 4, covered: 2, skipped: 0, pct: 50 },
  functions: { total: 2, covered: 0, skipped: 0, pct: 0 },
  branches: { total: 0, covered: 0, skipped: 0, pct: 100 }
}

See also:

istanbul.writeReports(opt)

Create the reports on stream end.

opt

Type: Object (optional)

{
  dir: './coverage',
  reporters: [ 'lcov', 'json', 'text', 'text-summary', CustomReport ],
  reportOpts: { dir: './coverage' },
  coverageVariable: 'someVariable'
}

dir

Type: String (optional) Default: ./coverage

The folder in which the reports are to be outputted.

reporters

Type: Array (optional) Default: [ 'lcov', 'json', 'text', 'text-summary' ]

The list of available reporters:

  • clover
  • cobertura
  • html
  • json
  • lcov
  • lcovonly
  • none
  • teamcity
  • text
  • text-summary

You can also specify one or more custom reporter objects as items in the array. These will be automatically registered with istanbul.

See also require('istanbul').Report.getReportList()

coverageVariable

Type: String (optional) Default: '$$cov_' + new Date().getTime() + '$$'

The global variable istanbul uses to store coverage

See also:

License

MIT License (c) Simon Boudrias - 2013

Something went wrong with that request. Please try again.