Forked from SBoudrias/gulp-Istanbul - Istanbul unit test coverage plugin for gulp with the ability to register a custom Istanbul report implementation.
Works on top of any Node.js unit test framework.
npm install --save-dev gulp-istanbulIn your gulpfile.js:
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
.pipe(istanbul.enforceThresholds({ thresholds: { global: 90 } })) // Enforce a coverage of at least 90%
.on('end', cb);
});
});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);
});
});Instrument files passed in the stream.
Type: Object (optional)
{
coverageVariable: 'someVariable',
...other Instrumeter options...
}Type: String (optional)
Default: '$$cov_' + new Date().getTime() + '$$'
The global variable istanbul uses to store coverage
See also:
Type: Boolean (optional)
Default: false
Flag to include test coverage of files that aren't required by any tests
See also:
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:
See:
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
get coverage summary details
Type: Object (optional)
{
coverageVariable: 'someVariable'
}Type: String (optional)
Default: '$$cov_' + new Date().getTime() + '$$'
The global variable istanbul uses to store coverage
See also:
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:
Create the reports on stream end.
Type: Object (optional)
{
dir: './coverage',
reporters: [ 'lcov', 'json', 'text', 'text-summary', CustomReport ],
reportOpts: { dir: './coverage' },
coverageVariable: 'someVariable'
}Type: String (optional)
Default: ./coverage
The folder in which the reports are to be outputted.
Type: Array (optional)
Default: [ 'lcov', 'json', 'text', 'text-summary' ]
The list of available reporters:
clovercoberturahtmljsonlcovlcovonlynoneteamcitytexttext-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()
Type: String (optional)
Default: '$$cov_' + new Date().getTime() + '$$'
The global variable istanbul uses to store coverage
See also:
Checks coverage against minimum acceptable thresholds. Fails the build if any of the thresholds are not met.
Type: Object (optional)
{
coverageVariable: 'someVariable',
thresholds: {
global: 60,
each: -10
}
}Type: String (optional)
Default: '$$cov_' + new Date().getTime() + '$$'
The global variable istanbul uses to store coverage
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 skips 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
}
}
A plugin error in the stream if the coverage fails
MIT License (c) Simon Boudrias - 2013 - modified by John Barry
documented by jsdoc-to-markdown.
#Changelog
| Type | ID | Summary | |
|---|---|---|---|
| Version: 0.2.0 - released 2015-05-20 | |||
| Non-functional | MDGULIST-16 | Package: Update package dependencies | |
| Non-functional | MDGULIST-18 | Package: Update to v0.9.0 SBoudrias/gulp-istanbul | |
| Bug | MDGULIST-17 | Package: Fix test failure due to istanbul hookRequire() being called twice | |
| Non-functional | MDGULIST-15 | Package: Update eslint configuration, test.js runner and dev dependencies | |
| Version: 0.1.8 - released 2015-01-28 | |||
| Non-functional | MDGULIST-14 | Package: Update package dependencies | |
| Non-functional | MDGULIST-13 | Package: Update eslint configuration, test.js runner and dev dependencies | |
| Non-functional | MDGULIST-12 | Package: Migrate from jshint to eslint static code analysis | |
| Version: 0.1.7 - released 2014-10-12 | |||
| Non-functional | MDGULIST-10 | Package: Update package dependencies | |
| Non-functional | MDGULIST-9 | Package: Remove all gulp tasks except 'test' and update readme docs | |
| Version: 0.1.6 - released 2014-10-09 | |||
| Non-functional | MDGULIST-8 | Package: Fix code-coverage reporting error on readme.md | |
| Version: 0.1.5 - released 2014-10-09 | |||
| Non-functional | MDGULIST-7 | Package: Update package dependencies | |
| Version: 0.1.4 - released 2014-10-09 | |||
| Non-functional | MDGULIST-6 | Package: Update package dependencies | |
| Version: 0.1.3 - released 2014-08-28 | |||
| Non-functional | MDGULIST-5 | Package: Update dependencies. | |
| Version: 0.1.2 - released 2014-08-27 | |||
| Non-functional | MDGULIST-4 | Package: Migrate to new Cellarise Package Manager. | |
| Version: 0.1.1 - released 2014-08-20 | |||
| Feature | MDGULIST-2 | Package: Add register report function. | |
MIT License (MIT). All rights not explicitly granted in the license are reserved.
Copyright (c) 2015 John Barry
abbrev@1.0.5 - "MIT", amdefine@0.1.0 - ["BSD","MIT"], ansi-regex@1.1.1 - "MIT", ansi-styles@2.0.1 - "MIT", argparse@1.0.2 - "MIT", array-differ@1.0.0 - "MIT", array-uniq@1.0.2 - "MIT", async@0.2.10 - ["MIT"], async@0.9.2 - "MIT", beeper@1.0.0 - "MIT", camelcase-keys@1.0.0 - "MIT", camelcase@1.0.2 - "MIT", chalk@1.0.0 - "MIT", clone-stats@0.0.1 - "MIT", clone@0.2.0 - "MIT", core-util-is@1.0.1 - "MIT", dateformat@1.0.11 - "MIT", deep-is@0.1.3 - "MIT", duplexer2@0.0.2 - "BSD", escape-string-regexp@1.0.3 - "MIT", escodegen@1.6.1 - ["BSD"], esprima@1.2.5 - ["BSD"], esprima@2.1.0 - ["BSD"], esprima@2.2.0 - ["BSD"], estraverse@1.9.3 - ["BSD"], esutils@1.1.6 - ["BSD"], fast-levenshtein@1.0.6 - "MIT", fileset@0.1.5 - ["MIT"], get-stdin@4.0.1 - "MIT", glob@3.2.11 - "BSD", gulp-istanbul-custom-reports@0.0.0 - "MIT License (MIT)", gulp-util@3.0.4 - ["MIT"], handlebars@3.0.0 - "MIT", has-ansi@1.0.3 - "MIT", indent-string@1.2.1 - "MIT", inherits@2.0.1 - "ISC", is-finite@1.0.0 - "MIT", isarray@0.0.1 - "MIT", istanbul-threshold-checker@0.1.0 - "MIT", istanbul@0.3.14 - "BSD-3-Clause", js-yaml@3.3.1 - "MIT", levn@0.2.5 - ["MIT"], lodash._basecopy@3.0.0 - "MIT", lodash._basetostring@3.0.0 - "MIT", lodash._basevalues@3.0.0 - "MIT", lodash._isiterateecall@3.0.5 - "MIT", lodash._reescape@3.0.0 - "MIT", lodash._reevaluate@3.0.0 - "MIT", lodash._reinterpolate@3.0.0 - "MIT", lodash.escape@3.0.0 - "MIT", lodash.isarguments@3.0.1 - "MIT", lodash.isarray@3.0.1 - "MIT", lodash.isnative@3.0.1 - "MIT", lodash.keys@3.0.5 - "MIT", lodash.restparam@3.6.0 - "MIT", lodash.template@3.4.0 - "MIT", lodash.templatesettings@3.1.0 - "MIT", lodash@3.6.0 - "MIT", lru-cache@2.6.4 - "ISC", map-obj@1.0.0 - "MIT", meow@3.1.0 - "MIT", minimatch@0.3.0 - "MIT", minimist@0.0.10 - "MIT", minimist@0.0.8 - "MIT", minimist@1.1.1 - "MIT", mkdirp@0.5.1 - "MIT", multipipe@0.1.2 - "MIT", nopt@3.0.2 - "ISC", object-assign@2.0.0 - "MIT", once@1.3.2 - "ISC", optimist@0.3.7 - "MIT/X11", optimist@0.6.1 - "MIT/X11", optionator@0.5.0 - ["MIT"], prelude-ls@1.1.2 - ["MIT"], readable-stream@1.0.33 - "MIT", readable-stream@1.1.13 - "MIT", repeating@1.1.2 - "MIT", replace-ext@0.0.1 - ["MIT"], resolve@1.1.6 - "MIT", sigmund@1.0.0 - "BSD", source-map@0.1.43 - ["BSD"], sprintf-js@1.0.2 - "BSD-3-Clause", string_decoder@0.10.31 - "MIT", strip-ansi@2.0.1 - "MIT", supports-color@1.3.1 - "MIT", through2@0.6.5 - "MIT", type-check@0.3.1 - ["MIT"], uglify-js@2.3.6 - "MIT*", vinyl@0.4.6 - ["MIT"], which@1.0.9 - "ISC", wordwrap@0.0.3 - "MIT", wrappy@1.0.1 - "ISC", xtend@4.0.0 - ["MIT"], documented by npm-licenses.