Skip to content

Adding coverage to your repository

Before setting up Codacy to display code coverage metrics for your repository you must have tests and use tools to generate coverage reports for the languages in your repositories. If you need help on getting started see how to generate coverage reports.

Codacy supports the following coverage report formats:

Report format Report file name
Clover clover.xml
Cobertura cobertura.xml
dotCover XML dotcover.xml
JaCoCo jacoco*.xml
LCOV lcov.info, lcov.dat, *.lcov
OpenCover opencover.xml
PHPUnit XML (version <= 4) coverage-xml/index.xml

Note

If you are generating a report format that Codacy does not yet support, see submitting coverage from unsupported report formats.

After having coverage reports set up for your repository, you must use Codacy Coverage Reporter to convert the reports to smaller JSON files and upload these files to Codacy. The recommended way to do this is using a CI/CD platform that automatically runs tests, generates coverage, and uses Codacy Coverage Reporter to upload the coverage report information for every commit.

  1. Set up an API token to allow Codacy Coverage Reporter to authenticate on Codacy.

    Obtain the project API Token from the page Integrations in your Codacy repository settings. Then, set the following environment variable to specify your project API Token:

    export CODACY_PROJECT_TOKEN=<your project API Token>
    

    Warning

    Never write API Tokens on your configuration files and keep your API Tokens well protected, as they grant owner permissions to your projects.

    We recommend that you set the API Tokens as environment variables. Check the documentation of your CI/CD platform on how to do this.

  2. If you are using Codacy Self-hosted set the following environment variable to specify your Codacy instance URL:

    export CODACY_API_BASE_URL=<your Codacy instance URL>
    
  3. Run Codacy Coverage Reporter to upload the coverage results to Codacy.

    The recommended way to do this is using a self-contained script that automatically downloads and runs the most recent version of Codacy Coverage Reporter:

    bash <(curl -Ls https://coverage.codacy.com/get.sh) report
    

    See alternative ways of running Codacy Coverage Reporter for other ways of running Codacy Coverage Reporter, such as when using Circle CI or GitHub actions, or to install the binary manually.

  4. Optionally, add a Codacy badge to the README of your repository to display the current code coverage.

See the sections below for more advanced functionality.

Uploading multiple coverage reports for the same language

If your test suite is split in different modules or runs in parallel, you will need to upload multiple coverage reports for the same language.

To do this, upload each separate report with the flags --partial, -l (to specify the language), and --coverge-reports (to specify each partial report). Then, after all reports were uploaded, notify Codacy with the final command. For example:

bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
    -l Java -r report1.xml --partial
bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
    -l Java -r report2.xml --partial
bash <(curl -Ls https://coverage.codacy.com/get.sh) final

Important

If you are sending reports for a language with the flag --partial, you should use the flag in all reports for that language to ensure the correct calculation of the coverage.

Tip

It might also be possible to merge the reports before uploading them to Codacy, since most coverage tools support merge/aggregation. For example, http://www.eclemma.org/jacoco/trunk/doc/merge-mojo.html.

Commit SHA hash detection

Codacy Coverage Reporter automatically detects the commit SHA hash to associate with the coverage data from several sources, in the following order:

  1. CI workflow context

    Codacy Coverage Reporter supports the following CI/CD platforms:

    • Appveyor
    • Bitrise
    • Buildkite
    • Circle CI
    • Codefresh
    • Codeship
    • Docker
    • GitLab
    • Greenhouse CI
    • Heroku CI
    • Jenkins
    • Magnum CI
    • Semaphore CI
    • Shippable CI
    • Solano CI
    • TeamCity CI
    • Travis CI
    • Wercker CI
  2. Git repository directory

    If Codacy Coverage Reporter finds a Git repository directory it will use the current commit.

However, you can also force using a specific commit SHA hash with the flag --commit-uuid. For example:

bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
    --commit-uuid cd4d000083a744cf1617d46af4ec108b79e06bed
Last update: September 30, 2020