cvrg

A bash script for pushing coverage reports to cvrg.report during local test execution or test runs in CI/CD environments.

The goal of this script is to not having to install language-specific coverage reporter plugins, but using one standardized helper for all languages and environments.

Usage

Bash script location

The download link https://cvrg.report/bash redirects to the the master branch of the cvrg script on GitHub.

Dynamic download (CI/CD usage)

You can download the script for each run, for example when using CI/CD systems. The cvrg script needs to be executed after the coverage reports have been created. Exceptions are gcov and coverage.py based coverage reports, those are run by the script itself.

curl -s -o ./cvrg https://cvrg.report/bash && chmod +x ./cvrg && ./cvrg

Direct use of the dynamically downloaded script can be achieved like this:

bash <(curl -s -o- -L https://cvrg.report/bash)

Adding the uploader to your project

You can add the cvrg script to your development projects directly, e.g.

$ mkdir -p .cvrg && wget https://cvrg.report/bash -o .cvrg/cvrg && chmod +x .cvrg/cvrg

Then, you can use the script at cvrg/cvrg to pipe the test coverage output to, or use the automatic discovery of coverage reporting files below the project path.

Runtime configuration

The cvrg script can be configured by specifying command line arguments:

General options

The general seeting can by influenced by the following:

  -h          Show this help screen and exit
  -f          Fail with a exit code of 1 instead of 0
  -y path     Configuration YAML file path
  -u url      API endpoint base URL (default: https://api.cvrg.report)
  -t token    Project token (if not passed via YAML configuration file)
  -D feature  Disable features
  
              gcov        Disable gcov
              coveragepy  Disable coverage.py

curl options

For custom settings, like using proxies etc., the arguments for curl can be set accordingly:

  -c path     Path to your custom cacert.pem file
  -a "args"   Additional curl arguments

gcov options

The creation of gcov reports can be customized by the following flags:

  -i glob     Path to ignore while gathering reports
  -I glob     Path to include while gathering reports
  -e exe      Executable for gcov to use. Default is 'gcov'
  -g "args"   Additional gcov arguments

Project-related overrides

There are also flags which can be used to override the automatic discovery of project-related information:

  -R path     Project root path
  -B name     Branch name
  -C sha      Commit hash
  -M "msg"    Commit message
  -T tag      Tag name
  
  -n "name"   Custom name (will be filled automatically for known CIs)
  -j id       Job identifier
  -b id       Build identifier
  -l "labels" Labels for this run (comma-separated)
  -p "info"   Pull request information
  -s slug     Owner/Repo information

Debugging

The following arguments can be used for debugging purposes:

  -v        Verbose mode
  -d        Dump the gathered coverage report info (no upload)

CI support

The cvrg scripts supports the following CI providers out of the box:

• Travis CI
• Circle CI
• Codeship
• GitLab CI
• Shippable
• Drone CI
• Jenkins
• Teamcity
• Buddybuild
• Bamboo CI
• Bitrise
• Buildkite
• Heroku CI
• Codefresh
• Wercker
• Magnum CI
• Greenhouse CI
• AppVeyor
• Semaphore CI

Environment variables

The following environment variables can be set before running the cvrg script, which will then automatically pick up the data:

• CVRG_NAME: The name of the environment/service where the cvrg script is run
• CVRG_TOKEN: The repository token (can be found at https://cvrg.report/$REPO_HOST/$USER/$REPO/settings)
• CVRG_LABELS: The comma-separated list of labels for this upload

The $REPO_HOST can have the values

• gh for GitHub
• bb for BitBucket
• gl for GitLab

YAML configuration

You can create a configuration file with the name pattern *cvrg.y*ml somewhere in your project, and the cvrg script will automatically find it an will try to read the configuration values from it.

The following configuration details are supported:

• cvrg_name: The name of the environment/service where the cvrg script is run
• cvrg_token: The repository token (can be found at https://cvrg.report/$REPO_HOST/$USER/$REPO/settings)
• cvrg_labels: The comma-separated list of labels for this upload

Please consider that if your project is publicly accessible, the specified upload token is visible to the public as well!

Example configuration file

cvrg_token: tsdjfsoifjojsoidjhfo23ioshfo
cvrg_slug: test/test
cvrg_labels: frontend,integration

Please note: Configuration parameters passed either via environment variable or flag will take precedence over the configuration file.