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

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)
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

Tip

To use Swift and Objective-C with Xcode coverage reports, use Slather to convert the Xcode output into the Cobertura format.

To do this, execute the following commands on the CI:

gem install slather
slather coverage -x --output-directory <report-output-dir> --scheme <project-name> <project-name>.xcodeproj

This will generate a file cobertura.xml inside the folder <report-output-dir>.

Note

If you're generating a report format that Codacy doesn't support yet, see submitting coverage from unsupported report formats.

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 to specify the account API token, the username associated with the account API token, and the repository for which you're uploading the coverage information:

      export CODACY_API_TOKEN=<your account API token>
export CODACY_ORGANIZATION_PROVIDER=<the repository provider>
export CODACY_USERNAME=<the repository owner username>
export CODACY_PROJECT_NAME=<the 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. For example:

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

    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.

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 April 21, 2021