# istanbul-instrumenter-loader

> Istanbul instrumenter loader for webpack

Latest version **3.0.1** (published 2018-03-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install istanbul-instrumenter-loader
pnpm add istanbul-instrumenter-loader
yarn add istanbul-instrumenter-loader
bun add istanbul-instrumenter-loader
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 3.0.1 |
| Published | 2018-03-28 |
| First published | 2014-09-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >= 4.8 < 5.0.0 \|\| >= 5.10 |
| Dependencies | 4 |
| Unpacked size | 14.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 270 |
| Author | Kir Belevich |
| Maintainers | bebraw, d3viant0ne, deepsweet |
| Keywords | webpack, loader, istanbul, coverage |

## Links

- npm: https://www.npmjs.com/package/istanbul-instrumenter-loader
- Repository: https://github.com/webpack-contrib/istanbul-instrumenter-loader
- Issues: https://github.com/webpack-contrib/istanbul-instrumenter-loader/issues
- npm.io page: https://npm.io/package/istanbul-instrumenter-loader

## Dependencies (4)

- [loader-utils](https://npm.io/package/loader-utils.md) ^1.1.0
- [schema-utils](https://npm.io/package/schema-utils.md) ^0.3.0
- [convert-source-map](https://npm.io/package/convert-source-map.md) ^1.5.0
- [istanbul-lib-instrument](https://npm.io/package/istanbul-lib-instrument.md) ^1.7.3

## Alternatives

- [raw-loader](https://npm.io/package/raw-loader.md) — 4.3M weekly downloads
- [plop](https://npm.io/package/plop.md) — 1.4M weekly downloads
- [webpack-deadcode-plugin](https://npm.io/package/webpack-deadcode-plugin.md) — 80.3K weekly downloads
- [@storybook/preact-vite](https://npm.io/package/@storybook/preact-vite.md) — 54.2K weekly downloads
- [vite-plugin-transform](https://npm.io/package/vite-plugin-transform.md) — 2.4K weekly downloads

## Recent versions

- 3.0.1 (latest) — 2018-03-28
- 3.0.0-rc.1 (beta) — 2017-07-13
- 3.0.0 — 2017-07-26
- 3.0.0-rc.0 — 2017-07-12
- 3.0.0-beta.1 — 2017-07-10
- 3.0.0-beta.0 — 2017-06-08
- 2.0.0 — 2017-02-09
- 1.2.0 — 2016-12-23
- 1.1.0 — 2016-11-27
- 1.0.0 — 2016-09-15
- 0.2.0 — 2016-02-15
- 0.1.3 — 2015-05-11
- 0.1.2 — 2014-09-28
- 0.1.1 — 2014-09-25
- 0.1.0 — 2014-09-25

## README

[![npm][npm]][npm-url]
[![node][node]][node-url]
[![deps][deps]][deps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
[![chat][chat]][chat-url]

<div align="center">
  <a href="https://github.com/webpack/webpack">
    <img width="200" height="200"
      src="https://webpack.js.org/assets/icon-square-big.svg">
  </a>
  <h1>Istanbul Instrumenter Loader</h1>
</div>

Instrument JS files with [istanbul-lib-instrument](https://github.com/istanbuljs/istanbuljs/tree/master/packages/istanbul-lib-instrument) for subsequent code coverage reporting

<h2 align="center">Install</h2>

```bash
npm i -D istanbul-instrumenter-loader
```

<h2 align="center"><a href="https://webpack.js.org/concepts/loaders">Usage</a></h2>

### `References`

* [karma-webpack](https://github.com/webpack/karma-webpack)
* [karma-coverage-istanbul-reporter](https://github.com/mattlewis92/karma-coverage-istanbul-reporter)

### `Structure`

```
├─ src
│ |– components
│ | |– bar
│ | │ |─ index.js
│ | |– foo/
│     |– index.js
|– test
| |– src
| | |– components
| | | |– foo
| | | | |– index.js
```

To create a code coverage report for all components (even for those for which you have no tests yet) you have to require all the 1) sources and 2) tests. Something like it's described in ["alternative usage" of karma-webpack](https://github.com/webpack/karma-webpack#alternative-usage)

**test/index.js**
```js
// requires all tests in `project/test/src/components/**/index.js`
const tests = require.context('./src/components/', true, /index\.js$/);

tests.keys().forEach(tests);

// requires all components in `project/src/components/**/index.js`
const components = require.context('../src/components/', true, /index\.js$/);

components.keys().forEach(components);
```

> ℹ️  This file will be the only `entry` point for `karma`

**karma.conf.js**
```js
config.set({
  ...
  files: [
    'test/index.js'
  ],
  preprocessors: {
    'test/index.js': 'webpack'
  },
  webpack: {
    ...
    module: {
      rules: [
        // instrument only testing sources with Istanbul
        {
          test: /\.js$/,
          use: { loader: 'istanbul-instrumenter-loader' },
          include: path.resolve('src/components/')
        }
      ]
    }
    ...
  },
  reporters: [ 'progress', 'coverage-istanbul' ],
  coverageIstanbulReporter: {
    reports: [ 'text-summary' ],
    fixWebpackSourcePaths: true
  }
  ...
});
```

### with `Babel`

You must run the instrumentation as a post step

**webpack.config.js**
```js
{
  test: /\.js$|\.jsx$/,
  use: {
    loader: 'istanbul-instrumenter-loader',
    options: { esModules: true }
  },
  enforce: 'post',
  exclude: /node_modules|\.spec\.js$/,
}
```

<h2 align="center"><a href="https://github.com/istanbuljs/istanbuljs/blob/master/packages/istanbul-lib-instrument/api.md#instrumenter">Options</a></h2>

The loader supports all options supported by `istanbul-lib-instrument`

|Name|Type|Default|Description|
|:--:|:--:|:-----:|:----------|
|**`debug`**|`{Boolean}`|`false`|Turn on debugging mode|
|**`compact`**|`{Boolean}`|`true`|Generate compact code|
|**`autoWrap`**|`{Boolean}`|`false`|Set to `true` to allow return statements outside of functions|
|**`esModules`**|`{Boolean}`|`false`|Set to `true` to instrument ES2015 Modules|
|**`coverageVariable`**|`{String}`|`__coverage__`|Name of global coverage variable|
|**`preserveComments`**|`{Boolean}`|`false`|Preserve comments in `output`|
|**`produceSourceMap`**|`{Boolean}`|`false`|Set to `true` to produce a source map for the instrumented code|
|**`sourceMapUrlCallback`**|`{Function}`|`null`|A callback function that is called when a source map URL is found in the original code. This function is called with the source filename and the source map URL|

**webpack.config.js**
```js
{
  test: /\.js$/,
  use: {
    loader: 'istanbul-instrumenter-loader',
    options: {...options}
  }
}
```

<h2 align="center">Maintainers</h2>

<table>
  <tbody>
    <tr>
      <td align="center">
        <img width="150" height="150"
        src="https://avatars.githubusercontent.com/u/266822?v=3&s=150">
        </br>
        <a href="https://github.com/deepsweet">Kir Belevich</a>
      </td>
      <td align="center">
        <a href="https://github.com/bebraw">
          <img width="150" height="150" src="https://github.com/bebraw.png?v=3&s=150">
          </br>
          Juho Vepsäläinen
        </a>
      </td>
      <td align="center">
        <a href="https://github.com/d3viant0ne">
          <img width="150" height="150" src="https://github.com/d3viant0ne.png?v=3&s=150">
          </br>
          Joshua Wiens
        </a>
      </td>
      <td align="center">
        <a href="https://github.com/michael-ciniawsky">
          <img width="150" height="150" src="https://github.com/michael-ciniawsky.png?v=3&s=150">
          </br>
          Michael Ciniawsky
        </a>
      </td>
      <td align="center">
        <a href="https://github.com/mattlewis92">
          <img width="150" height="150" src="https://github.com/mattlewis92.png?v=3&s=150">
          </br>
          Matt Lewis
        </a>
      </td>
    </tr>
  <tbody>
</table>


[npm]: https://img.shields.io/npm/v/istanbul-instrumenter-loader.svg
[npm-url]: https://npmjs.com/package/istanbul-instrumenter-loader

[node]: https://img.shields.io/node/v/istanbul-instrumenter-loader.svg
[node-url]: https://nodejs.org

[deps]: https://david-dm.org/webpack-contrib/istanbul-instrumenter-loader.svg
[deps-url]: https://david-dm.org/webpack-contrib/istanbul-instrumenter-loader

[tests]: http://img.shields.io/travis/webpack-contrib/istanbul-instrumenter-loader.svg
[tests-url]: https://travis-ci.org/webpack-contrib/istanbul-instrumenter-loader

[cover]: https://codecov.io/gh/webpack-contrib/istanbul-instrumenter-loader/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/webpack-contrib/istanbul-instrumenter-loader

[chat]: https://badges.gitter.im/webpack/webpack.svg
[chat-url]: https://gitter.im/webpack/webpack

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