• Stars
    star
    185
  • Rank 208,271 (Top 5 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created almost 11 years ago
  • Updated over 4 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Istanbul unit test coverage plugin for gulp.

gulp-istanbul NPM version Build Status Dependency Status

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 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 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 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('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 when instrumenting:

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)

{
  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 required 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({
    // supports es6
    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()

reportOpts

Type: Object (optional)

{
  dir: './coverage'
}

You can also configure separate directory for each report.

{
  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.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

More Repositories

1

Inquirer.js

A collection of common interactive command line user interfaces.
TypeScript
19,956
star
2

mem-fs-editor

File edition helpers working on top of mem-fs (https://github.com/SBoudrias/mem-fs)
TypeScript
415
star
3

AST-query

Tentative to a simple JavaScript AST modification library
JavaScript
242
star
4

mem-fs

Simple in-memory vinyl file store.
TypeScript
123
star
5

class-extend

Backbone like `Class.extend` for Node.js
JavaScript
88
star
6

grouped-queue

In memory queue system prioritizing tasks
JavaScript
86
star
7

gruntfile-editor

An API to modify a Gruntfile.js content
JavaScript
40
star
8

readline2

Node.js Readline façade fixing bugs and issues in v0.8 and v0.10
JavaScript
27
star
9

gulp-exclude-gitignore

Gulp plugin to exclude file contained in .gitignore from the stream
JavaScript
27
star
10

run-async

Utility method to run function either synchronously or asynchronously using the common `this.async()` style.
JavaScript
23
star
11

require.replace

Require.js plugin to load conditionnal modules (i18n and such)
JavaScript
21
star
12

generator-jest

Add jest support to any projects
JavaScript
19
star
13

file-utils

Grunt.file utility fork to add some goodness
JavaScript
16
star
14

inquirer-npm-name

Helper function using inquirer to validate a value provided in a prompt does not exist as an npm package.
JavaScript
13
star
15

detect-conflict

Small utility library that check if a new file content can be merged safely in the on-disk existing file.
JavaScript
11
star
16

gulp-validate-jsdoc

Ensure your JsDoc covers every functions parameters.
JavaScript
7
star
17

dotfiles

My OS X dotfiles (based on necolas/dotfiles)
Shell
7
star
18

instagram-feed-slideshow

Fetch an instagram hash tag feed and displays it in a slideshow
JavaScript
4
star
19

frontend-windows-installer

Installer for most common Frontend/JavaScript work/build tools
3
star
20

Detect-Mobile-Device

PHP based mobile redirection code
2
star
21

flight-filedrop

File dropzone component (FileReader API)
JavaScript
2
star
22

bug-next-head

Demo project of a next.js bug with the Head component
JavaScript
1
star
23

generator-py-microlib

Generate python micro library boilerplate
JavaScript
1
star
24

jquery.3dish-slider

3D "ish" slider plugin for jQuery - Work in progress
JavaScript
1
star