DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

Cover image for The jacoco-badge-generator GitHub Action is now also available as a CLI tool from PyPI
Vincent A. Cicirello
Vincent A. Cicirello

Posted on • Updated on

The jacoco-badge-generator GitHub Action is now also available as a CLI tool from PyPI

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 GitHub repository includes the source code, as well as more detailed documentation including additional examples:

GitHub logo cicirello / jacoco-badge-generator

Coverage badges, and pull request coverage checks, from JaCoCo reports in GitHub Actions

jacoco-badge-generator

cicirello/jacoco-badge-generator - Coverage badges, and pull request coverage checks, from JaCoCo reports in GitHub Actions

Check out all of our GitHub Actions: https://actions.cicirello.org/

About

GitHub Actions GitHub release (latest by date) Count of Action Users
Command-Line Utility PyPI
Build Status build CodeQL
Security Snyk security score
Source Info License GitHub top language
Support GitHub Sponsors Liberapay Ko-Fi

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:

GitHub logo 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'
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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)

favicon pypi.org

Installing the CLI utility from PyPI

To install from PyPi (Unix and MacOS):

python3 -m pip install jacoco-badge-generator
Enter fullscreen mode Exit fullscreen mode

To install from PyPi (Windows):

py -m pip install jacoco-badge-generator
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Generating instructions coverage and branches coverage badges

python3 -m jacoco_badge_generator --generate-branches-badge true
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

favicon 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
GitHub Sponsors Liberapay Ko-Fi

Top comments (1)

Collapse
cicirello profile image
Vincent A. Cicirello Author

If you want to see a live example of GitHub Action usage, I am using this in several repositories, including the following:

GitHub logo cicirello / Chips-n-Salsa

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

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/

Publications About the Library DOI
Packages and Releases Maven Central GitHub release (latest by date)
Build Status build docs CodeQL
JaCoCo Test Coverage coverage branches coverage
Security Snyk security score Snyk Known Vulnerabilities
DOI DOI
License GitHub

How to Cite

If you use this library in your research, please cite the following paper:

Cicirello, V. A., (2020). Chips-n-Salsa: A Java Library of Customizable, Hybridizable, Iterative, Parallel, Stochastic, and Self-Adaptive Local Search Algorithms. Journal of Open Source Software, 5(52), 2448, doi.org/10.21105/joss.02448 .

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...

🌚 Friends don't let friends browse without dark mode.

Sorry, it's true.