Overview

The JUnit to Test for Jira Importer tool allows you to import the results from the execution of JUnit tests to the executions of one or more test plans in T4J. The application is able to read multiple XML files at once and map the contained test cases to the Jira issues of the corresponding test plans. The application then creates a new execution for each test plan and sets the status of the included test cases according to that of the corresponding JUnit test execution.

1 Overview
2 Prerequisites
3 Execution
4 Command Line Arguments
5 JUnit Test Result XML File
6 Result Messages
7 Customizing Result Messages

Prerequisites

The importer requires Java 8 or newer to be installed on the machine that runs the application. To verify the version of Java, open a new terminal and execute the following command:

java -version

The application itself is a single self-contained jar-file that must be downloaded: JUnit to Test for Jira Importer.

Execution

To execute the application, open a new command line terminal in the directory that contains the application jar file and enter the following command:

java -jar junit-to-test-for-Jira-importer.jar [arguments]

The arguments that can be passed are of the following form:

--argumentName="value"

Here is an example:

java -jar junit-to-test-for-Jira-importer.jar --plan="JUnit Tests" --project="FIR" --url="http://myhost:2990/Jira/" --user="admin" --pw="adminpw" --xmlFilePath="D:/JUnit Results/results*.xml" --xmlIssueKeyAttrName="JiraIssueKey" --execution="JUnit Test Import Execution"

Command Line Arguments

Argument	Explanation

Argument	Explanation
plan	The name of the default test plan in T4J for which the new execution is to be created. This argument is optional if the xmlPlanNameAttrName argument is provided.
project	The key of the Jira project that contains the test plan.
url	The base-URL of the Jira instance, which should be of the following form: http(s)://host:port/Jira/.
user	The username of the user account that is used to create the new execution.
pw	The corresponding password for the user account.
xmlFilePath	The path to the JUnit XML result files. The path may contain wildcards to select multiple XML files for one import - for example: `D:\Test Results\JUnit\result*.xml` Only XML files are supported. Trying to pass a path to a different file type results in an error.
xmlIssueKeyAttrName	The name of the "testcase" element attribute in the XML files that contain the corresponding issue key for each test case.
xmlPlanNameAttrName	The name of the "testcase" element attribute in the XML files that contain the corresponding plan name for each test case. This argument is optional if the plan argument is provided.
execution	The name of the new execution.
resultXsltPath	The path to an XSL file, which is used to transform the content of the XML files into result messages for failed test executions. This argument is optional. If no path is specified the default XSL file provided with the importer is used.
version	Use this argument without any value and without other arguments to return the version of the application. If any other arguments are used, the application starts as usual.
testMode	Use this argument with an arbitrary value to start the application in test mode. In this mode the application does not import anything, but instead checks the following conditions: whether the Jira instance can be accessed via the specified url whether the passed user credentials are correct whether the project with the specified project key exists in the Jira instance whether the plan with the specified plan name exists in the project To use the test mode all other arguments except version must be specified.

JUnit Test Result XML File

The JUnit test result XML file should contain one or more test cases. Every test case element must have an attribute containing the Jira key of a test issue. The name of this attribute is specified using the xmlIssueKeyAttrName argument. A test case is ignored if the specified test plan does not include the corresponding Jira issue key. There should be no more than one test case in the file with the same issue key.

A test case can have an optional attribute providing the intended test plan and is specified using the xmlPlanNameAttrName argument. If this argument is not provided, the intended plan must be specified using the plan argument.

A test case can contain a skipped, error or failure element - or no child elements at all. The following table explains how JUnit test results are translated into T4J:

JUnit	T4J

JUnit	T4J
no child elements	Passed
error or failure element	Failed - if the test case is the last test case to be read. Failed Continue - if more test cases follow.
skipped	Skipped test cases are currently ignored.

The following example of a test results file provides results for three Jira issues, identified as FIR-1, FIR-2 and FIR-3:

<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
    <testsuite name="JUnitXmlReporter" errors="0" tests="0" failures="0" time="0" timestamp="2013-05-24T10:23:58" />
    <testsuite name="JUnitXmlReporter.constructor" errors="0" skipped="1" tests="3" failures="1" time="0.006" timestamp="2013-05-24T10:23:58">
        <properties>
            <property name="java.vendor" value="Sun Microsystems Inc." />
            <property name="compiler.debug" value="on" />
            <property name="project.jdk.classpath" value="jdk.classpath.1.6" />
        </properties>
        <testcase classname="JUnitXmlReporter.constructor" name="should default path to an empty string" time="0.006" JiraIssueKey="FIR-3">
            <failure message="test failure">Assertion failed</failure>
        </testcase>
        <testcase classname="JUnitXmlReporter.constructor" name="should default consolidate to true" time="0" JiraIssueKey="FIR-1">
            <skipped />
        </testcase>
        <testcase classname="JUnitXmlReporter.constructor" name="should default useDotNotation to true" time="0" JiraIssueKey="FIR-2" JiraPlanName="Demo Plan"/>
    </testsuite

Result Messages

By default, the message created by the importer consists of the following two elements:

Result message: If the error or failure element of the test case contains an attribute named “message” the value of this attribute is part of the result message.
Detailed error information: This part of the message contains the entire body of the error or failure element. The detailed error information is part of the result message.

Currently a result message is only created for failed test cases.

Customizing Result Messages

You can customize result messages by providing a custom XSL file to the importer using the resultXsltPath argument.

The following simple XSL file causes the same result message to be produced, consisting of the java version as stated in the result XML file.

<xsl:template match="testsuite">
Environment ------
Java Version : <xsl:value-of select="properties/property[@name = 'java.version']/@value
</xsl:template>

To create test case specific result messages, you can use the following two parameters in the XSL file to find the corresponding test case element:

issueKey: The corresponding issue key of the test case currently being imported.
xmlIssueKeyAttrName: The name of the testcase attribute that contains the issue key of the corresponding Jira issue

The importer uses the corresponding values for the test case currently being imported. You can use the following code block to retrieve the test case element from the XML result file for the test case currently being imported.

<xsl:param name="issueKey" />
<xsl:param name="xmlIssueKeyAttrName" />
<xsl:template match="testsuite">
    <xsl:for-each select="testcase/attribute::*[name() = $xmlIssueKeyAttrName and .= $issueKey]">
		<!-- Your code goes here -->
	</xsl:for-each>
</xsl:template>

T4J - Test Management for Jira

JUnit to T4J Importer