gulp-coffee-istanbul

Istanbul unit test coverage plugin for gulp, covering coffee and javascript.

Allows for in-place testing and coverage of coffee files without the need for compiling and linking to the compiled source.

Almost entirely stolen from Simon Boudrias and his gulp plugin gulp-istanbul.

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

Installation

npm install --save-dev gulp-coffee-istanbul

Example

In your gulpfile.js:

Node.js testing

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

jsFiles = ['config/**/*.js', 'controllers/**/*.js', 'models/**/*.js', 'app.js']
specFiles = ['spec/**/*.coffee']
coffeeFiles = ['src/**/*.coffee']

gulp.task 'test', ->
  gulp.src jsFiles.concat(coffeeFiles)
    .pipe istanbul({includeUntested: true}) # Covering files
    .pipe istanbul.hookRequire()
    .on 'finish', ->
      gulp.src specFiles
        .pipe mocha reporter: 'spec'
        .pipe istanbul.writeReports() # Creating the reports after tests run

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-coffee-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:

• istanbul coverageVariable
• SanboxedModule

includeUntested

Type: Boolean (optional) Default: false

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

See also:

• istanbul "0% coverage" issue

Other Istanbul Instrumenter options

See:

• istanbul Instrumenter documentation

istanbul.hookRequire()

Overwrite require so it returns the covered files.

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:

• istanbul coverageVariable
• SanboxedModule

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 utils.summarizeCoverage()

istanbul.writeReports(opt)

Create the reports on stream end.

opt

Type: Object (optional)

{
  dir: './coverage',
  reporters: [ 'lcov', 'json', 'text', 'text-summary' ],
  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

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:

• istanbul coverageVariable
• SanboxedModule

License

MIT License (c) Matt Blair - 2015