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.

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

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

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?

255 characters left

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

255 characters left

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 September 30, 2020