132 lines
4.5 KiB
Markdown
132 lines
4.5 KiB
Markdown
|
# babel-plugin-istanbul
|
|||
|
|
|
|||
|
|
[](https://greenkeeper.io/)
|
|||
|
|
[](https://travis-ci.org/istanbuljs/babel-plugin-istanbul)
|
|||
|
|
[](https://coveralls.io/github/istanbuljs/babel-plugin-istanbul?branch=master)
|
|||
|
|
[](https://conventionalcommits.org)
|
|||
|
|
[](http://devtoolscommunity.herokuapp.com)
|
|||
|
|
|
|||
|
|
_Having problems? want to contribute? join our [community slack](http://devtoolscommunity.herokuapp.com)_.
|
|||
|
|
|
|||
|
|
A Babel plugin that instruments your code with Istanbul coverage.
|
|||
|
|
It can instantly be used with [karma-coverage](https://github.com/karma-runner/karma-coverage) and mocha on Node.js (through [nyc](https://github.com/bcoe/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](#integrations) section.
|
|||
|
|
|
|||
|
|
## Usage
|
|||
|
|
|
|||
|
|
Install it:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
npm install --save-dev babel-plugin-istanbul
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Add it to `.babelrc` in test mode:
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
{
|
|||
|
|
"env": {
|
|||
|
|
"test": {
|
|||
|
|
"plugins": [ "istanbul" ]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Optionally, use [cross-env](https://www.npmjs.com/package/cross-env) to set
|
|||
|
|
`NODE_ENV=test`:
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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](https://github.com/karma-runner/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](https://codecov.io/github/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`](https://github.com/bcoe/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`:
|
|||
|
|
|
|||
|
|
```js
|
|||
|
|
"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](https://github.com/bcoe/nyc#excluding-files):
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"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](https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md#ignoring-code-for-coverage-purposes) 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.
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"env": {
|
|||
|
|
"test": {
|
|||
|
|
"plugins": [
|
|||
|
|
["istanbul", {
|
|||
|
|
"useInlineSourceMaps": false
|
|||
|
|
}]
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
If you're instrumenting code programatically, you can pass a source map explicitly.
|
|||
|
|
```js
|
|||
|
|
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](https://github.com/dtinth)'s original library [`babel-plugin-__coverage__`](https://github.com/dtinth/babel-plugin-__coverage__).
|