JUnit to easeTest Importer
- Support Advocate (ease solutions)
- David Sedlock
- Bernhard Doleschel
- Ron B. Bugay
Overview
The JUnit to easeTest 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 easeTest. 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.
Prerequisites
The importer requires Java 8, 9 or 11 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"
Example batch file “import.cmd”:
@echo off
REM %1: Jira project key (e.g. MYKJEY)
REM %2: Test plan name (e.g. Automated Tests)
REM %3: Execution Name in Jira (e.g. MYKEY#28-2023-01-01_12:00)
REM %4: Name of file with JUnit-formatted test results, use / instead of backslash
java -jar junit-to-test-for-jira-importer.jar --plan=%2 --project=%1 --url="https://myserver.com/jira/" --user="<username>" --pw="<password>" --xmlFilePath="%4" --xmlIssueKeyAttrName="jira-key" --execution=%3Example call of batch
import MYKEY "Automated Tests" "MYKEY#28-2024-05-13_12:00" "./result.xml"
Command Line Arguments
Argument | Explanation |
|---|---|
plan | The name of the default test plan in easeTest 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. |
token | Access token can be used instead of username/password for embedding process into automated imports. This is prioritized over user and pw arguments. |
xmlFilePath | The path to the JUnit XML result files. The path may contain wildcards to select multiple XML files for one import - for example:
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:
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 easeTest:
JUnit | easeTest |
|---|---|
no child elements | Passed |
error or failure element | Failed - if the test case is the last test case to be read. |
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 (Jira keys can be in uppercase, lowercase or mixed case):
<?xml version="1.0" encoding="UTF-8"?>
<testsuites>
<testsuite name="JUnitXmlReporter" errors="0" tests="0" failures="0" time="0" timestamp="2023-05-24T10:23:58" />
<testsuite name="JUnitXmlReporter.constructor" errors="0" skipped="1" tests="3" failures="1" time="0.006" timestamp="2023-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>
</testsuites>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.