# gulp-istanbul

> Istanbul unit test coverage plugin for gulp.

Latest version **1.1.3** (published 2018-01-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-istanbul
pnpm add gulp-istanbul
yarn add gulp-istanbul
bun add gulp-istanbul
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.3 |
| Published | 2018-01-02 |
| First published | 2013-12-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/gulp-istanbul) |
| Module format | CommonJS |
| Dependencies | 6 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 186 |
| Author | Simon Boudrias |
| Maintainers | sboudrias |
| Keywords | gulpplugin, coverage, istanbul, unit test |

## Links

- npm: https://www.npmjs.com/package/gulp-istanbul
- Repository: https://github.com/SBoudrias/gulp-istanbul
- Issues: https://github.com/SBoudrias/gulp-istanbul/issues
- npm.io page: https://npm.io/package/gulp-istanbul

## Dependencies (6)

- [lodash](https://npm.io/package/lodash.md) ^4.0.0
- [istanbul](https://npm.io/package/istanbul.md) ^0.4.0
- [through2](https://npm.io/package/through2.md) ^2.0.0
- [plugin-error](https://npm.io/package/plugin-error.md) ^0.1.2
- [vinyl-sourcemaps-apply](https://npm.io/package/vinyl-sourcemaps-apply.md) ^0.2.1
- [istanbul-threshold-checker](https://npm.io/package/istanbul-threshold-checker.md) ^0.2.1

## Recent versions

- 1.1.3 (latest) — 2018-01-02
- 1.1.2 — 2017-06-07
- 1.1.1 — 2016-08-25
- 1.1.0 — 2016-08-15
- 1.0.0 — 2016-06-10
- 0.10.4 — 2016-04-05
- 0.10.3 — 2015-11-23
- 0.10.2 — 2015-10-18
- 0.10.1 — 2015-09-27
- 0.10.0 — 2015-06-07
- 0.9.0 — 2015-05-07
- 0.8.1 — 2015-04-05
- 0.8.0 — 2015-04-05
- 0.7.0 — 2015-03-24
- 0.6.0 — 2015-02-01
- … 9 more at https://npm.io/package/gulp-istanbul/versions

## README

gulp-istanbul [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][depstat-image]][depstat-url]
===========================

[Istanbul][istanbul] unit test coverage plugin for [gulp][gulp].

Works on top of any Node.js unit test framework.

Installation
---------------

```shell
npm install --save-dev gulp-istanbul
```

Example
---------------

In your `gulpfile.js`:

#### Node.js testing

```javascript
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](https://github.com/SBoudrias/gulp-istanbul/issues/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](#coveragevariable) 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](http://karma-runner.github.io) - it has built-in coverage using Istanbul.


```javascript
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][gulp-sourcemaps] when instrumenting:


```javascript
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)
```js
{
  coverageVariable: 'someVariable',
  ...other Instrumeter options...
}
```

##### coverageVariable
Type: `String` (optional)
Default: `'$$cov_' + new Date().getTime() + '$$'`

The global variable istanbul uses to store coverage

See also:
- [istanbul coverageVariable][istanbul-coverage-variable]
- [SanboxedModule][sandboxed-module-coverage-variable]

##### includeUntested
Type: `Boolean` (optional)
Default: `false`

Flag to include test coverage of files that aren't `require`d by any tests

See also:
- [istanbul "0% coverage" issue](https://github.com/gotwarlost/istanbul/issues/112)

##### instrumenter
Type: `Instrumenter` (optional)
Default: `istanbul.Instrumenter`

Custom Instrumenter to be used instead of the default istanbul one.

```js
var isparta = require('isparta');
var istanbul = require('gulp-istanbul');

gulp.src('lib/**.js')
  .pipe(istanbul({
    // supports es6
    instrumenter: isparta.Instrumenter
  }));
```

See also:
- [isparta](https://github.com/douglasduteil/isparta)

##### Other Istanbul Instrumenter options

See:
- [istanbul Instrumenter documentation][istanbul-coverage-variable]

### istanbul.hookRequire()

Overwrite `require` so it returns the covered files. The method take an optional [option object](https://gotwarlost.github.io/istanbul/public/apidocs/classes/Hook.html#method_hookRequire).

Always use this option if you're running tests in Node.js

### istanbul.summarizeCoverage(opt)

get coverage summary details

#### opt
Type: `Object` (optional)
```js
{
  coverageVariable: 'someVariable'
}
```
##### coverageVariable
Type: `String` (optional)
Default: `'$$cov_' + new Date().getTime() + '$$'`

The global variable istanbul uses to store coverage

See also:
- [istanbul coverageVariable][istanbul-coverage-variable]
- [SanboxedModule][sandboxed-module-coverage-variable]

#### returns
Type: `Object`
```js
{
  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 utils.summarizeCoverage()][istanbul-summarize-coverage]


### istanbul.writeReports(opt)

Create the reports on stream end.

#### opt
Type: `Object` (optional)
```js
{
  dir: './coverage',
  reporters: [ 'lcov', 'json', 'text', 'text-summary', CustomReport ],
  reportOpts: { dir: './coverage' },
  coverageVariable: 'someVariable'
}
```

You can pass individual configuration to a reporter.
```js
{
  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)
```js
{
  dir: './coverage'
}
```

You can also configure separate directory for each report.
```js
{
  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 coverageVariable][istanbul-coverage-variable]
- [SanboxedModule][sandboxed-module-coverage-variable]


### istanbul.enforceThresholds(opt)

Checks coverage against minimum acceptable thresholds. Fails the build if any of the thresholds are not met.

#### opt
Type: `Object` (optional)
```js
{
  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](http://en.wikipedia.org/wiki/MIT_License) (c) Simon Boudrias - 2013

[istanbul]: http://gotwarlost.github.io/istanbul/
[gulp]: https://github.com/gulpjs/gulp
[gulp-sourcemaps]: https://github.com/floridoo/gulp-sourcemaps

[npm-url]: https://npmjs.org/package/gulp-istanbul
[npm-image]: https://badge.fury.io/js/gulp-istanbul.svg

[travis-url]: http://travis-ci.org/SBoudrias/gulp-istanbul
[travis-image]: https://secure.travis-ci.org/SBoudrias/gulp-istanbul.svg?branch=master

[depstat-url]: https://david-dm.org/SBoudrias/gulp-istanbul
[depstat-image]: https://david-dm.org/SBoudrias/gulp-istanbul.svg

[istanbul-coverage-variable]: http://gotwarlost.github.io/istanbul/public/apidocs/classes/Instrumenter.html
[istanbul-summarize-coverage]: http://gotwarlost.github.io/istanbul/public/apidocs/classes/ObjectUtils.html#method_summarizeCoverage
[sandboxed-module-coverage-variable]: https://github.com/felixge/node-sandboxed-module/blob/master/lib/sandboxed_module.js#L240

---
_Source: https://npm.io/package/gulp-istanbul · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._