Manually Create Coverage Badges Using GitHub Actions


Adding a coverage badge to your repository is an excellent way to demonstrate your project's test coverage and maintain a high level of code quality. By the end of this guide, you will be able to generate a dynamic coverage badge that updates automatically with each new push to your repository.

## Prerequisites

- A [Node.js](https://nodejs.org/) project with test coverage reports generated by a tool like [c8](https://github.com/bcoe/c8) or [Istanbul](https://github.com/istanbuljs/nyc).
- A GitHub repository for your project.
- [GitHub deploy keys](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) configured for your repository.

Let's get started!

## Step 1: Install Cheerio

Before anything else, make sure you have a coverage report generated by your testing tool. In our case, we will use the HTML report generated by [c8](https://github.com/bcoe/c8). This report will look something like this:

```html filename=./coverage/index.html
<!DOCTYPE html>
<html lang="en">
  <body>
    <div class="wrapper">
      <div class="pad1">
        <div class="clearfix">
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Statements</span>
            <span class="fraction">786/786</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Branches</span>
            <span class="fraction">74/74</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">90.9%</span>
            <span class="quiet">Functions</span>
            <span class="fraction">33/33</span>
          </div>
          <div class="fl pad1y space-right2">
            <span class="strong">100%</span>
            <span class="quiet">Lines</span>
            <span class="fraction">786/786</span>
          </div>
        </div>
      </div>
    </div>
  </body>
</html>
```

We will use [cheerio](https://github.com/cheeriojs/cheerio), a [jQuery](https://jquery.com/)-like library for server-side to extract the percentage data from the HTML. Install it to your `devDependencies` using the package manager of your choice:

```bash
# npm
npm install --save-dev cheerio

# yarn
yarn add --dev cheerio

# pnpm
pnpm add --save-dev cheerio
```

## Step 2: Create a Script to Extract Coverage Data

Next, we need to create the actual script that will extract the coverage data from the HTML report. Create a new file called `./scripts/generate-badges.js` and add the following code:

```js filename=./scripts/generate-badges.js
const fs = require('fs');
const https = require('https');
const cheerio = require('cheerio');

const coverageFile = './coverage/index.html';
const badgesDir = './coverage/badges';

// Read the coverage HTML file.
fs.readFile(coverageFile, 'utf-8', (err, data) => {
  if (err) {
    console.error(`Error reading coverage file: ${err}`);
    process.exit(1);
  }

  // Parse the HTML using Cheerio.
  const $ = cheerio.load(data);

  // Construct the shields.io URL for each badge.
  const statementsBadgeUrl = generateUrl('statements', extractPercentage($, 1));
  const branchesBadgeUrl = generateUrl('branches', extractPercentage($, 2));
  const functionsBadgeUrl = generateUrl('functions', extractPercentage($, 3));
  const linesBadgeUrl = generateUrl('lines', extractPercentage($, 4));

  // Create the badges directory if it does not exist.
  if (!fs.existsSync(badgesDir)) {
    fs.mkdirSync(badgesDir);
  }

  // Download each badge and save it to the badges directory.
  downloadBadge(statementsBadgeUrl, `${badgesDir}/statements.svg`);
  downloadBadge(branchesBadgeUrl, `${badgesDir}/branches.svg`);
  downloadBadge(functionsBadgeUrl, `${badgesDir}/functions.svg`);
  downloadBadge(linesBadgeUrl, `${badgesDir}/lines.svg`);

  console.log('Code coverage badges created successfully.');
});

/**
 * Generate a shields.io URL for a badge.
 *
 * Change the color of the badge based on the percentage.
 *
 * @param {string} text The text to display on the badge.
 * @param {number} percentage The percentage to display on the badge.
 * @returns {string} The shields.io URL.
 */
const generateUrl = (text, percentage) => {
  let color = 'brightgreen';
  if (percentage < 70) {
    color = 'red';
  } else if (percentage < 80) {
    color = 'yellow';
  } else if (percentage < 90) {
    color = 'orange';
  }
  return `https://img.shields.io/badge/coverage%3A${text}-${percentage}%25-${color}.svg`;
};

/**
 * Extract the code coverage percentage from the HTML.
 * @param {Cheerio} $ The Cheerio object.
 * @param {number} index The index of the element to extract.
 */
const extractPercentage = ($, index) => {
  const text = $(`.pad1y:nth-child(${index}) span.strong`) ?? '0';
  const percentage = text.text().trim().replace('%', '');
  return parseFloat(percentage);
};

/**
 * Download a badge from shields.io.
 * @param {string} url The shields.io URL.
 * @param {string} filename The filename to save the badge to.
 */
const downloadBadge = (url, filename) => {
  https.get(url, (res) => {
    if (res.statusCode !== 200) {
      console.error(`Error downloading badge: ${res.statusMessage}`);
      return;
    }

    const file = fs.createWriteStream(filename);
    res.pipe(file);
    file.on('finish', () => {
      file.close();
    });
  });
};
```

This is a fairly straightforward script that uses Cheerio to parse the HTML report and extract the coverage data. It then uses the data to generate the [shields.io](https://shields.io/) URLs for each badge type. Finally, it downloads each badge and saves it to the `./coverage/badges` directory.

Update your `package.json` to add a new script that will run the `generate-badges.js` script:

```json filename=package.json
{
  "scripts": {
    // ...
    "generate-badges": "node ./scripts/generate-badges.js"
  }
}
```

Run the script to generate the badges:

```bash
# generate the coverage report first
pnpm coverage

# generate the badges
pnpm generate-badges
```

## Step 3: Configure GitHub Actions

> **NOTE**: For this guide, we will use [pnpm](https://pnpm.io/), but the commands should be similar for other package managers.

> **NOTE**: This requires that you have an SSH Deploy Key configured for your repository. See [Create SSH Deploy Key](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) for more information.

In your repository, create a `.github/workflows` directory if it doesn't already exist. Then, create a new YAML file inside the workflows directory called `coverage-badge.yml`. This file will define the GitHub Actions workflow that generates the coverage badge.

Add the following content to `coverage-badge.yml`:

```yaml filename=.github/workflows/coverage-badge.yml
name: (main) coverage badge

on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  coverage-badge:
    strategy:
      matrix:
        os:
          - ubuntu-latest
        node:
          - 18.14.2
        pnpm:
          - 7
    runs-on: ${{ matrix.os }}
    steps:
      - name: checkout repository
        uses: actions/checkout@v3
      - name: setup node
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node }}
      - name: install pnpm
        uses: pnpm/action-setup@v2
        id: pnpm-install
        with:
          version: ${{ matrix.pnpm }}
          run_install: false
      - name: get pnpm store directory
        id: pnpm-cache
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
      - name: Setup pnpm cache
        uses: actions/cache@v3
        with:
          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-
      - name: install dependencies
        run: pnpm install
      - name: run coverage
        run: pnpm coverage
      - name: generate badges
        run: pnpm generate-badges
      - name: push coverage artifacts to another branch
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.COVERAGE_DEPLOY_KEY }}
          publish_dir: ./coverage
          publish_branch: coverage
          allow_empty_commit: true
```

Let's break down the workflow into its various sections:

```yaml
on:
  workflow_dispatch:
  push:
    branches:
      - main
```

The workflow is triggered when there's a push to the `main` branch or can be triggered manually ([`workflow_dispatch`](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch)).

```yaml
jobs:
  covera:
    strategy:
      matrix:
        os:
          - ubuntu-latest
        node:
          - 18.14.2
        pnpm:
          - 7
    runs-on: ${{ matrix.os }}
```

We're using a matrix strategy to run the workflow on multiple operating systems, Node.js versions, and pnpm versions. For our purpose, we will only use one version of each, but this is a good practice to follow.

```yaml
- name: checkout repository
  uses: actions/checkout@v3
- name: setup node
  uses: actions/setup-node@v3
  with:
    node-version: ${{ matrix.node }}
```

This step checks out your repository using the [actions/checkout](https://github.com/actions/checkout) action. Then, it sets up Node.js using the [actions/setup-node](https://github.com/actions/setup-node) action.

```yaml
- name: install pnpm
  uses: pnpm/action-setup@v2
  id: pnpm-install
  with:
    version: ${{ matrix.pnpm }}
    run_install: false
```

This step installs pnpm using the [pnpm/action-setup](https://github.com/pnpm/action-setup) action and the specified pnpm version from the matrix. We're not installing any dependencies yet, so we don't need to run `pnpm install`.

```yaml
- name: get pnpm store directory
  id: pnpm-cache
  shell: bash
  run: |
    echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
- name: Setup pnpm cache
  uses: actions/cache@v3
  with:
    path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
    key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
    restore-keys: |
      ${{ runner.os }}-pnpm-store-
- name: install dependencies
  run: pnpm install
```

These steps will use the cache from [actions/cache](https://github.com/actions/cache) and install the project's dependencies using pnpm. We're using the cache to reduce installation time and to avoid downloading the same dependencies multiple times.

```yaml
- name: run coverage
  run: pnpm coverage
- name: generate badges
  run: pnpm generate-badges
```

This step runs the `coverage` script, which should generate a coverage report. Then, it runs the `generate-badges` script, which should generate the coverage badges.

```yaml
- name: push coverage artifacts to another branch
  uses: peaceiris/actions-gh-pages@v3
  with:
    deploy_key: ${{ secrets.COVERAGE_DEPLOY_KEY }}
    publish_dir: ./coverage
    publish_branch: coverage
    allow_empty_commit: true
```

Lastly, this step pushes the coverage artifacts, including the generated badges and the coverage report, to a separate coverage branch in your repository using the [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages) action.

Options:

- The `deploy_key` option is set to the `COVERAGE_DEPLOY_KEY` secret, which is a Deploy Key stored in your repository settings. This deploy key should have write access to the repository. Follow the instructions from [Create SSH Deploy Key](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-create-ssh-deploy-key) to generate it and add it to your repository.
- The `publish_dir` is set to `./coverage`, which is the directory containing the coverage report and badges.
- The `allow_empty_commit` option is set to true to allow empty commits if there are no changes in the coverage artifacts.
- The `publish_branch` is the name of the branch you want to push the coverage artifacts to. It's currently set to `coverage`, but you can change it to whatever you want.

## Step 4: Add Badge to README

To display the coverage badge in your README file, add the following line at the top of your `README.md` file:

```md filename=README.md
![Coverage: Statements](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/statements.svg)
![Coverage: Branches](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/branches.svg)
![Coverage: Functions](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/functions.svg)
![Coverage: Lines](https://raw.githubusercontent.com/<USER_NAME>/<REPO_NAME>/<PUBLISH_BRANCH_NAME>/badges/lines.svg)
```

These lines will render the badges as an image. It should point to the latest badges in your `<PUBLISH_BRANCH_NAME>` branch.

## Conclusion

Congratulations! You have successfully created a dynamic coverage badge for your Node.js project. This badge will help you showcase your project's test coverage and encourage you to maintain a high level of code quality. Don't hesitate to customize this workflow to suit your needs and adapt it to different coverage tools and badge styles.

Happy coding!


Nap Joseph Calub

Posts with the "Coverage" tag