ccguard

you can only improve! :-)

ccguard compares the current code coverage to past code coverage. ccguard fails unless your new code coverage is equal or better than your past code coverage!

requires

• python3 (on the server)
• git

how should you use this software

• setup the server
• define your code coverage exclusions and inclusions (in your test runner, not in ccguard)
• setup the CI workflow so that ccguard can (here for CircleCI)
  • ingest the code coverage report
  • send it to the server
  • ensure that the coverage improves
• (optional, but required for the following steps) download reports on your computer using ccguard_sync
• (recommended) inspect the git/reference log with ccguard_log
• (optional) display the code coverage for a specific commit with ccguard_show
• (optional) display the code coverage diff between two references with ccguard_diff

welcome beta testers: setup

# prepare the package and install it
./distrib.sh

contribute

./bootstrap.sh

please execute flake8, black, pytest and ccguard against all of your changes. (a pre-commit hook will ensure that everythng is fine before letting you commit)

./pre-commit

ccguard - the code coverage guard

cd your-favorite-source-folder
# execute unit tests, collecting code coverage here
ccguard coverage.xml
# change your code somehow
# execute unit tests, collecting code coverage
# then verify that your code coverage has not decreased
ccguard --consider-uncommitted-changes coverage.xml
# if you are rather a visual person, check cc.html and diff.html
ccguard --html --consider-uncommitted-changes coverage.xml
# if needed to display the line coverage for each file in the HTML report,
# fine tune the source files path with the --repository argument
ccguard--html --consider-uncommitted-changes coverage.xml --repository src/
# allow regressions up to 3%
ccguard coverage.xml --tolerance 3
# allow regressions up to 10%, but never descend below 70%
ccguard coverage.xml --tolerance 10 --hard-minimum 70
# use the web adapter (ie. send the data to ccguard_server).
# requires a ccguard.server.address setting in the config.
ccguard coverage.xml --adapter web

please see how to produce code coverage data in your favourite language.

display code coverage trends

What a better feedback loop than measuring the work you have accomplished?

ccguard_log

display code coverage report

You could be curious about how the code coverage looked like a few commits ago..

ccguard_show 7b43f26

display code coverage diff

And, you could be curious about how the code coverage has evolved between two commits.

ccguard_diff 3413af3 7b43f26

synchronize repositories

The use case being: you wish to use ccguard as pre-commit. Your team already has some references. Then you could be interested in sharing them.

# upload the report to a distant redis repository
ccguard_sync sqlite redis
# download the report from a distant redis repository
ccguard_sync redis sqlite
# limit to a single repository
ccguard_sync redis sqlite --repository_id abcd
# limit to a single repository and a single commit
ccguard_sync redis sqlite --repository_id abcd --commit_id ef12
# retrieve data from a specific web server, and display whats going on behind the scenes
ccguard_server_address=https://ccguard.nilleb.com ccguard_sync web sqlite --debug

launch a local server

ccguard_server allows you to centralize the reports and the regression checks (useful for CI workflows) also serves coverage and diff reports.

ccguard_server

You could be interested to know how to setup the server.

convert a report

Sometimes you need to convert a report from a format to another. ccguard_convert is here to help!

# convert the report from golang textual format to cobertura.xml
ccguard_convert golang-coverage-report.txt -if go -of xml -o output.xml

# convert the report from cobertura xml format to html (pycobertura)
ccguard_convert cobertura.xml -if xml -of html -o output.html

# convert the report from golang textual format to html (pycobertura)
ccguard_convert golang-coverage-report.txt -if go -of html -o output.html

# you can add a .ccguard.config.json in the same directory of the report or to your home directory to fine tune the exclusions
echo '{"convert.exclusions.go": ["**/config/default.go"]}' > .ccguard.config.json
# the report will not contain the files matching the glob expression
ccguard_convert golang-coverage-report.txt -if go -of xml -o output.xml

To know more about glob expressions, see man 3 fnmatch.

expose a status badge

Add the following Markdown to your README.md

[![CodeCoverage](https://ccguard.nilleb.com/api/v1/repositories/a8858db8a0d483f8f6c8e74a5dc03b84bc9674f8/status_badge.svg?branch=master)](https://ccguard.nilleb.com/web/main/a8858db8a0d483f8f6c8e74a5dc03b84bc9674f8)

(make sure that you change your repository_id to match the one printed by a ccguard --debug)

alternatives to this software

• opencov
• diff-cover
• codecov.io
• coveralls.io
• sonarqube

credits

• Alexandre Conrad for his wonderful pycobertura
• all the beta testers for their precious feedback