Skip to content
This documentation applies to Codacy Self-hosted v8.1.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 code coverage of your repositories on Codacy:

  1. Generating coverage reports

    Ensure that you're generating one of the code 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)
Coverlet Make sure that you output the report files in a supported format using one of the following file names:
opencover.xml (OpenCover)
cobertura.xml (Cobertura)
lcov.info, lcov.dat, *.lcov (LCOV)
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
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>

    Check the console output to validate that the Codacy Coverage Reporter detected the correct commit UUID and successfully uploaded the coverage data to Codacy. If you need help, check the troubleshooting page for solutions to the most common setup issues.

    Tip

    The self-contained script get.sh 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.

    Be sure to also check the sections below for more advanced functionality while uploading the coverage data to Codacy.

  4. Make sure that Codacy received the coverage data successfully for the correct commit UUID and branch. On Codacy, open your Repository Settings, tab Coverage, and expand the list of recent coverage reports in the section Test your integration:

    Testing the coverage integration

    If you make adjustments to your setup and upload new coverage data, click the button Test integration to refresh the table.

To validate that the coverage setup is complete, wait until your repository has at least two new commits and check that Codacy displays the coverage information on the last commit or in subsequent pull requests, either as a positive, negative, or no variation (represented by =) of the coverage percentage:

Coverage data displayed on Codacy

Follow these troubleshooting steps if Codacy doesn't display the coverage data for your commit or pull request (represented by -).

Uploading multiple coverage reports for the same language#

If your test suite is split on different modules or runs in parallel, you must 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 -name 'jacoco*.xml' -printf '-r %p ')

Note

Alternatively, you can:

  1. Upload each report separately with the flag --partial
  2. 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.

Uploading the same coverage report for multiple languages#

If your test suite generates a single coverage report for more than one language, you must upload the same coverage report for each language.

To do this, upload the same report multiple times, specifying each different language with the flag -l. For example:

bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
    -l Javascript -r report.xml
bash <(curl -Ls https://coverage.codacy.com/get.sh) report \
    -l TypeScript -r report.xml

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.

To do this, provide the correct language 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.

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 June 16, 2022