{"id":13273,"library":"gulp-istanbul","title":"Gulp Istanbul Coverage Plugin","description":"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.","status":"maintenance","version":"1.1.3","language":"javascript","source_language":"en","source_url":"git://github.com/SBoudrias/gulp-istanbul","tags":["javascript","gulpplugin","coverage","istanbul","unit test"],"install":[{"cmd":"npm install gulp-istanbul","lang":"bash","label":"npm"},{"cmd":"yarn add gulp-istanbul","lang":"bash","label":"yarn"},{"cmd":"pnpm add gulp-istanbul","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for any Gulp plugin to function within a Gulp task runner environment.","package":"gulp","optional":false},{"reason":"Core dependency providing the underlying code instrumentation and reporting capabilities.","package":"istanbul","optional":false},{"reason":"Optional instrumenter for supporting ES6/ES2015+ syntax.","package":"isparta","optional":true}],"imports":[{"note":"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.","wrong":"const { istanbul } = require('gulp-istanbul')","symbol":"istanbul","correct":"import istanbul from 'gulp-istanbul'"},{"note":"Used to force `require` to return covered files in Node.js testing setups. This is accessed as a property of the main `istanbul` export.","symbol":"istanbul.hookRequire","correct":"const istanbul = require('gulp-istanbul');\nistanbul.hookRequire();"},{"note":"Generates the coverage reports (e.g., HTML, LCOV) after tests have been executed. It is a method on the `istanbul` object.","symbol":"istanbul.writeReports","correct":"const istanbul = require('gulp-istanbul');\nistanbul.writeReports();"},{"note":"Enforces minimum coverage percentages and fails the Gulp task if thresholds are not met. This is typically the last step in a coverage task.","symbol":"istanbul.enforceThresholds","correct":"const istanbul = require('gulp-istanbul');\nistanbul.enforceThresholds({ thresholds: { global: 90 } });"}],"quickstart":{"code":"const gulp = require('gulp');\nconst istanbul = require('gulp-istanbul');\nconst mocha = require('gulp-mocha');\n\n// Ensure gulp-mocha is at a compatible version, e.g., 3.0.1 for this example\n\ngulp.task('pre-test', function () {\n  return gulp.src(['lib/**/*.js'])\n    // Instrumenting files with Istanbul\n    .pipe(istanbul({\n      // Optional: use isparta for ES6+ support if needed\n      // instrumenter: require('isparta').Instrumenter\n    }))\n    // Force `require` to return instrumented files for coverage collection\n    .pipe(istanbul.hookRequire());\n});\n\ngulp.task('test', ['pre-test'], function () {\n  return gulp.src(['test/*.js'])\n    .pipe(mocha())\n    // Creating the coverage reports after tests complete\n    .pipe(istanbul.writeReports({\n      // Optional: Configure reporters\n      // reporters: ['lcov', 'text', 'text-summary'],\n      // reportOpts: { dir: './coverage' }\n    }))\n    // Enforce a global coverage threshold of at least 90%\n    .pipe(istanbul.enforceThresholds({ thresholds: { global: 90 } }));\n});\n\ngulp.task('default', ['test']);","lang":"javascript","description":"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."},"warnings":[{"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.","message":"`gulp-mocha` version 4.x.x and above is explicitly not supported by `gulp-istanbul`, leading to potential test failures or incorrect coverage reporting.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"`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`).","severity":"deprecated","affected_versions":">=1.1.3"},{"fix":"If targeting browser environments, leverage test runners designed for browsers (e.g., Karma) that provide seamless integration with Istanbul for coverage reporting.","message":"Achieving 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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"By 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"`gulp-istanbul` without a specific instrumenter might not correctly parse modern JavaScript syntax (e.g., ES6 arrow functions).","error":"Error: Line X: Unexpected token =>"},{"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.","cause":"The `istanbul.enforceThresholds` task fails because the actual code coverage percentages fall below the configured minimums.","error":"Coverage threshold not met. Global coverage: { 'statements': X%, 'branches': Y%, 'functions': Z%, 'lines': A% }"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}