Wondering what’s next for npm?Check out our public roadmap! »

    gulp-istanbul
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/gulp-istanbul package

    1.1.3 • Public • Published

    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 in this example, but any test framework will work
    var mocha = require('gulp-mocha');
     
    gulp.task('pre-test', function () {
      return gulp.src(['lib/**/*.js'])
        // Covering files
        .pipe(istanbul())
        // Force `require` to return covered files
        .pipe(istanbul.hookRequire());
    });
     
    gulp.task('test', ['pre-test'], function () {
      return gulp.src(['test/*.js'])
        .pipe(mocha())
        // Creating the reports after tests ran
        .pipe(istanbul.writeReports())
        // Enforce a coverage of at least 90%
        .pipe(istanbul.enforceThresholds({ thresholds: { global: 90 } }));
    });

    Note: Version 4.x.x of gulp-mocha is not supported (see issue #115 for details). In this example, you should use gulp-mocha version 3.0.1 for the time being.

    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('pre-test', function () {
      return gulp.src(['lib/**/*.js'])
        // Covering files
        .pipe(istanbul())
        // Write the covered files to a temporary directory
        .pipe(gulp.dest('test-tmp/'));
    });
     
    gulp.task('test', ['pre-test'], function () {
      // Make sure your tests files are requiring files from the
      // test-tmp/ directory
      return gulp.src(['test/*.js'])
        .pipe(testFramework())
        // Creating the reports after tests ran
        .pipe(istanbul.writeReports());
    });

    Source Maps

    gulp-istanbul supports gulp-sourcemaps when instrumenting:

    gulp.task('pre-test', function () {
      return gulp.src(['lib/**/*.js'])
        // optionally load existing source maps
        .pipe(sourcemaps.init())
        // Covering files
        .pipe(istanbul())
        .pipe(sourcemaps.write('.'))
        // Write the covered files to a temporary directory
        .pipe(gulp.dest('test-tmp/'));
    });

    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({
        // supports es6
        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'
    }

    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()

    reportOpts

    Type: Object (optional)

    {
      dir: './coverage'
    }

    You can also configure separate directory for each report.

    {
      html: {
            dir: './coverage/html',
            watermarks: {
                statements: [ 50, 80 ],
                lines: [ 50, 80 ],
                functions: [ 50, 80],
                branches: [ 50, 80 ]
            }
        },
        lcov: {dir: './coverage/lcov'},
        lcovonly: {dir: './coverage/lcovonly'},
        json: {dir: './coverage/json'},
    }

    watermarks can be used to confgure the color of the HTML report. Default colors are.. RED: below 50% coverage, YELLOW: 50-80% coverage, GREEN: above 80%

    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

    Install

    npm i gulp-istanbul

    DownloadsWeekly Downloads

    22,543

    Version

    1.1.3

    License

    MIT

    Last publish

    Collaborators

    • avatar