| 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.
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 field Step at cell A:25 must be present
in the first line above the step list. Do not skip or rename it, the parser is relying on
finding that field for locating the test steps.
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 an variable number of test steps. These are listed one per row starting from cell A26 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 Case Step Coordinates
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 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.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 in *.xls format.
The project that should contain the imported test cases has to be already created.
If the "Authentication required for import?" flag is set (see Section 10.4.1, “Miscellaneous Settings”), username and password of a system user have to be provided (see Section 10.3.3, “User Details” for more information on system users).
If user defined properties are to be imported they have to be created for the project prior to starting the import process.
Please note that user defined properties are only available in Klaros-Testmanagement Enterprise Edition.
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.
![[Important]](images/important.png) |
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"
Example 12.1. Excel Test Case Import via Command Line
If the Klaros-Testmanagement installation requires authentication for import, username and password arguments have to be appended to the curl call.
curl -v -T TestCases.xls "<klaros-app-url>/seam/resource/rest/import/testcase/xls?config=P00001\ &username=user&password=secret"
Example 12.2. Excel Test Case Import via Command Line with authentication
![[Note]](images/note.png) |
Note |
|---|---|
|
All artifacts 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. For validation purposes an XML schema is also available from the following URL: http://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 be in *.xml format.
The project that should contain the imported test cases has to be already created.
If the "Authentication required for import?" flag is set (see Section 10.4.1, “Miscellaneous Settings”), username and password of a system user have to be provided (see Section 10.3.3, “User Details” for more information on system users).
If custom attributes are to be used, they have to be defined for the project prior to starting the import process. The name element of the custom attribute to be imported must match with the name of a user defined property in the corresponding project for the import to succeed.
Please note that user defined properties are only available in Klaros-Testmanagement Enterprise Edition
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"
Example 12.3. XML Test Case Import via Command Line
If the Klaros-Testmanagement installation requires authentication for importing test cases, username and password arguments have to be appended to the curl call.
curl -v -T TestCases.xml "<klaros-app-url>/seam/resource/rest/import/testcase/xml?config=P00001\ &username=user&password=secret"
Example 12.4. XML Test Case Import via Command Line with authentication
|
Note |
|---|---|
|
All artifacts 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 P01 and P001 are not. |
Klaros-Testmanagement allows importing of requirements from Excel sheets structured in a predefined format which will be further detailed in Section 12.3.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 according to what is listed in Section 12.3.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.3.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 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 |
Name |
|
B2 |
Revision (only used in export) |
|
B3 |
Description |
|
B4 |
Priority (
|
|
B5 |
Summary |
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 format.
The project that should contain the imported requirements has to be already created.
If the Authentication required for import? flag is set (see Section 10.4.1, “Miscellaneous Settings”), username and password of a system user have to be provided (see Section 10.3.3, “User Details” for more information on system users).
If custom properties are to be used they have to be defined for the project prior to starting the import process.
Please note that custom properties are only supported in the Klaros-Testmanagement Enterprise Edition
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"
Example 12.5. Excel Requirement Import via Command Line
If the Klaros-Testmanagement installation requires authentication for import, username and password arguments have to be appended to the curl call.
curl -v -T Requirements.xls "<klaros-app-url>/seam/resource/rest/import/requirement/xls?config=P00001\ &username=user&password=secret"
Example 12.6. Excel Requirement Import via Command Line with authentication
|
Note |
|---|---|
|
All artifacts 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 P01 and P001 are not. |
Klaros-Testmanagement allows to both import and synchronize requirements from XML Files. An import is limited to a one time action which will always create new instances of the supplied requirements. On the other hand synchronization allows to update existing requirements with the content in the XML file and create new revisions of them when needed.
The format of the XML file is described in Appendix D, Requirement Import File Specification. For validation purposes an XML schema is also available from the following URL: http://www.klaros-testmanagement.com/files/schema/klaros-requirements-1.0.xsd.
To import XML based requirements the following prerequisites have to be met:
The file that is going to be imported has to be in XML format matching the given XML schema.
The project that should contain the imported requirements has to be already created.
If the Authentication required for import? flag is set (see Section 10.4.1, “Miscellaneous Settings”), username and password of a system user have to be provided (see Section 10.3.3, “User Details” for more information on system users).
If custom properties are to be used they have to be defined for the project prior to starting the import process.
Please note that custom properties are only supported in the Klaros-Testmanagement Enterprise Edition.
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"
Example 12.7. XML Requirement Import via Command Line
If the Klaros-Testmanagement installation requires authentication for import, username and password arguments have to be appended to the curl call.
curl -v -T Requirements.xml "<klaros-app-url>/seam/resource/rest/import/requirement/xml?config=P00001\ &username=user&password=secret"
Example 12.8. XML Requirement Import via Command Line with authentication
|
Note |
|---|---|
|
All artifacts 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 P01 and P001 are not. |
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) |
Required Synchronization Element externalId
|
|---|---|
|
Supplying the |
|
Optional Synchronization Element externalRevision
|
|---|---|
|
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.
curl -v -T Requirements.xml "<klaros-app-url>/seam/resource/rest/sync/requirement/xml?config=P00001"
Example Requirements.xml input:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <r:container xmlns:r="http://klaros-testmanagement.com/export-requirement-1.0"> <r:requirements> <r:requirement> <r:attributes/> <r:externalId>RTM-00001</r:externalId> <r:externalRevision>1.0</r:externalRevision> <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.9. XML Requirement Synchronization via Command Line
If the Klaros-Testmanagement installation requires authentication for import, username and password arguments have to be appended to the curl call as shown below.
curl -v -T Requirements.xml "<klaros-app-url>/seam/resource/rest/import/requirement/xml?config=P00001\ &username=user&password=secret"
Example 12.10. XML Requirement Import via Command Line with authentication
|
Note |
|---|---|
|
All artifacts 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 P01 and P001 are not. |
Klaros-Testmanagement is able to import test results via a REST interface into the Klaros-Testmanagement database.
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.
If the Authentication required for import? flag is set (see Section 10.4.1, “Miscellaneous Settings”), username and password of a system user have to be provided (see Section 10.3.3, “User Details” for more information on system users).
The default URL of the import interface is located at
http://localhost:18080/klaros-web/seam/resource/rest/importer.
The content will be transferred via a 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. I00001). 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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
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 (since plugin version 1.1) |
The user name for the import. If Klaros-Testmanagement is configured to use authentication for the import a valid user name must be passed to the importer. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
password (since plugin version 1.1) |
The password for the import. If Klaros-Testmanagement is configured to use authentication for the import a valid password must be passed to the importer. |
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.11. 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.12. 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.13. Powershell curl alias command line example
|
Note |
|---|---|
|
All artifacts 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 P01 and P001 are not. |
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.
Feature 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 backup 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 Klaros-Testmanagement Remote API. |
|
|
|
|
| 11.3. Example Report |  |
Chapter 13. The Klaros-Testmanagement Remote API |
