Prevent code coverage regressions

pip install ccguard==0.7.2



CircleCI PyPI version CodeCoverageLicense: AGPL v3

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! in action so bad, a regression

trendsall the status badges


  • 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



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)


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?


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


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


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

alternatives to this software


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