Skip to content
This documentation applies to Codacy Self-hosted v3.4.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 our blog.

To set up coverage on Codacy you must complete these main steps:

  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 does not 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.

    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 Codacy repositories.

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

  1. Upload each separate report with the following flags:

    • --partial
    • -l <language>
    • -r <partial report>

  2. After uploading all reports, notify Codacy with the final command.

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

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

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 March 5, 2021