Skip to content
This repository has been archived by the owner on Jan 19, 2021. It is now read-only.

Commit

Permalink
docs(README): standardize (#64)
Browse files Browse the repository at this point in the history
  • Loading branch information
@michael-ciniawsky
michael-ciniawsky committed Jul 9, 2017
1 parent 27cf4eb commit 75a4c67
Showing 1 changed file with 106 additions and 85 deletions.
191 changes: 106 additions & 85 deletions README.md
View file
Expand Up @@ -13,111 +13,127 @@
<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.
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 install --save-dev istanbul-instrumenter-loader
# or
yarn add --dev istanbul-instrumenter-loader
npm i -D istanbul-instrumenter-loader
```

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

#### References
### `References`

* [Loaders](https://webpack.js.org/concepts/loaders/)
* [karma-webpack](https://github.com/webpack/karma-webpack)
* [karma-coverage-istanbul-reporter](https://github.com/mattlewis92/karma-coverage-istanbul-reporter)

#### Project structure

Let's say you have the following:
### `Structure`

```
├── src/
│ └── components/
│ ├── bar/
│ │ └── index.js
│ └── foo/
│ └── index.js
└── test/
└── src/
└── components/
└── foo/
└── index.js
├─ 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
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
// require all `project/test/src/components/**/index.js`
const testsContext = require.context('./src/components/', true, /index\.js$/);
// requires all tests in `project/test/src/components/**/index.js`
const tests = require.context('./src/components/', true, /index\.js$/);

testsContext.keys().forEach(testsContext);
tests.keys().forEach(tests);

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

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

This file will be the only entry point for Karma.

#### karma.conf.js
> ℹ️ 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$/,
include: path.resolve('src/components/'),
loader: 'istanbul-instrumenter-loader'
}
]
...
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
},
…
]
}
...
},
reporters: [ 'progress', 'coverage-istanbul' ],
coverageIstanbulReporter: {
reports: [ 'text-summary' ],
fixWebpackSourcePaths: true
}
...
});
```

#### With babel
You must run the instrumentation as a post step:
### with `Babel`

You must run the instrumentation as a post step

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

#### Options
The loader supports all options supported by [istanbul-lib-instrument](https://github.com/istanbuljs/istanbuljs/blob/master/packages/istanbul-lib-instrument/api.md#instrumenter).
<h2 align="center"><a href="https://github.com/istanbuljs/istanbuljs/blob/master/packages/istanbul-lib-instrument/api.md#instrumenter">Options</a></h2>

<h2 align="center">Contributing</h2>
The loader supports all options supported by `istanbul-lib-instrument`

Don't hesitate to create a pull request. Every contribution is appreciated. In development you can start the tests by calling `npm test`.
|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}`|`true`|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|

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

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

Expand All @@ -131,33 +147,38 @@ Don't hesitate to create a pull request. Every contribution is appreciated. In d
<a href="https://github.com/deepsweet">Kir Belevich</a>
</td>
<td align="center">
<img width="150" height="150"
src="https://avatars3.githubusercontent.com/u/166921?v=3&s=150">
</br>
<a href="https://github.com/bebraw">Juho Vepsäläinen</a>
<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">
<img width="150" height="150"
src="https://avatars2.githubusercontent.com/u/8420490?v=3&s=150">
</br>
<a href="https://github.com/d3viant0ne">Joshua Wiens</a>
<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">
<img width="150" height="150"
src="https://avatars3.githubusercontent.com/u/533616?v=3&s=150">
</br>
<a href="https://github.com/SpaceK33z">Kees Kluskens</a>
<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">
<img width="150" height="150"
src="https://avatars3.githubusercontent.com/u/3408176?v=3&s=150">
</br>
<a href="https://github.com/TheLarkInn">Sean Larkin</a>
<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

Expand Down

0 comments on commit 75a4c67

Please sign in to comment.