gulp-babel-istanbul

Babel + Istanbul unit test coverage plugin for gulp.

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
gulp-babel-istanbul
621.6.07 years ago9 years agoMinified + gzip package size for gulp-babel-istanbul in KB

Popular Searches

Readme

gulp-babel-istanbul
!NPM Versionnpm-imagenpm-url !NPM Downloadsdownloads-imagedownloads-url !Depsdavid-imagedavid-url !Dev Depsdavid-dev-imagedavid-dev-url
Babelbabel ES2015 transpiling and Istanbulistanbul unit test coverage plugin for gulpgulp.
Works on top of any Node.js unit test framework.

Installation

npm install gulp-babel-istanbul --save-dev

Example

In your gulpfile.js:

Node.js testing

The following example is a sort of "kitchen sink" example of how to use gulp-babel-istanbul.
var babel = require('gulp-babel');
var istanbul = require('gulp-babel-istanbul');
var injectModules = require('gulp-inject-modules');
var mocha = require('gulp-mocha');

gulp.task('coverage', function (cb) {
  gulp.src('src/**/*.js')
  .pipe(istanbul())
  .pipe(istanbul.hookRequire()) // or you could use .pipe(injectModules())
  .on('finish', function () {
    gulp.src('test/**/*.js')
    .pipe(babel())
    .pipe(injectModules())
    .pipe(mocha())
    .pipe(istanbul.writeReports())
    .pipe(istanbul.enforceThresholds({ thresholds: { global: 90 } }))
    .on('end', cb);
  });
});

Browser testing

WARNING: Browser testing is untested and may or may not work :(

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-babel-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 ran
        .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-babel-istanbul');

gulp.src('lib/**.js')
  .pipe(istanbul({
    instrumenter: isparta.Instrumenter
  }));
NOTE: I don't think you need to use isparta since we use babel-istanbulbabel-istanbul.
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'
}

You can pass individual configuration to a reporter. 
{
  dir: './coverage',
  reporters: [ 'lcovonly', 'json', 'text', 'text-summary', CustomReport ],
  reportOpts: {
    lcov: {dir: 'lcovonly', file: 'lcov.info'}
    json: {dir: 'json', file: 'converage.json'}
  },
  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:

istanbul.enforceThresholds(opt)

Checks coverage against minimum acceptable thresholds. Fails the build if any of the thresholds are not met.

opt

Type: Object (optional) 
{
  coverageVariable: 'someVariable',
  thresholds: {
    global: 60,
    each: -10
  }
}
coverageVariable
Type: String (optional) Default: '$$cov_' + new Date().getTime() + '$$'
The global variable istanbul uses to store coverage
thresholds
Type: Object (required)
Minimum acceptable coverage thresholds. Any coverage values lower than the specified threshold will fail the build.
Each threshold value can be:
  • A positive number - used as a percentage
  • A negative number - used as the maximum amount of coverage gaps
  • A falsey value will skip the coverage

Thresholds can be specified across all files (global) or per file (each): 
{
  global: 80,
  each: 60
}

You can also specify a value for each metric: 
{
  global: {
    statements: 80,
    branches: 90,
    lines: 70,
    functions: -10
  }
  each: {
    statements: 100,
    branches: 70,
    lines: -20
  }
}

emits

A plugin error in the stream if the coverage fails

License

MIT License (c) Simon Boudrias - 2013