Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/the-bugging/istanbul-badges-readme
Creates and updates README testing coverage badges with your json-summary
https://github.com/the-bugging/istanbul-badges-readme
c8 coverage githooks husky istanbul istanbul-badges-readme jest jest-badges-readme lcov lcov-report nyc readme
Last synced: about 15 hours ago
JSON representation
Creates and updates README testing coverage badges with your json-summary
- Host: GitHub
- URL: https://github.com/the-bugging/istanbul-badges-readme
- Owner: the-bugging
- License: mit
- Created: 2020-08-03T18:29:38.000Z (over 4 years ago)
- Default Branch: develop
- Last Pushed: 2024-05-04T14:32:42.000Z (9 months ago)
- Last Synced: 2025-01-11T09:47:13.332Z (3 days ago)
- Topics: c8, coverage, githooks, husky, istanbul, istanbul-badges-readme, jest, jest-badges-readme, lcov, lcov-report, nyc, readme
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/istanbul-badges-readme
- Size: 4.91 MB
- Stars: 94
- Watchers: 4
- Forks: 32
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Istanbul Badges Readme
> Creates README badges from istanbul coverage report
| Statements | Branches | Functions | Lines |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|  |  |  |  |
---
## Table of Contents
- [Running example](#running-example)
- [Requirements](#requirements)
- [Installation](#installation)
- [Simple Usage](#simple-usage)
- [Advanced Usage](#advanced-usage-arguments)
- [Usage as a part of your githooks](#usage-as-a-part-of-your-githooks)
- [Usage as a part of your CI](#usage-as-a-part-of-your-ci)
- [Custom badge Styles](#custom-badge-styles)
- [See running examples](#see-running-examples)
- [Contributors](#contributors)
- [License](#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](./examples/README.md).
---
## 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:
- ``
- ``
- ``
- ``
- A simple example of all hashes being used in a table fashion markup:
```markdown
| 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](https://shields.io/)_ own style reference. See more examples [here](#badge-styles).
```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](https://shields.io/)_ own documentation which uses all icons available at _[simple-icons](https://simpleicons.org/)_.
```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](#exit-code) 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'`:
- Square flat `style='square-flat'`:
- Plastic `style='plastic'`:
- For the badge `style='for-the-badge'`:
## See running examples
[Examples folder](./examples/README.md)
> ✔️ **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](https://allcontributors.org/docs/en/emoji-key)):
Olavo Parno
🤔 💻 ⚠️
nothingismagick
🤔 🐛 🖋
Dave Fisher
🐛
Martin Zagora
🤔 🐛
Victor Miti
🐛
Stefan Huber
💬 📖
Guilherme Ventura
🤔 💻 🐛
Matt Hodges
🐛
Antoine Vendeville
🐛
Oleg Dutchenko
🐛
Thomas
🤔
Troy Poulter
💻 🤔 ⚠️
LiaoLiao
🤔
David Mimnagh
🤔
Micael Levi L. Cavalcante
🤔 💻 🐛
Richard Michael Coo
🐛
Letícia Vidal
🐛
Yusuf
📖
Supun Tharinda Edirisuriya
📖
Nico Meyer
💻 🤔
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
---
## License
Istanbul Badges Readme is [MIT licensed](./LICENSE).