gulp-istanbul-plus v0.10.3
gulp-istanbul
Difference in this project
There's no way in gulp-istanbul
, istanbul
or isparta
to ignore certain includes, for example if you are
doing the following gulp-istanbul
will fail:
import './my-style.scss';
// or
import './my-style.css';
The above is often seen for people using webpack
to transpile their code.
This branch of SBoudria's awesome work is the same only it adds
an additional option called skipImports
as seen below:
istanbul({
// skip both scss and css files
skipImports: /\.(scss|css)$/
})
A pull request was requested to the main package, but after a discussion it was agreed that this is a bit of a work around, and not really under the scope of gulp-stanbul.
However the need still remains so it was branched into this repository where this fix (and potentially others in the future) can live.
In the future I'm sure a more long term solution will become available for projects that use css includes.
For more information on this feature please see the pull request discussion at: https://github.com/SBoudrias/gulp-istanbul/pull/68
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 ran
.pipe(istanbul.enforceThresholds({ thresholds: { global: 90 } })) // Enforce a coverage of at least 90%
.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 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 require
d 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'
}
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