The jacoco-badge-generator GitHub Action is now also available as a CLI tool from PyPI
Vincent A. Cicirello
Posted on July 8, 2022
The jacoco-badge-generator began its life as a GitHub Action for use in GitHub workflows to do the following: parse a JaCoCo coverage report, generate coverage badges as SVGs entirely within GitHub Actions, optionally generate Shields JSON badge endpoints rather than direct badge generation, and optionally to perform pull request checks to fail workflow runs if coverage or branches coverage is below a user-configurable threshold, or if coverage or branches coverage decreased relative to prior run. It is suitable for use with Java projects, as well as projects with any other JVM language supported by JaCoCo such as Kotlin. The badges can be configured in a variety of ways, such as color scheme (e.g., mapping from coverage ranges to colors), and label text (e.g., defaults are "coverage" and "branches" but for a multi-module project, you might want something like "coverage (module name)" and "branches (module name)").
At the request of multiple users, the jacoco-badge-generator can now also be used as a command-line utility outside of GitHub Actions, such as executing it from a local build script. For this CLI use-case, it can now be installed locally from PyPI using pip. The jacoco-badge-generator is implemented 100% in Python. Within GitHub Actions, it is a container Action, relying on Docker to ensure a compatible Python version is available within the workflow. As a CLI tool, Docker is not needed, but you must have a compatible version of Python installed. It has been tested with Python 3.8, 3.9, and 3.10 (it may or may not work with earlier versions).
The remainder of this post is organized as follows:
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 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…
I made this repository a template to make it easy for someone
to use it to get started on a new project. To use this to start a
new project, click the "Use this Template" button. Depending on
which starter workflow you want to use, you might want to select
the option to include all branches. If you are not sure, then
for now include all branches. You can always delete unneeded
branches afterwards.
You are also free to fork this repository if you want (e.g
if you want to contribute to it with a pull request or…
The following example workflows demonstrate how to use some of the functionality. See the GitHub repository for complete documentation.
Example 1: All defaults
This first example GitHub workflow uses all of the default inputs, and also assumes the JaCoCo report is in Maven's default location. The default behavior only generates the coverage badge (and does not generate the branches coverage badge). The jacoco-badge-generator doesn't commit the badge, so there is an additional step in this workflow to do that.
name:buildon:push:branches:[main]jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v2-name:Set up the Java JDKuses:actions/setup-java@v2with:java-version:'17'distribution:'adopt'-name:Build with Maven and run testsrun:mvn -B test-name:Generate JaCoCo Badgeid:jacocouses:cicirello/jacoco-badge-generator@v2-name:Log coverage percentage to the workflow logrun:|echo "coverage = ${{ steps.jacoco.outputs.coverage }}"echo "branch coverage = ${{ steps.jacoco.outputs.branches }}"-name:Commit and push the badge (if it changed)uses:EndBug/add-and-commit@v7with:default_author:github_actionsmessage:'commitbadge'add:'*.svg'
Example 2: Both coverage and branches coverage badges
If you want badges for both instructions coverage and branches coverage, replace the jacoco-badge-generator step with:
Example 3: Changing the color theme and coverage intervals
If you want to change the colors used and the coverage intervals for each color, you can use the colors and intervals inputs. In the following example, green is used if coverage is at least 90 percent, yellow if coverage is less than 90 but at least 75 percent, orange is used if coverage is less than 75 percent but at least 60 percent, and red is used if coverage is less than 60 percent. This example also generates both badges. Colors can be specified as either SVG named colors as in this example or as 6-digit or 3-digit hex colors.
All of the above examples assume that you are running the tests with Maven. If you are using Gradle, you can replace the Maven step and the jacoco-badge-generator step with something like the following, which runs the tests and JaCoCo with Gradle rather than Maven, and which passes Gradle's location of the JaCoCo report to the jacoco-badge-generator:
-name:Run Testsrun:./gradlew test-name:Run Test Coveragerun:./gradlew jacocoTestReport-name:Generate JaCoCo Badgeid:jacocouses:cicirello/jacoco-badge-generator@v2with:jacoco-csv-file:build/reports/jacoco/test/jacocoTestReport.csv
JaCoCo coverage badges (SVG format), and coverage checks (e.g., decreasing coverage and minimum coverage)
pypi.org
Installing the CLI utility from PyPI
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
CLI examples
Here are a few example cases. All of the examples assume the Python 3 executable is python3, such as on Unix and MacOS. On Windows, just change python3 to py. All of the examples assume that you have already generated the JaCoCo report, and also assume that you are running the command from the root of your project.
All defaults
Generates only the instructions coverage badge, and assumes the report is in Maven's default location:
python3 -m jacoco_badge_generator
Generating instructions coverage and branches coverage badges
If you want to change the colors used and the coverage intervals for each color, you can use the --colors and --intervals options. In the following example, green is used if coverage is at least 90 percent, yellow if coverage is less than 90 but at least 75 percent, orange is used if coverage is less than 75 percent but at least 60 percent, and red is used if coverage is less than 60 percent. Colors can be specified as either SVG named colors as in this example or as 6-digit or 3-digit hex colors.
python3 -m jacoco_badge_generator --colors green yellow orange red --intervals 90 75 60
Generating Shields JSON endpoints instead of badges
If you want to generate Shields JSON endpoints instead of badges, you need
to disable generating the coverage badge, and enable the JSON endpoints:
The utility by default assumes that the JaCoCo report is the Maven default of target/site/jacoco/jacoco.csv. If it is somewhere else, there is an option
to specify its location. Here is an example with Gradle's standard location and name of the JaCoCo csv report.
Features information on several open source GitHub Actions for workflow automation that we have developed to automate parts of the CI/CD pipeline, and other repetitive tasks. The GitHub Actions featured include jacoco-badge-generator, generate-sitemap, user-statistician, and javadoc-cleanup.
actions.cicirello.org
Here is an earlier DEV post about the jacoco-badge-generator, including an example GitHub workflow that also comments the coverage percentage on pull requests:
pypi.org
actions.cicirello.org
