Registry / testing / gulp-istanbul

gulp-istanbul

JSON →
library1.1.3jsnpmunverified

gulp-istanbul is a Gulp plugin that integrates Istanbul, a JavaScript code coverage tool, into a Gulp build workflow. It enables developers to instrument their source code, execute unit tests, and generate detailed coverage reports, with the option to enforce coverage thresholds. The package is currently at version 1.1.3, with its last release in mid-2017. Due to its age and the evolution of both Gulp (which has moved to Gulp 4 and beyond) and code coverage tools (with `nyc` becoming the successor to standalone Istanbul), this package is primarily in maintenance mode and is not actively developed. Its core functionality offers straightforward integration for existing Gulp 3/4 projects and includes support for sourcemaps during code instrumentation.

testingdevops
npm install gulp-istanbul
github ↗package ↗
INSTALL
IMPORT
SIG · GULP-ISTANBUL
G
gulp-istanbul
testingjavascriptv1.1.3
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

istanbul
✓ import istanbul from 'gulp-istanbul'
✗ const { istanbul } = require('gulp-istanbul')
The `require` statement typically assigns the entire module export, which is the instrumenter function, to the `istanbul` variable. Subsequent methods are properties of this function. For ESM, the default import captures this.
istanbul.hookRequire
✓ const istanbul = require('gulp-istanbul'); istanbul.hookRequire();
Used to force `require` to return covered files in Node.js testing setups. This is accessed as a property of the main `istanbul` export.
istanbul.writeReports
✓ const istanbul = require('gulp-istanbul'); istanbul.writeReports();
Generates the coverage reports (e.g., HTML, LCOV) after tests have been executed. It is a method on the `istanbul` object.
istanbul.enforceThresholds
✓ const istanbul = require('gulp-istanbul'); istanbul.enforceThresholds({ thresholds: { global: 90 } });
Enforces minimum coverage percentages and fails the Gulp task if thresholds are not met. This is typically the last step in a coverage task.

This quickstart defines Gulp tasks to instrument source code, run Mocha tests, generate Istanbul coverage reports, and enforce a minimum 90% global code coverage threshold.

const gulp = require('gulp'); const istanbul = require('gulp-istanbul'); const mocha = require('gulp-mocha'); // Ensure gulp-mocha is at a compatible version, e.g., 3.0.1 for this example gulp.task('pre-test', function () { return gulp.src(['lib/**/*.js']) // Instrumenting files with Istanbul .pipe(istanbul({ // Optional: use isparta for ES6+ support if needed // instrumenter: require('isparta').Instrumenter })) // Force `require` to return instrumented files for coverage collection .pipe(istanbul.hookRequire()); }); gulp.task('test', ['pre-test'], function () { return gulp.src(['test/*.js']) .pipe(mocha()) // Creating the coverage reports after tests complete .pipe(istanbul.writeReports({ // Optional: Configure reporters // reporters: ['lcov', 'text', 'text-summary'], // reportOpts: { dir: './coverage' } })) // Enforce a global coverage threshold of at least 90% .pipe(istanbul.enforceThresholds({ thresholds: { global: 90 } })); }); gulp.task('default', ['test']);
Debug
Known issues
breaking`gulp-mocha` version 4.x.x and above is explicitly not supported by `gulp-istanbul`, leading to potential test failures or incorrect coverage reporting.
fix
Downgrade `gulp-mocha` to a compatible version, such as 3.0.1, if you must use `gulp-istanbul`. Consider migrating to `nyc` for modern coverage workflows.
affects: >=4.0.0
deprecated`gulp-istanbul` has not been actively maintained since its last release in 2017. This means it may not support newer Node.js versions, modern JavaScript syntax (without `isparta`), or the latest features of the Istanbul core library (which has transitioned to `nyc`).
fix
For new projects or projects requiring modern JavaScript support and active maintenance, consider migrating to `nyc` (the current Istanbul command-line client) directly or using integrated solutions in test runners like Jest.
affects: >=1.1.3
gotchaAchieving code coverage for browser-based tests with `gulp-istanbul` can be complex. The documentation explicitly advises users to consider dedicated browser test runners like Karma, which have built-in Istanbul coverage capabilities.
fix
If targeting browser environments, leverage test runners designed for browsers (e.g., Karma) that provide seamless integration with Istanbul for coverage reporting.
affects: *
gotchaBy default, `gulp-istanbul` (and older Istanbul versions) might only report coverage for files that are `require`d during tests. This can lead to '0% coverage' for files that exist but are not executed.
fix
Set the `includeUntested` option to `true` when calling `istanbul()` to ensure all files are included in the coverage report, regardless of whether they were executed by tests.
affects: *
Errors
Common errors & fixes
Error: Line X: Unexpected token =>
`gulp-istanbul` without a specific instrumenter might not correctly parse modern JavaScript syntax (e.g., ES6 arrow functions).
fix
Pass an ES6-compatible instrumenter, such as `isparta.Instrumenter`, to the `istanbul()` plugin options: `.pipe(istanbul({ instrumenter: require('isparta').Instrumenter }))`. Ensure `isparta` is installed.
Coverage threshold not met. Global coverage: { 'statements': X%, 'branches': Y%, 'functions': Z%, 'lines': A% }
The `istanbul.enforceThresholds` task fails because the actual code coverage percentages fall below the configured minimums.
fix
Either increase your test coverage to meet the specified thresholds or adjust the `thresholds` option in `istanbul.enforceThresholds` to acceptable levels. Ensure all relevant files are being instrumented and tested.
Upgrade
Version history
1.1.3latest on npm
Audit
Dependencies
gulprequiredPeer dependency for any Gulp plugin to function within a Gulp task runner environment.
istanbulrequiredCore dependency providing the underlying code instrumentation and reporting capabilities.
ispartaoptionalOptional instrumenter for supporting ES6/ES2015+ syntax.
Agent activity
7 hits · last 30 days
node
6
Amazon
1
Resources
githubhttps://github.com/SBoudrias/gulp-istanbul ↗
packagehttps://www.npmjs.com/package/gulp-istanbul ↗
gulp-istanbul — npm install gulp-istanbul · libregistry