istanbul-badges-readme
v1.9.0
Creates README badges from istanbul coverage report
0/weekUpdated 1 years agoMITUnpacked: 49.6 KB
Published by Olavo Parno
npm install istanbul-badges-readmeIstanbul Badges Readme
> Creates README badges from istanbul coverage report
| Statements | Branches | Functions | Lines |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| !Statements | !Branches | !Functions | !Lines |
---
Table of Contents
- Running example
- Requirements
- Installation
- Simple Usage
- Advanced Usage
- Usage as a part of your githooks
- Usage as a part of your CI
- Custom badge Styles
- See running examples
- Contributors
- License
Running example
---
Requirements
- First, of course, you must have a test runner such as Jest and Mocha;
- You must have json-summary as a coverageReporter in your tests configuration;
- For example, if you are using Jest, configuration should either be within package.json or inside your jest config file i.e. jest.config.js or jestconfig.json as written below:
``json`
"coverageReporters": ["json-summary"]
- See more in the examples.
---
Installation
- Install the library in your project as a devDependency:
`bash`
npm i -D istanbul-badges-readme
- Add at least one of the below coverage hashes in your README file:
- !Statements
-
-
-
- A simple example of all hashes being used in a table fashion markup:
`markdown`
| Statements | Branches | Functions | Lines |
| --------------------------- | ----------------------- | ------------------------- | ----------------- |
| !Statements | !Branches | !Functions | !Lines |
---
Simple Usage
- Simply run it from the CLI as follows:
`bash`
npx istanbul-badges-readme
- Or add it to your package.json scripts as follows:
`json`
"scripts": {
"make-badges": "istanbul-badges-readme",
}
---
Advanced Usage Arguments
#### Coverage Directory
- Custom coverage directory? Use --coverageDir argument:
`bash`
npm run istanbul-badges-readme --coverageDir="./my-custom-coverage-directory"
#### Readme Directory
- Custom readme directory? Use --readmeDir argument:
`bash`
npm run istanbul-badges-readme --readmeDir="./my-custom-readme-directory"
#### Silent
- Want it without logging? Try silent mode with --silent argument:
`bash`
npm run istanbul-badges-readme --silent
#### Functions and Branches Labels
- You may also create custom labeling for the badges using the corresponding hash and _Label_ e.g. _branchesLabel_ --branchesLabel='Branches are troublesome!':
`bash`
npm run istanbul-badges-readme --functionsLabel='Mis funciones!' --branchesLabel='Branches are troublesome!'
#### Badge Style
- You can also change the badge styling, according to _shields.io's_ own style reference. See more examples here.
`bash`
npm run istanbul-badges-readme --style="for-the-badges"
#### Badge Logo
- There is an option to use a _logo_ within the badge, as described on _shields.io's_ own documentation which uses all icons available at _simple-icons_.
`bash`
npm run istanbul-badges-readme --logo="jest"
#### Configure Badge Color
- You can configure the color threshold of the badges by passing the --colors argument. If you want red badges for a code coverage below 50% and yellow badges for a coverage below 60%, you'd do this:`bash`
npm run istanbul-badges-readme --colors=red:50,yellow:60
#### Exit code
- To exit with 1 code on validation errors (eg.: _README doesn't exist_, or _coverage directory doesn't exist_) or on editing errors (eg.: cannot write to README due to lack of permissions). The default exit code is 0. Set a different one by using --exitCode argument.
`bash`
npm run istanbul-badges-readme --exitCode=1
---
Usage as a part of your githooks
- If you want to have this run on the pre-commit hook and update the commit in place, just install husky and add the pre-commit script to your package.json.
1. Install Husky.
`bash`
npm install -D husky
2. Add your pre-commit script:
`json`
"husky": {
"hooks": {
"pre-commit": "npm run test && istanbul-badges-readme && git add 'README.md'"
}
}
3. Git Commit and Push. Just use your workflow as usual. If your tests fail, no commit. If they pass, update the README.md and add the file to the commit. Nice!
---
Usage as a part of your CI
You may want to have peace of mind that contributors have run istanbul-badges-readme locally by performing a simple check in your CI.
The --ci argument will throw an error, code 0 by default unless exitCode is specified, thus not updating anything regarding coverage, if the badges generated do not match what is already in the README.md.
You can add this to your package.json as follows for exitCode 0:
`json`
"scripts": {
"make-badges": "istanbul-badges-readme",
"make-badges:ci": "npm run make-badges -- --ci",
}
Also if you wish a different exitCode:
`json`
"scripts": {
"make-badges": "istanbul-badges-readme",
"make-badges:ci": "npm run make-badges -- --ci --exitCode=1",
}
This is a useful addition/alternative to the githooks approach for some use cases such as larger codebases, slow computers etc, where it isn't always feasible to run all the tests and produce coverage on each commit.
Custom Badge Styles
- DEFAULT STYLE Square style='square':
!Statements
- Square flat style='square-flat':
!Statements
- Plastic style='plastic':
!Statements
- For the badge style='for-the-badge'`:
!Statements
See running examples
> ✔️ Tip
>
> We use this in our pull request GitHub Action, check out a recent pull request to see it in action!
---
Contributors
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
---
License
Istanbul Badges Readme is MIT licensed.