JUnit Integration (and similar)

Applies to Zephyr Scale Cloud, last modified on March 28, 2023.

JUnit is the de-facto test automation tool for Java. No matter if JUnit is used for writing unit or integration tests or even if another framework is used in conjunction with it - such as Selenium - the output results file can be uploaded to Zephyr Scale for generating reports and leveraging all the other capabilities. For more info on JUnit, see here.

This integration works with JUnit 4 and JUnit 5. Both versions of JUnit export the same results file format - an XML containing the test results. Additionally, any framework that is able to export such file type should be compatible with the API endpoint used in this integration.

Writing JUnit tests

JUnit tests are written in the form of Java classes and methods, for example:

public class CalculatorSumTest {

    public void JQA_T1_sumTwoNumbers() {
        Calculator calculator = new Calculator();
        assertEquals(5, calculator.sum(3, 2));

    public void JQA_T2_multiplyTwoNumbers() {
        Calculator calculator = new Calculator();
        assertEquals(4, calculator.multiply(2, 2));

    public void divideTwoNumbers() {
        Calculator calculator = new Calculator();
        assertEquals(2, calculator.divide(4, 2));

Note that the first two method names begin with JQA_T1 and JQA_T2. This particular prefix will map the result of each of those test methods to the corresponding test cases in Zephyr Scale if they exist, respectively test cases with key JQA-T1 and JQA-T2.

Also, note that the last method divideTwoNumbers is not prefixed with a test case key. Zephyr Scale will try to find an existing test case that matches the package, class and method name, in this case com.example.junit.CalculatorSumTest.divideTwoNumbers, and map the result of the test method to the test case. If these test cases don’t exist, an error will be returned when the results are uploaded to Zephyr Scale.

If any test case, prefixed with the test case key or not, is not found, an error will be returned when the results are uploaded to Zephyr Scale. In this case, if you intend to automatically create test cases that don’t exist previously, the query parameter autoCreateTestCases=true can be set when uploading test results to Zephyr Scale.

To summarize, the rules for matching a test method to a test case are:

  • Try to match by parsing a test case key from the test method name

  • If no test case is matched, then try to match a test case by using the method full qualified name

  • If no test case is matched, then:

    • If the parameter autoCreateTestCases is true, create the test case and create a new test execution for it

    • If the parameter autoCreateTestCases is false or not present, return an error - no test cases have been matched

Uploading results to Zephyr Scale

Once the JUnit tests have executed, the results can be uploaded to Zephyr Scale. There are two options for uploading test results:

  • Using a single JUnit XML results file

  • Using a zip file containing multiple JUnit XML results file

Both options work the same way and can be uploaded using the same API endpoint: https://support.smartbear.com/zephyr-scale-cloud/api-docs/#operation/createJUnitExecutions.

Below, an example using Curl of how to use the API endpoint for uploading one single file:

curl -H "Authorization: Bearer ${TOKEN}" -F "file=@TestSuites.xml;type=application/xml" https://api.zephyrscale.smartbear.com/v2/automations/executions/junit?projectKey="JQA"&autoCreateTestCases=true

…and for uploading a zip file containing multiple XML files:

curl -H "Authorization: Bearer ${TOKEN}" -F "file=@TestSuites.zip;type=application/x-zip-compressed" https://api.zephyrscale.smartbear.com/v2/automations/executions/junit?projectKey="JQA"&autoCreateTestCases=true

Note the query parameters on the URL. The projectKey specifies what project will be used to create the test cycle. The autoCreateTestCase will create a test case using the JUnit test method name when no matching test case is found.

Code samples

Here you can find a complete example of how to upload JUnit results to Zephyr Scale, using different JUnit features such as parameterised tests:


Highlight search results