• Stars
    star
    622
  • Rank 72,195 (Top 2 %)
  • Language
    JavaScript
  • License
    BSD 3-Clause "New...
  • Created over 8 years ago
  • Updated 4 months ago

Reviews

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

Repository Details

A babel plugin that adds istanbul instrumentation to ES6 code

babel-plugin-istanbul

Coverage Status Conventional Commits community slack

Having problems? want to contribute? join our community slack.

A Babel plugin that instruments your code with Istanbul coverage. It can instantly be used with karma-coverage and mocha on Node.js (through nyc).

Note: This plugin does not generate any report or save any data to any file; it only adds instrumenting code to your JavaScript source code. To integrate with testing tools, please see the Integrations section.

Usage

Install it:

npm install --save-dev babel-plugin-istanbul

Add it to .babelrc in test mode:

{
  "env": {
    "test": {
      "plugins": [ "istanbul" ]
    }
  }
}

Optionally, use cross-env to set NODE_ENV=test:

{
  "scripts": {
    "test": "cross-env NODE_ENV=test nyc --reporter=lcov --reporter=text mocha test/*.js"
  }
}

Integrations

karma

It just works with Karma. First, make sure that the code is already transpiled by Babel (either using karma-babel-preprocessor, karma-webpack, or karma-browserify). Then, simply set up karma-coverage according to the docs, but don’t add the coverage preprocessor. This plugin has already instrumented your code, and Karma should pick it up automatically.

It has been tested with bemusic/bemuse project, which contains ~2400 statements.

mocha on node.js (through nyc)

Configure Mocha to transpile JavaScript code using Babel, then you can run your tests with nyc, which will collect all the coverage report.

babel-plugin-istanbul respects the include/exclude configuration options from nyc, but you also need to configure NYC not to instrument your code by adding these settings in your package.json:

  "nyc": {
    "sourceMap": false,
    "instrument": false
  },

Ignoring files

You don't want to cover your test files as this will skew your coverage results. You can configure this by providing plugin options matching nyc's exclude/include rules:

{
  "env": {
    "test": {
      "plugins": [
        ["istanbul", {
          "exclude": [
            "**/*.spec.js"
          ]
        }]
      ]
    }
  }
}

If you don't provide options in your Babel config, the plugin will look for exclude/include config under an "nyc" key in package.json.

You can also use istanbul's ignore hints to specify specific lines of code to skip instrumenting.

Source Maps

By default, this plugin will pick up inline source maps and attach them to the instrumented code such that code coverage can be remapped back to the original source, even for multi-step build processes. This can be memory intensive. Set useInlineSourceMaps to prevent this behavior.

{
  "env": {
    "test": {
      "plugins": [
        ["istanbul", {
          "useInlineSourceMaps": false
        }]
      ]
    }
  }
}

If you're instrumenting code programatically, you can pass a source map explicitly.

import babelPluginIstanbul from 'babel-plugin-istanbul';

function instrument(sourceCode, sourceMap, fileName) {
  return babel.transform(sourceCode, {
    filename,
    plugins: [
      [babelPluginIstanbul, {
        inputSourceMap: sourceMap
      }]
    ]
  })
}

Credit where credit is due

The approach used in babel-plugin-istanbul was inspired by Thai Pangsakulyanont's original library babel-plugin-__coverage__.

babel-plugin-istanbul for enterprise

Available as part of the Tidelift Subscription.

The maintainers of babel-plugin-istanbul and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source dependencies you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact dependencies you use. Learn more.

More Repositories

1

nyc

the Istanbul command line interface
JavaScript
5,602
star
2

istanbuljs

monorepo containing the various nuts and bolts that facilitate istanbul.js test instrumentation
JavaScript
1,006
star
3

puppeteer-to-istanbul

given coverage information output by puppeteer's API output a format consumable by Istanbul reports
JavaScript
209
star
4

v8-to-istanbul

convert from v8 coverage format to istanbul's format
JavaScript
113
star
5

spawn-wrap

Wrap all spawned Node.js child processes by adding environs and arguments ahead of the main JavaScript file argument.
JavaScript
36
star
6

istanbuljs.github.io

the Istanbul community website
JavaScript
22
star
7

append-transform

handle multiple require hooks
JavaScript
21
star
8

caching-transform

Wraps a transform and provides caching
JavaScript
20
star
9

eslint-plugin-istanbul

ESLint plugin for istanbul code coverage
JavaScript
10
star
10

esm-loader-hook

Loader hook for ESM instrumentation (experimental!!)
JavaScript
10
star
11

sample-babel-node

Sample babel project to demonstrate source mapped coverage reports with istanbul
JavaScript
9
star
12

sample-mocha-compilers

Sample project to demo istanbul coverage with mocha using the babel compiler
JavaScript
7
star
13

test-exclude

test for inclusion or exclusion of paths using globs
JavaScript
7
star
14

istanbul-lib-processinfo

A module for reading and writing in NYC's processinfo data folder
JavaScript
3
star
15

load-nyc-config

Utility function to load nyc configuration
JavaScript
2
star
16

schema

Schemas describing various structures used by nyc and istanbuljs
JavaScript
1
star
17

assets

logos, fonts, graphics, and other assets.
1
star