Monorepo-Coverage-Badges

Generate coverage badges for monorepos

Table of Contents

Requirements
Installation
Usage
Configuration
License

Requirements

You need to have a coverage report generated by your test runner
You can use any test runner, as long as it generates a coverage report

Examples

To generate a coverage report with Vitest, you can use the --coverage flag.
And set the coverage.reporter to include "json-summary" in your vitest.config.ts file.

To generate a coverage report with Jest, you can use the --coverage flag.
And set the "coverageReporters" to include "json-summary" in your jest.config.js file.

Installation

Install it with your package manager of choice (npm, yarn, pnpm) as a dev dependency

# npm
npm install monorepo-coverage-badges -D

# yarn
yarn add monorepo-coverage-badges -D

# pnpm
pnpm i monorepo-coverage-badges -D

Add the identifiers to your README.md file, where you want the badges to be placed, the identifiers are:

$coverage$ - The coverage badge
$lines$ - The lines badge
$statements$ - The statements badge
$functions$ - The functions badge
$branches$ - The branches badge

The indentifiers can be used multiple times in the same file and will be replaced with the correct shields.io badge url.

You may also pass a folder path to each identifier, to generate a badge for a specific folder.
You can use any folder path you want, but the path must be relative to the parent folder of the README.md file that contains the identifier.

For example, if you have a monorepo with the following structure:

	monorepo
	├── README.md
	├── packages
	│   ├── package-1
	│   │   ├── README.md
	│   │   └── package.json
	│   └── package-2
	│       ├── README.md
	│       └── package.json
	└── package.json
	

You can add the following identifiers to your monorepo's README.md file to generate a badge for the whole monorepo:
$coverage$, $lines$, $statements$, $functions$, $branches$

And if you want to show the coverage for a specific package, you can add the following identifiers to your monorepo's README.md file:
$coverage$/packages/package-1, $lines$/packages/package-1,
$statements$/packages/package-1, $functions$/packages/package-1, $branches$/packages/package-1

But you can use the normal identifiers in the package's README.md file, and it will generate a badge for the package itself as the path is relative to the parent folder of the README.md file.

Usage

Add it as a script to your monorepo's package.json file (you can name it whatever you want)
Vitest is used as an example, but you can use any test runner, as long as it generates a coverage report

You will most likely have test scripts in each package, if you do, just make the test script in the monorepo's package.json file run the test scripts in each package

{
	"scripts": {
		"test": "vitest --run && pnpm badges",
		"test:watch": "vitest --ui --coverage",
		"test:ci": "vitest --run --coverage && pnpm badges:ci",
		"badges": "monorepo-coverage-badges",
		"badges:ci": "monorepo-coverage-badges --ci"
	}
}

You can also add it to your pre-commit hook, to make sure the badges are always up to date.
You can use any hook you want, but the pre-commit hook is recommended

{
	"husky": {
		"hooks": {
			"pre-commit": "pnpm test && pnpm badges"
		}
	}
}

Configuration

You can initialize the configuration file with the --init flag.
After that, you can edit the monorepo-coverage-badges.config.cjs file.

You can also use the --config flag to specify a custom configuration file.

Options

silent - boolean - default: false

Disables all WARN and INFO messages

coverageFiles - string - default: "**/coverage-summary.json"

Glob pattern to find the coverage files

mdFiles - object - default: { "**/*.md": ... }

Object with glob patterns as keys and the values are explained further below

mdFiles[].coverage - object - default: { label: "coverage", ...DefaultBadge}

Object with the options for the coverage badge, the DefaultBadge options are explained further below
label is the text that shows inside of the badge

mdFiles[].statements - object - default: { label: "statements", ...DefaultBadge}

Object with the options for the statements badge, the DefaultBadge options are explained further below
label is the text that shows inside of the badge

mdFiles[].branches - object - default: { label: "branches", ...DefaultBadge}

Object with the options for the branches badge, the DefaultBadge options are explained further below
label is the text that shows inside of the badge

mdFiles[].functions - object - default: { label: "functions", ...DefaultBadge}

Object with the options for the functions badge, the DefaultBadge options are explained further below
label is the text that shows inside of the badge

mdFiles[].lines - object - default: { label: "lines", ...DefaultBadge}

Object with the options for the lines badge, the DefaultBadge options are explained further below
label is the text that shows inside of the badge

DefaultBadge - object - default: { style: "flat", uncoveredText: "unknown", logo: undefined, color: BadgeColor }

Object with the default options for the badges, the BadgeColor options are explained further below
style is the style of the badge, you can use any style from shields.io
uncoveredText is the text that shows inside of the badge when the coverage is unknown
logo is the logo that shows inside of the badge, you can use any logo from simpleicons.org

BadgeColor - object - default: { "<80": "critical", "<90": "important", ">=90": "success", uncovered: "informational" }

Object with the colors for the badges, the keys are the thresholds and the values are the colors, you can use any color from shields.io
uncovered is the color that shows inside of the badge when the coverage is unknown

You can use the following operators in the keys of the object:
== - equal
!= - not equal
< - less than
> - greater than
<= - less than or equal
>= - greater than or equal

License

Mozilla Public License 2.0