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:
- GitHub Actions usage examples
- CLI utility installation and usage examples
- Learn more
- Support the project
The GitHub repository includes the source code, as well as more detailed documentation including additional examples:
cicirello
/
jacoco-badge-generator
Coverage badges, and pull request coverage checks, from JaCoCo reports in GitHub Actions
jacoco-badge-generator
Check out all of our GitHub Actions: https://actions.cicirello.org/
About
| GitHub Actions |
 |
|---|---|
| Command-Line Utility |
  
|
| Build Status |
 
|
| Security |  |
| Source Info |
 
|
| Support |
  
|
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…
GitHub Actions usage examples
In addition to the GitHub repository, embedded above, there is also a template repository with a few runnable GitHub workflows:
cicirello
/
examples-jacoco-badge-generator
Sample Java project with runnable workflows demonstrating the cicirello/jacoco-badge-generator GitHub Action
Runnable Workflows Demonstrating the cicirello/jacoco-badge-generator GitHub Action
The purpose of this repository includes:
- providing a simple example of configuring the jacoco-maven-plugin,
- providing a simple example of running jacoco in GitHub Actions as part of a build, and
- providing runnable example workflows using the cicirello/jacoco-badge-generator GitHub Action.
Why is this Repository a Template?
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: build
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up the Java JDK
uses: actions/setup-java@v2
with:
java-version: '17'
distribution: 'adopt'
- name: Build with Maven and run tests
run: mvn -B test
- name: Generate JaCoCo Badge
id: jacoco
uses: cicirello/jacoco-badge-generator@v2
- name: Log coverage percentage to the workflow log
run: |
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@v7
with:
default_author: github_actions
message: 'commit badge'
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:
- name: Generate JaCoCo Badge
id: jacoco
uses: cicirello/jacoco-badge-generator@v2
with:
generate-branches-badge: true
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.
- name: Generate JaCoCo Badge
id: jacoco
uses: cicirello/jacoco-badge-generator@v2
with:
generate-branches-badge: true
colors: green yellow orange red
intervals: 90 75 60
Example 4: Shields JSON endpoints instead of SVG badges
If you'd rather generate JSON instead of SVG badges that you can then pass to Shields custom endpoint, you can use the following step:
- name: Generate JaCoCo Badge
id: jacoco
uses: cicirello/jacoco-badge-generator@v2
with:
generate-coverage-badge: false
generate-coverage-endpoint: true
generate-branches-endpoint: true
Example 5: Gradle rather than Maven
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 Tests
run: ./gradlew test
- name: Run Test Coverage
run: ./gradlew jacocoTestReport
- name: Generate JaCoCo Badge
id: jacoco
uses: cicirello/jacoco-badge-generator@v2
with:
jacoco-csv-file: build/reports/jacoco/test/jacocoTestReport.csv
CLI utility installation and usage examples
The PyPI package page is found at:
jacoco-badge-generator · PyPI
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
python3 -m jacoco_badge_generator --generate-branches-badge true
Changing Colors 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 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:
python3 -m jacoco_badge_generator --generate-coverage-badge false --generate-coverage-endpoint true --generate-branches-endpoint true
Gradle location of JaCoCo report
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.
python3 -m jacoco_badge_generator --jacoco-csv-file build/reports/jacoco/test/jacocoTestReport.csv
Learn more
You can find additional information about the jacoco-badge-generator and other GitHub Actions that I've implemented on the following website:
Vincent Cicirello - Open source GitHub Actions for workflow automation
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:
Support the project
You can support the project in a number of ways:
- Starring: If you find this utility useful, consider starring the GitHub repository.
- Sharing with Others: Consider sharing it with others who you feel might find it useful.
- Reporting Issues: If you find a bug or have a suggestion for a new feature, please report it via the Issue Tracker.
- Contributing Code: If there is an open issue that you think you can help with, submit a pull request.
- Sponsoring: You can also consider sponsoring via one of the following:
| GitHub | Liberapay | Ko-Fi |
|---|---|---|
 |
 |
 |
Top comments (1)
If you want to see a live example of GitHub Action usage, I am using this in several repositories, including the following:
A Java library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms
Chips-n-Salsa - A Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive local search algorithms
Copyright (C) 2002-2022 Vincent A. Cicirello.
Website: chips-n-salsa.cicirello.org/
API documentation: chips-n-salsa.cicirello.org/api/
How to Cite
If you use this library in your research, please cite the following paper:
Overview
Chips-n-Salsa is a Java library of customizable, hybridizable, iterative, parallel, stochastic, and self-adaptive local search algorithms. The library includes implementations of several stochastic local search algorithms, including simulated annealing, hill climbers, as well as constructive search algorithms such as stochastic sampling. Chips-n-Salsa now also includes genetic algorithms as well as evolutionary algorithms more generally. The library very extensively supports simulated annealing…
The direct link to the workflow within the above repository where it is used is: github.com/cicirello/Chips-n-Salsa...