This guide will show you how to upload a JaCoCo XML file to Teamscale that contains code coverage for your tests.

Depending on the configuration, JaCoCo will output a binary .exec file when run. This file does not contain all the information needed by Teamscale to process the coverage. You first need to convert it to JaCoCo's XML format, e.g. with the corresponding ANT task or Maven Pendant. The rest of this guide assumes that you have an XML file.


How often would you like to upload coverage?

  • I'd like to do a one-time manual upload of coverage (e.g. to check if the coverage is as expected or during an evaluation of Teamscale): See section Manual Upload via UI
  • I'd like an automated upload e.g. in regular intervals or during my continuous integration build


Manual Upload via UI

If you'd like to quickly get a first report into Teamscale, use the Projects UI for this. If you'd like to automate upload of coverage results, please consult the following sections instead.

  1. Go to Projects
  2. Select "External-Analysis Upload" for your project:
  3. Click on "Upload Report"
  4. Select your XML file
  5. Enter a custom message for your upload (arbitrary text that is shown in the UI), e.g. "Unit Test Coverage"
  6. Select the branch of the code commit for which you generated coverage
  7. Select the date of the code commit for which you generated coverage
  8. Select format JaCoCo
  9. Set any partition (unique ID for this type of coverage), e.g. "Unit Tests"


Upload via REST API

In order to upload coverage results to Teamscale, you need to have a server on which the following criteria are met:

  • Coverage result files (XML format) are available
  • Access to the running Teamscale server via HTTP is possible

As a first step, create a new user which will be able to upload coverage results to Teamscale. You can either use your administration account for this, or better use a special user with the "Build" role. 


To upload one or more XML coverage files to Teamscale, issue the following HTTP request:


  • HTTP method: POST
  • URL: http://<YOUR_TEAMSCALE_SERVER>:<PORT>/p/<TEAMSCALE_PROJECT_ID>/external-report?format=JACOCO&partition=<PARTITION>&message=<MESSAGE>
    • YOUR_TEAMSCALE_SERVER:PORT is the address and port of the Teamscale instance
    • TEAMSCALE_PROJECT_ID is the ID of the Teamscale project into which to store the coverage
    • PARTITION is a logical name for the type of coverage. All coverage with the same partition will be grouped together. This, e.g. allows you to upload both coverage for your Java and your JavaScript tests without the results of one overriding those of the other. The name is descriptive and can be any arbitrary string.
    • MESSAGE is the message shown in the Activity perspective to the user. It should make clear that coverage was uploaded.
  • Content-type: application/x-www-form-urlencoded
  • Body: Form data. May contain any number of elements with name "report" and the content of a single coverage XML file.
  • Authentication: HTTP Basic Authentication with the build or admin user and their Access Token (not their password!)


Example curl invocation: 


curl -X POST -ubuild:arka9a78l0araklra87 -Freport=@coverage.xml "http://teamscale-server:8080/p/myProject/external-report?format=JACOCO&partition=Unit%20Tests&message=Unit%20Test%20Coverage"


Note that the uploaded coverage will be used for the current HEAD commit in Teamscale on the main branch. Should this not be the behaviour you want, you can override this by adding the following to the request's URL:

&t=<BRANCHNAME>:<TIMESTAMP>


This will cause Teamscale to store the coverage for the code on given branch at the given Java Unix timestamp (Epoch time in milliseconds).



Upload via Python Client

In order to upload coverage results to Teamscale, you need to have a server on which the following criteria are met:

  • Coverage result files (XML format) are available
  • Access to the running Teamscale server via HTTP is possible
  • Python must be installed
  • Python pip must be able to download packages

As a first step, create a new user which will be able to upload coverage results to Teamscale. You can either use your administration account for this, or better use a special user with the "Build" role. 


Install the Teamscale Python client. It contains a short example of how to upload Unit Test Coverage. Modify the settings in this example script for your particular setup.

Be sure to change the coverage format in the Example to "JACOCO"!


Please also use the Access Token, not the password of the user!


Caveats