Overview

The jacoco-badge-generator can be used in one of two ways: as a GitHub Action or as a command-line utility (e.g., such as part of a local build script). The jacoco-badge-generator parses a jacoco.csv from a JaCoCo coverage report, computes C0 and C1 coverage percentages from JaCoCo's Instructions and Branches counters, and generates badges for one or both of these (user configurable) to provide an easy to read visual summary of the code coverage of your test cases. The default behavior directly generates the badges internally with no external calls, but the action also provides an option to instead generate Shields JSON endpoints. It supports both the basic case of a single jacoco.csv, as well as multi-module projects in which case the action can produce coverage badges from the combination of the JaCoCo reports from all modules, provided that the individual reports are independent. It can also optionally generate a simple JSON summary report containing the computed coverages for easy consumption by other tools.

When used as a GitHub Action, the jacoco-badge-generator can also optionally be used as part of a pull-request check. Specifically, you can configure it to fail the workflow run if coverage decreased relative to prior run, and/or if coverage is below a target threshold.

The jacoco-badge-generator can be integrated directly into your CI/CD workflow within GitHub Actions, or it can be used as a command-line utility (installable for this purpose from PyPI). It is implemented in Python. The jacoco-badge-generator source code repository is hosted on GitHub; and is licensed under the MIT License. Also in the GitHub repository you will find detailed instructions for use including several sample GitHub workflows.

The jacoco-badge-generator GitHub Action is developed by Vincent A. Cicirello. It was originally implemented for my own use, but I have decided to share it with others.

The developers of the jacoco-badge-generator are not affiliated with the developers of JaCoCo, although we are a fan and user of their excellent test coverage tool.

Live GitHub Actions Examples

We have a template repository containing a simple Java project (Maven), and several runnable example workflows demonstrating the most common use-cases. The purpose of that repository is to enable potential new users of the action to use it as a project starter, or to have a sample that they can fork and experiment with before integrating into their projects.

You can also take a look at the following real projects that use the action.

Command-Line Usage

Although the tool began its life as a GitHub Action, it can now be used as a command-line utility outside of GitHub Actions, such as on your local development machine.

Installing from PyPI: The jacoco-badge-generator requires Python 3 (and has been tested with Python 3.8 and above).

To install from PyPi (Unix and MacOS):

python3 -m pip install jacoco-badge-generator

To install from PyPi (Windows):

py -m pip install jacoco-badge-generator

To upgrade to the latest version from PyPi (Unix and MacOS):

python3 -m pip install --upgrade jacoco-badge-generator

To upgrade to the latest version from PyPi (Windows):

py -m pip install --upgrade jacoco-badge-generator

Running for the First Time: After installing, we recommend running it once with the -h or --help flag to see the details of all of the available command-line options.

On Unix or MacOS:

python3 -m jacoco_badge_generator --help

On Windows:

py -m jacoco_badge_generator --help

Detailed Usage Examples: See the detailed usage examples in the GitHub repository.

Tech Stack

The jacoco-badge-generator GitHub Action utilizes the following:

• Python 3 (CLI mode is 100% Python with no external dependencies);
• GitHub Actions mode additionally utilizes the following:
  • The pyaction Docker container, which is a Docker container designed to support GitHub Actions development in the Python language (also see pyaction's GitHub repository);
  • The cicirello/python-github-action-template repository, a template that we maintain to assist developers getting started developing a GitHub Action in Python;
  • Docker since it is implemented as a container action; and
  • GitHub Container Registry, which is where we pull pyaction from at runtime for faster action loading (e.g., pulling the base Docker container from GitHub while an action is running on a GitHub server should be faster than pulling from Docker Hub).

Blog Posts About the jacoco-badge-generator

As the author of the jacoco-badge-generator, I occasionally post about this, and other software that I maintain on DEV.to. See my DEV.to profile for a full list of such posts. Below is a selection of blog posts specifically about the jacoco-badge-generator.

• JaCoCo Coverage Badges for Multi-Module Projects in GitHub Actions, posted on DEV on May 25, 2023.

  This post is a tutorial on usage of the jacoco-badge-generator for multi-module projects, including both within GitHub Actions as well as with the CLI utility.

• Using GitHub Actions to Build a Java Project With Pull Request Coverage Commenting and Coverage Badges, posted on DEV on November 9, 2022.

  This post is a tutorial on how to use GitHub Actions for a CI/CD pipeline to build a Java project, validate tests during pull requests, generate a coverage report, including commenting coverage on pull requests and generating coverage badges.

• The jacoco-badge-generator GitHub Action is now also available as a CLI tool from PyPI, posted on DEV on July 8, 2022.

  This post introduces an update to the jacoco-badge-generator that includes the ability to use as a command line tool, rather than strictly as a GitHub Action. Several examples of how to use the new functionality is covered, including how to install from PyPI.

• JaCoCo coverage badges, PR coverage checks, and PR coverage comments, from GitHub Actions, posted on DEV on November 29, 2021.

  This post introduces an update to the jacoco-badge-generator, which includes pull-request coverage checks. Additionally, it provides an example workflow demonstrating how to use it in combination with the GitHub CLI to automate commenting on pull requests with the test coverage. This workflow was a submission to the DEV/GitHub Actions Hackathon.