cuvner on Pull Requests

December 13, 2024

My tool “cuvner” (aka cuv) has mostly morphed into a command-line aid for looking at coverage data.

It turns out that GitHub Actions steps can more-or-less properly render ANSI escapes, making it useful there too.

It further turns out that GitHub Actions can produce a “summary” text (although IMO it’s buried behind too many clicks to be as useful as it could be).

Here, we show you how to use “cuv” to enhance your Python-language Pull Requests(tm) with additional information – no pesky third-party coverage services required!

The Promise

Part of a terminal, showing a diff that at least one added line is coloured red because it was not covered by a unit-test

You get to see the coverage of your pull-request locally, quickly and reliably.

I personally find “git diff main | cuv diff -” (shown above) to be a super useful aid in my programming: it immediately tells me what stuff in my branch remains un-tested. The alternative is to push to a branch, create a Pull Request, await Continuous Integration, hope that the selected “coverage SaaS” service works, and then hope I believe the results.

There are other tools in Cuvner besides the above, all various forms of terminal visualizations of coverage data.

Okay, Neat, Lets Do It Remotely Too!

Many modern CI runners can now render ANSI colour escape sequences properly, including GitHub Actions.

So, this means that we can also run the same tool in CI. This means no external dependency on a service like Coveralls.io.

Here’s an actual Pull Request #39 in Fowl showing this in action.

Part of a web browser showing the results of a pull-request run, with ANSI coloured cuv-ner terminal output

The configuration to run cuv-ner in GitHub Actions is fairly straightforward:

- name: PR Coverage Graph
  shell: bash
  run: git diff origin/main..HEAD | cuv diff -
  continue-on-error: true

You can also make a shorter “report”:

- name: Coverage report
  shell: bash
  run: |
      git diff origin/main..HEAD > p
      cuv report p
  continue-on-error: true

…or, use the GitHub summary information (although I personally find this to be “too many clicks” to get to) in most actual PRs. But if you’re already putting information there, great!

- name: Coverage summary
  shell: bash
  run: |
      git diff origin/main..HEAD > p
      echo "Coverage" > $GITHUB_STEP_SUMMARY
      echo "--------" >> $GITHUB_STEP_SUMMARY
      cuv report p >> $GITHUB_STEP_SUMMARY
  continue-on-error: true

Installing on GitHub Actions

These days, pip install --user cuvner will often work. On GitHub actions, you’re usually already installing some sort of Python, so adding cuvner to your requirements, or pip install cuvner as a “Step” is all that’s required. For example:

- name: Set up Python ${{ matrix.python-version }}
  uses: actions/setup-python@v2
  with:
    python-version: ${{ matrix.python-version }}
- name: Install dependencies
  run: |
    pip install cuvner

Edited: December 14, 2024: move some sections around, add more example configuration.