Skip to content
This documentation applies to Codacy Self-hosted v4.2.0

For the latest updates and improvements, see the latest Cloud documentation instead.

Adding coverage to your repository#

Code coverage is a metric used to describe the degree to which the source code of a program is tested. A program with high code coverage has been more thoroughly tested and has a lower chance of containing software bugs than a program with low code coverage. You can read more about the basics of code coverage on Codacy's blog.

Complete these main steps to start monitoring the test coverage of your repositories on Codacy:

  1. Generating coverage reports

    Ensure that you're generating one of the test coverage report formats supported by Codacy on each push to your repository.

  2. Uploading coverage data to Codacy

    After each push to your repository, run the Codacy Coverage Reporter to parse your report file and upload the coverage data to Codacy.

The next sections include detailed instructions on how to complete each step of the setup process.

1. Generating coverage reports#

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.

There are many tools that you can use to generate coverage reports for the languages used in your repositories. The following table contains example coverage tools that generate reports in formats that Codacy supports:

Language Example coverage tools Report files
C# OpenCover opencover.xml (OpenCover)
dotCover CLI dotcover.xml (dotCover detailedXML)
Go Golang Code Coverage Golang report files don't have a specific name. Because of this, later in the setup process you must follow specific instructions while submitting coverage to Codacy.
Java JaCoCo jacoco*.xml (JaCoCo)
Cobertura cobertura.xml (Cobertura)
JavaScript Istanbul
Poncho
Mocha + Blanket.js		 lcov.info, lcov.dat, *.lcov (LCOV)
PHP PHPUnit coverage-xml/index.xml (PHPUnit XML version <= 4)
clover.xml (Clover)
Python Coverage.py cobertura.xml (Cobertura)
Ruby SimpleCov cobertura.xml (Cobertura)
lcov.info, lcov.dat, *.lcov (LCOV)
Scala sbt-jacoco jacoco*.xml (JaCoCo)
scoverage cobertura.xml (Cobertura)
Swift/Objective-C Xcode Code Coverage See below how to generate coverage reports with Xcode

Submitting coverage from unsupported report formats#

If you're generating a report format that Codacy doesn't support yet, contribute with a parser implementation yourself or use one of the community projects below to generate coverage reports in a supported format:

As a last resort, you can also send the coverage data directly by calling one of the following Codacy API endpoints:

2. Uploading coverage data to Codacy#

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 push to your repository.

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

    • If you're setting up coverage for one repository, obtain a project API token and set the following environment variable to specify your project API token:

      export CODACY_PROJECT_TOKEN=<your project API token>

    • If you're setting up and automating coverage for multiple repositories, obtain an account API Token and set the following environment variables:

      • CODACY_API_TOKEN: Your account API token.

      • CODACY_ORGANIZATION_PROVIDER: Git provider hosting the repository.

        Must be one of gh, ghe, gl, gle, bb, or bbe to specify GitHub, GitHub Enterprise, GitLab, GitLab Enterprise, Bitbucket, or Bitbucket Enterprise, respectively.

      • CODACY_USERNAME: Name of your organization on the Git provider, or your username on the Git provider if you're using a personal organization.

      • CODACY_PROJECT_NAME: Name of the repository for which you're uploading the coverage information.

      export CODACY_API_TOKEN=<your account API token>
export CODACY_ORGANIZATION_PROVIDER=<Git provider hosting the repository>
export CODACY_USERNAME=<organization name or username on the Git provider>
export CODACY_PROJECT_NAME=<repository name>

    Warning

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

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

  2. If you're 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 on the root of the locally checked out branch of your Git repository, specifying the relative path to the coverage report to upload:

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

    Tip

    The recommended self-contained script automatically downloads and runs the most recent version of Codacy Coverage Reporter.

    See alternative ways of running Codacy Coverage Reporter for other ways of running Codacy Coverage Reporter, such as by installing the binary manually or using a GitHub Action or CircleCI Orb.

  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, or check the troubleshooting page if you found an issue during the setup process.

Uploading multiple coverage reports for the same language#

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

To do this, specify multiple reports by repeating the flag -r. For example:

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

You can also upload all your reports dynamically using the command find. For example:

bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
    -l Java $(find **/jacoco*.xml -printf '-r %p ')

Note

Altenatively, you can upload each report separately with the flag --partial and notify Codacy with the final command after uploading all reports. For example:

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

If you're 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.

Submitting coverage for Golang#

Codacy can't automatically detect Golang coverage report files because they don't have specific file names.

If you're uploading a Golang coverage report, you must also specify the report type:

bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
    --force-coverage-parser go -r <coverage report file name>

Submitting coverage for unsupported languages#

If your language is not in the list of supported languages, you can still send coverage to Codacy. You can do it by providing the correct language name with the flag -l, together with --force-language. For example:

bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
  -l Kotlin --force-language -r <coverage report file name>

See the list of languages that you can specify using the flag -l.

Commit SHA hash detection#

The Codacy Coverage Reporter automatically detects the commit SHA hash to associate with the coverage data from the following CI/CD platforms:

  • Appveyor
  • Azure Pipelines
  • 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

If the Codacy Coverage Reporter fails to detect the current commit from the CI workflow context, it will use the current commit from the local Git repository instead.

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 \
    -r report.xml \
    --commit-uuid cd4d000083a744cf1617d46af4ec108b79e06bed

Share your feedback 📢

Did this page help you?

Thanks for the feedback! Is there anything else you'd like to tell us about this page?

We're sorry to hear that. Please let us know what we can improve:

Alternatively, you can create a more detailed issue on our GitHub repository.

Thanks for helping improve the Codacy documentation.

If you have a question or need help please contact support@codacy.com.

Last modified August 18, 2021