| Chapter 12. Import/Export | ||
|---|---|---|
|
 |
|
| Chapter 12. Import/Export | ||
|---|---|---|
|
|
|
|
Table of Contents
Klaros-Testmanagement provides several interfaces to import data from other tools and export its data into several formats.
User authentication is mandatory for all import operations. The user role required varies with the type of data being imported. For importing test results, the Tester role is sufficient as for requirements and test cases the Manager role is required.
![[Important]](images/important.png) |
LDAP Authentication |
|---|---|
| .
If the setting Login default is enabled in the LDAP configuration, then authentication is done exclusively via the LDAP directory. Local authentication information is always ignored in this case. |
Klaros-Testmanagement allows importing of test cases from Excel sheets structured in a predefined format which will be further detailed in Section 12.1.1, “Import Format”.
In addition to the standard fields provided for test cases, users of the Klaros-Testmanagement Enterprise Edition are also able to import data for user-defined fields. For this it is necessary to prepare the project according to what is listed in Section 12.1.2, “Prerequisites”.
The import interface consists of a simple REST interface which can be accessed by command line tools as well as custom applications. This is further detailed in Section 12.1.3, “Execution”.
The Excel sheet used to import test cases has to follow this strict format:
Each test case is located on a separate sheet.
Each sheet is divided into three sections: general properties, test case steps and custom properties.
The fields A:1 to A:22 are reserved for the standard attributes of a test case. The corresponding values are entered in the fields B:1 to B:22. It is not mandatory to fill all fields.
Column G is for the names of any number of user-defined properties. In column H the corresponding values are entered.
The Step field in cell A:25 must remain.
Changing or deleting the A:25 field will cause the import of this table to be rejected.
From here the definition of the test steps begins:
Column A for the test step number,
Column B for the action,
Column C for the precondition,
Column D for the postcondition and
Column E for the expected result.
The table below lists the cell coordinates for the general test case properties. The test case ID does not have to be specified. The ID is generated during the import. None of these values are mandatory. Some fields can take only predefined values which are listed there.
|
Coordinate |
Value |
|---|---|
|
B2 |
Name |
|
B3 |
Revision (only used in export) |
|
B5 |
Description |
|
B6 |
Precondition |
|
B7 |
Postcondition |
|
B8 |
Expected Result |
|
B10 |
Note |
|
B11 |
Area ( |
|
B12 |
Design Method ( |
|
B13 |
Variety ( |
|
B14 |
Execution ( |
|
B15 |
Priority ( |
|
B16 |
State ( |
|
B17 |
Team |
|
B18 |
Level ( |
|
B19 |
Document Base |
|
B20 |
Dependency |
|
B21 |
Evaluation |
|
B22 |
Traceability |
Table 12.1. General Property Coordinates
Test cases may contain a variable number of test steps. These are listed one per row starting from cell A:26 downwards. The import parser will stop reading steps once it encounters an empty step number.
|
Coordinate |
Value |
|---|---|
|
A26 (ff) |
Step Number |
|
B26 (ff) |
Action |
|
C26 (ff) |
Precondition |
|
D26 (ff) |
Postcondition |
|
E26 (ff) |
Expected Result |
Table 12.2. Test Step Coordinates
Only available in Klaros-Testmanagement Enterprise Edition
Test cases may contain custom properties. These may be listed as name/value pairs starting from cell G1 downwards.
For the import to succeed, the names of the listed properties must match with user defined properties defined for the project targeted by the import.
The value field for enumeration properties must exactly match the name of the enumeration property value definition to be parsed.
If an empty name cell is found, processing stops.
|
Coordinate |
Value |
|---|---|
|
G1 (ff) |
Property name |
|
H1 (ff) |
Property value |
Table 12.3. Custom Property Coordinates
To import Excel based test cases the following prerequisites have to be met:
The file that is going to be imported has to be XLS or XLSX format.
The project that should contain the imported test cases has to be already created.
If user defined properties (only available in Klaros-Testmanagement Enterprise Edition) are to be imported they have to be created for the project prior to starting the import process.
To import Excel-based test cases a REST interface is available which allows you to upload your data from the command-line or other applications.
The following example shows how to import an Excel sheet containing test cases into the project named P00001 using the curl command line application. Curl should be available in every Linux distribution and as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html for the Microsoft Windows operating system family.
|
Incompatible Windows Powershell curl Alias |
|---|---|
|
Windows Powershell also defines an alias named curl which also can be used for this purpose but takes a completely different set of arguments. If you prefer to use the Linux compatible curl executable under Powershell, use curl.exe instead of curl. |
curl -v -T TestCases.xls "<klaros-app-url>/seam/resource/rest/import/testcase/xls?config=P00001\ &username=user&password=secret"
Example 12.1. Excel Test Case Import via Command Line
![[Note]](images/note.png) |
ID Format |
|---|---|
|
All objects which are referenced during import (like projects or test cases) contain five digits in their id. For example, P00001 is a valid project ID, while P0001 and P000001 are not. |
Klaros-Testmanagement allows importing of test cases from XML Files. The import process will always create new instances of the supplied test cases for each invocation.
The format of the XML file is described in Appendix C, Test Case Import File Specification. The XML schema is available at the following URL: https://www.klaros-testmanagement.com/files/schema/klaros-testcases-1.0.xsd.
To import XML based test cases the following prerequisites have to be met:
The file that is going to be imported has to in XML format.
The project that should contain the imported test cases has to be already created.
If user defined properties are to be imported, they have to be created in the project prior to starting the import process.
To import XML-based test cases a REST interface is available which allows you to upload your data from the command-line or other applications.
The following example shows how to import an XML file containing test cases into the project named P00001 using the curl command line application. Curl should be available in every decent Linux distribution and as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html for the Microsoft Windows operating system family.
curl -v -T TestCases.xml "<klaros-app-url>/seam/resource/rest/import/testcase/xml?config=P00001\ &username=user&password=secret"
Example 12.2. XML Test Case Import via Command Line
In order to correctly import requirements from Excel spreadsheets, the data must exist in a specified format. This format is described in detail in the following section Section 12.1.1, “Import Format”.
In addition to the standard fields provided for requirements, users of the Klaros-Testmanagement Enterprise Edition are also able to import data for user-defined fields. For this it is necessary to prepare the project accordingly. You can find more information about this at Section 12.1.2, “Prerequisites”.
The import interface consists of a simple REST interface which can be accessed by command line tools as well as custom applications. This is further detailed in Section 12.1.3, “Execution”.
The Excel sheet used to import requirements has to follow this strict format:
Each requirement is located on a separate sheet.
Each sheet is divided into two sections: general properties and custom properties.
The fields A:1 to A:9 are reserved for the standard attributes of a requirement. The corresponding values are entered in the fields B:1 to B:9. It is not mandatory to fill all fields.
Column G is for the names of any number of user-defined properties. In column H the corresponding values are entered.
The table below lists the cell coordinates for the general requirement properties. None of these values are mandatory. Some fields can take only predefined values which are listed there.
|
Coordinate |
Value |
|---|---|
|
B1 |
ID (only used in export) |
|
B2 |
Name |
|
B3 |
Revision (only used in export) |
|
B5 |
Summary |
|
B6 |
Description |
|
B8 |
Priority
( |
|
B9 |
State
( |
Table 12.4. General Property Coordinates
Requirements may contain custom properties. These may be listed as name/value pairs starting from cell G1 downwards.
For the import to succeed, the names of the listed properties must match with user defined properties defined for the project targeted by the import.
The name in the name column must exactly match the name of a user defined property for a value to be parsed correctly. The parsing stops once an empty name cell has been found. The value field for enumeration properties must exactly match the name of the enumeration property value definition to be parsed.
|
Coordinate |
Value |
|---|---|
|
G1 (ff) |
Property name |
|
H1 (ff) |
Property value |
Table 12.5. Custom Property Coordinates
To import Excel based requirements the following prerequisites have to be met:
The file that is going to be imported has to be in XLS or XLSX format.
The project that should contain the imported requirements has to be already created.
If user defined properties (only available in Klaros-Testmanagement Enterprise Edition) are to be imported they have to be created for the project prior to starting the import process.
To import Excel-based requirements a REST interface is available which allows you to upload your data from the command-line or other applications.
The following example shows how to import an Excel sheet containing requirements into the project named P00001 using the curl command line application. curl is available in almost any Linux distribution and for the Microsoft Windows operating system family as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html.
curl -v -T Requirements.xls "<klaros-app-url>/seam/resource/rest/import/requirement/xls?config=P00001\ &username=user&password=secret"
Example 12.3. Excel Requirement Import via Command Line
Klaros-Testmanagement allows to both import and synchronize requirements from XML Files.
An import is limited to a one-time action that always creates new instances of the delivered requirements. Synchronization, on the other hand, allows updating existing requirements with the content of the XML file and creating new revisions of them as needed.
The format of the XML file is described in Appendix D, Requirement Import File Specification. The XML schema is available at the following URL: https://www.klaros-testmanagement.com/files/schema/klaros-requirements-1.0.xsd.
To import XML based test cases the following prerequisites have to be met:
The file that is going to be imported has to be in *.XML format.
The project that should contain the imported requirement has to be already created.
If user defined properties are to be imported, they have to be created in the project prior to starting the import process.
If the imported requirements should be assigned to test cases via externalTestCaseId,
Test cases with this external ID must already exist.
To import XML-based requirements a REST interface is available which allows you to upload your data from the command-line or other applications.
The following example shows how to import an XML file containing requirements into the project named P00001 using the curl command line application. curl is available in almost any Linux distribution and for the Microsoft Windows operating system family as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html.
curl -v -T Requirements.xml "<klaros-app-url>/seam/resource/rest/import/requirement/xml?config=P00001\ &username=user&password=secret"
Example 12.4. XML Requirement Import via Command Line
To synchronize XML-based requirements a different REST interface is available
(ending with /sync/requirement/xml). It understands the same import
format as defined for importing requirements but requires additional elements to be present
for correct operation.
In contrast to an import a synchronization action is intended to update the set of requirements stored in Klaros-Testmanagement from arbitrary external applications on a regular basis.
The synchronization supports creating and updating as well as revisioning of requirements. Changes to the requirements will be reflected in the Klaros-Testmanagement database on a per-field basis for each synchronization action.
![[Caution]](images/caution.png) |
Synchronization Overrides Local Changes! |
|---|---|
|
Be aware that all data received via synchronization will overwrite any changes made to the requirements stored in Klaros-Testmanagement. |
![[Tip]](images/tip.png) |
externalId
|
|---|---|
|
Supplying the |
|
revision
|
|---|---|
|
Supplying the
|
The following example shows how to synchronize an XML file containing requirements into the project named P00001 using the curl command line application. curl is available in almost any Linux distribution and for the Microsoft Windows operating system family as part of the Cygwin http://www.cygwin.com/ distribution or as a command line tool from http://curl.haxx.se/download.html.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <r:container xmlns:r="http://klaros-testmanagement.com/export-requirements-1.0"> <r:requirements> <r:requirement> <r:attributes/> <r:externalId>RTM-00001</r:externalId> <r:revision>1.0</r:revision> <r:priority>MEDIUM</r:priority> <r:shortname>Remote-controlled door panels / unlocking</r:shortname> <r:summary>Doors must me remote controllable.</r:summary> </r:requirement> </r:requirements> </r:container>
Example 12.5. XML Requirement Synchronization via Command Line
curl -v -T Requirements.xml "<klaros-app-url>/seam/resource/rest/sync/requirement/xml?config=P00001\ &username=user&password=secret"
Example 12.6. XML Requirement Import via Command Line
Test automation tools typically generate test results in file form. These files can be imported via a REST interface and automatically converted into test results.
JUnit XML++ is the generic format used internally by Klaros-Testmanagement for importing test case results from external sources. This format is upward compatible with the JUnit XML format.
By extending the JUnit XML format, the JUnit XML++ format enables you to specify individual test steps
of a test, as well as to embed binary attachments in an XML document.
In addition, with the result type inconclusive it allows to indicate ambiguous results.
Unfortunately, a clear formal JUnit XML format specification does not exist, as JUnit itself does not create XML reports. XML reporting usually results from the processing of the JUnit invocation within a build tool such as the Ant JUnit task, the Maven Surefire plugin, or Gradle.
The JUnit XML format has established itself as a generic (quasi-)standard format for test case results across tool and programming language boundaries and is supported by a large number of automation tools. Despite the ambiguity of the format, there have been several attempts in the past to document the format in the form of an XML schema. Detailed commented schema definitions can be found, for example, here: https://llg.cubic.org/docs/junit/ and here: https://github.com/windyroad/Junit-Schema/blob/master/JUnit.xsd.
The JUnit XML format unfortunately does not offer all the possibilities that are supported in Klaros-Testmanagement, especially it lacks:
Das JUnit XML Format bietet leider nicht alle Möglichkeiten, die in Klaros-Testmanagement unterstützt werden, insbesondere fehlt hier:
We have added this to the JUnit XML format without changing the existing syntax. In the following we call this new format JUnit XML++.
Within a testcase element there can now occur any number of teststep
elements.
These must contain a time attribute which specifies the execution time of the
test step in seconds.
As with test cases, error, failure or skipped
elements within a test step control their rating.
Also likewise to the test cases, system-out as well as system-err
elements are supported. If these contain content, they are automatically added as binary attachments
to the test case result generated during import.
Optionally, the elements action, precondition,
postcondition and expectedResult can be mapped to the test step result.
If these are available, they are transferred to the corresponding fields of a test step result in Klaros-Testmanagement.
This information is not mandatory, but it is recommended at least for the action field
in order to better identify individual test steps.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<testcase name="Test 1" time="0.008">
<teststep time="0.006">
<action>Textual description of the action taken in this step</action>
<precondition>Precondition information</precondition>
<postcondition>Postcondition information</postcondition>
<expectedResult>Expected result of this test step</expectedResult>
</teststep>
<teststep time="0.002">
<failure>
Detailed failure message
</failure>
<system-out>Log message</system.out>
</teststep>
</testcase>Example 12.7.
For the documentation of a test (step) result, it may be useful to supplement it with a file (screenshot, document, etc.) in addition to the textual description. To enable this, additional content can be defined in the system-out and system-err elements.
After successful extraction and saving, this content is not transferred to any additionally created system-out/system-err attachments. The content is defined according to the Jenkins plugin JUnit Attachments and may appear in three different forms:
|
Base64 Encoded Attachment |
Syntax:
In “encoded data” a base64-encoded binary content is expected.
After successful decoding, this is stored under the file name So this method saves the entire attachment as part of the result file. This requires more storage space, but allows access to the content at any time. |
|
URL Attachment |
Syntax:
An attempt will be made to download the contents of the URL
This method expects the attachment to be available on the network. It is mandatory that the Klaros instance has access to this URL at import time for the extraction to succeed. |
|
File Attachment |
Syntax:
An attempt is made to download the contents of the file With this method it is expected that the attachment is provided in the local file system. It is mandatory that the Klaros instance has access to this file at the time of import for the extraction to succeed. |
To import test results the following prerequisites have to be met:
The project, iteration, test environment and system under test that should contain the imported test case or test suite results have to be created.
The default URL of the import interface is located at
http://localhost:18080/klaros-web/seam/resource/rest/importer.
The content is transferred via an HTTP PUT request using the above URL and various URL query parameters.
|
The <klaros-app-url> Term
|
|---|---|
|
The |
The following parameters are supported:
|
config |
The ID of the project to import the results into (e.g. P0001). |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
iteration |
The ID of the iteration to relate the results to (e.g. ITR00001). This parameter is optional. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
env |
The ID of the test environment in which the tests have been run (e.g. ENV00001). Please make sure that this test environment already exists in the project before starting the import. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
sut |
The ID of the system under test in which the tests have been run (e.g. SUT00001). Please make sure that this system under test already exists in the project before starting the import. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
type |
The type of the import format. The following types are supported:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
job |
The optional ID of a job this test run should be assigned to (e.g. JOB00001). If given, the job must already exist in the project before starting the import. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
time |
The time of the test execution. Please make sure the fixed format for the time is |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
createTestSuiteResults |
If set to |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
autoCreateTestCases |
If set to |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
username |
The username for the import. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
password |
The password for the import. |
A complete example for a QF-Test import URL would look like this:
http://localhost:18080/klaros-web/seam/resource/rest/importer?\ config=P00001&env=ENV00001&sut=SUT00001&type=qftest&time=01.03.2011_12:00&username=me&password=secret
Example 12.8. QF-Test import URL sample
The result file is contained in the HTTP request body.
The curl command line tool can be used on Linux or Windows/Cygwin to trigger an import in a single command line.
curl -v -H "Content-Type: text/xml" -T <test result file> \ "<klaros-app-url>/seam/resource/rest/importer?config=P00001&env=ENV00001&sut=SUT00001&type=junit\ &time=23.05.2011_14:55"
Example 12.9. Curl Command Line Example
|
Incompatible Windows Powershell curl alias |
|---|---|
|
Windows Powershell also defines an alias named curl which also can be used for this purpose but takes a completely different set of arguments. If you prefer to use the Linux compatible curl executable under Powershell, use curl.exe instead of curl. |
curl -Method put -InFile <test result file> -Uri \ "<klaros-app-url>/seam/resource/rest/importer?config=P00001&env=ENV00001&sut=SUT00001&type=junit\ &time=23.05.2011_14:55"
Example 12.10. Powershell Curl Alias Command Line Example
This plugin integrates a continuous integration server with Klaros-Testmanagement by publishing the test results of a Jenkins build to the Klaros-Testmanagement application. The test results will be stored in the Klaros-Testmanagement database for further evaluation and reporting purposes. You can find the installation and configuration guide for the plugin in the Jenkins GitHub page.
Klaros-Testmanagement provides a JUnit XML export interface that enables the export of test results.
The default URL of the export interface is located at
http://localhost:18080/klaros-web/seam/resource/rest/export/result/junit.
The content is transferred via an HTTP GET request using the above URL and various URL query parameters.
|
The <klaros-app-url> Term
|
|---|---|
|
The |
The following parameters are supported:
|
config |
The ID of the project to export the results from (e.g. P0001). |
|
env |
The ID of the test environment in which the tests have been run (e.g. ENV00001). |
|
sut |
The ID of the system under test in which the tests have been run (e.g. SUT00001). |
|
job |
The ID of the job to export the results of (e.g. JOB00001). |
|
testRun |
The ID of the test run to export the results of (e.g. TRU0000001). |
|
username |
The username for the export. |
|
password |
The password for the export. |
Both individual test results of a job or a test run and all test results of a system under test or a combination of system under test and test environment can be exported. This can be controlled by specifying the parameters.
The curl command line tool can be used on Linux or Windows/Cygwin to trigger an export in a single command line.
curl \ "<klaros-app-url>/seam/resource/rest/export/result/junit?config=P00001&job=JOB00001&user=me&password=secret"
In this example, the results of the job JOB00001 from the project P00001 are exported.
Example 12.11. Curl Command Line Example
|
Incompatible Windows Powershell curl alias |
|---|---|
|
Windows Powershell also defines an alias named curl which also can be used for this purpose but takes a completely different set of arguments. If you prefer to use the Linux compatible curl executable under Powershell, use curl.exe instead of curl. |
curl -Method get -Uri \ "<klaros-app-url>/seam/resource/rest/export/result/junit?config=P00001&testRun=TRU0000001&username=me&password=secret"
In this example, the results of the test run TRU0000001 from the project P00001 are exported.
Example 12.12. Powershell Curl Alias Command Line Example
Only available in Klaros-Testmanagement Enterprise Edition
With Klaros-Testmanagement it is possible to export the content of all tables to an Excel file. The current filter and sort settings will be considered.
To move data between different database installations, or to selectively import data, Klaros-Testmanagement provides the functionality to import and export database content via XML files. Section 10.6, “Backup” explains the import and export functionality in detail.
Klaros-Testmanagement Enterprise Edition contains a REST-based interface that grant access to back up files of single projects. The following URI for example returns the backup xml file of the project P00004: http://{host}:{port}/klaros-web/seam/resource/rest/io/backup/project/P00004.
|
Note |
|---|---|
|
For more information on how to access REST-based interfaces, see Chapter 13, The Remote API. |
|
|
|
|
| 11.5. Creating a Chart |  |
Chapter 13. The Remote API |
