Chapter 12. Import/Export

Table of Contents

12.1. Importing Test Cases from Excel
12.1.1. Import Format
12.1.2. Prerequisites
12.1.3. Execution
12.2. Importing Test Cases from XML
12.2.1. Prerequisites
12.2.2. Execution
12.3. Importing Requirements from Excel
12.3.1. Import Format
12.3.2. Prerequisites
12.3.3. Execution
12.4. Importing and Synchronizing Requirements from XML
12.4.1. Prerequisites
12.4.2. Importing
12.4.3. Synchronizing
12.5. Importing Test Results
12.5.1. Prerequisites
12.5.2. Execution
12.6. Exporting Table Content to Excel
12.7. Backup/Recovery

Klaros-Testmanagement provides several interfaces to import data from other tools and export its data into several formats.

12.1. Importing Test Cases from Excel

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”.

12.1.1. Import Format

The Excel sheet used to import test cases has to follow this strict format:

  1. Each test case is located on a separate sheet.

  2. Each sheet is divided into three sections: general properties, test case steps and custom properties.

  3. 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.

Test Case Excel Sheet Sample

Figure 12.1. Test Case Excel Sheet Sample


12.1.1.1. General Properties

The table below lists the cell coordinates for the general test case properties. 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 ( FUNCTIONAL, NON_FUNCTIONAL, STRUCTURAL, REGRESSION, RE_TEST)

B12

Design Method ( BLACK_BOX, WHITE_BOX)

B13

Variety ( POSITIVE, NEGATIVE)

B14

Execution ( MANUAL, AUTO)

B15

Priority ( LOW, MEDIUM, HIGH)

B16

State ( NEW, APPROVED, LOCKED, INVISIBLE)

B17

Team

B18

Level ( COMPONENT, INTEGRATION, SYSTEM, ACCEPTANCE)

B19

Document Base

B20

Dependency

B21

Evaluation

B22

Traceability

Table 12.1. General Property Coordinates


12.1.1.2. Test Case Steps

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

A27 (ff)

Step Number

B27 (ff)

Action

C27 (ff)

Precondition

D27 (ff)

Postcondition

E27 (ff)

Expected Result

Table 12.2. Test Case Step Coordinates


12.1.1.3. Custom Properties

Test cases may contain custom attributes. These are listed as name/value pairs starting from cell G1 downwards.

The name in the name column must exactly match the name of general 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. User Defined Property Coordinates


12.1.2. Prerequisites

To import Excel based test cases the following prerequisites have to be met:

  1. The file that is going to be imported has to be in *.xls format.

  2. The project that should contain the imported test cases has to be already created.

  3. If the "Authentication required for import?" flag is set (see Section 10.5.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).

  4. 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 Klaros-Testmanagement Enterprise Edition.

12.1.3. Execution

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.

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] 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.

12.2. Importing Test Cases from XML

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.

12.2.1. Prerequisites

To import XML based test cases the following prerequisites have to be met:

  1. The file that is going to be imported has to be in *.xml format.

  2. The project that should contain the imported test cases has to be already created.

  3. If the "Authentication required for import?" flag is set (see Section 10.5.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).

  4. 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 available in the Klaros-Testmanagement Enterprise Edition

12.2.2. Execution

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] 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.

12.3. Importing Requirements from Excel

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”.

12.3.1. Import Format

The Excel sheet used to import requirements has to follow this strict format:

  1. Each requirement is located on a separate sheet.

  2. Each sheet is divided into two sections: general properties and custom properties.

Requirement Excel Sheet Sample

Figure 12.2. Requirement Excel Sheet Sample


12.3.1.1. General 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 ( LOW, MEDIUM, HIGH)

B5

Summary

Table 12.4. General Property Coordinates


12.3.1.2. Custom Properties

Requirements may contain an arbitrary number of custom attributes. These are listed as name/value pairs starting from cell G1 downwards.

The name in the name column must exactly match the name of general 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. User Defined Property Coordinates


12.3.2. Prerequisites

To import Excel based requirements the following prerequisites have to be met:

  1. The file that is going to be imported has to be in *.xls format.

  2. The project that should contain the imported requirements has to be already created.

  3. If the Authentication required for import? flag is set (see Section 10.5.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).

  4. 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

12.3.3. Execution

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] 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.

12.4. Importing and Synchronizing Requirements from XML

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 synchronisation 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.

12.4.1. Prerequisites

To import XML based requirements the following prerequisites have to be met:

  1. The file that is going to be imported has to be in XML format matching the given XML schema.

  2. The project that should contain the imported requirements has to be already created.

  3. If the Authentication required for import? flag is set (see Section 10.5.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).

  4. 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.

12.4.2. Importing

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] 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.

12.4.3. Synchronizing

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] 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] Required Synchronization Element externalId

Supplying the externalId element (See Section D.7, “<externalId>”) will identify a requirement for subsequent synchronisation attempts. It is required field when using this interface. If you change this value, a new requirement object will be created instead of replacing the content of the previously created requirement.

[Tip] Optional Synchronization Element externalRevision

Supplying the externalRevision element (See Section D.8, “<externalRevision>”) will identify a new revision of a requirement for subsequent synchronisation attempts. It is optional when using this interface. If you add this value and it does not match a previous revision of yet existing requirement matching the supplied externalId, a new requirement revision will be created instead of replacing the content of the existing requirement.

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] 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.

12.5. Importing Test Results

Klaros-Testmanagement is able to import test results via a REST interface into the Klaros-Testmanagement database.

12.5.1. Prerequisites

To import test results the following prerequisites have to be met:

  1. The project, iteration, test environment and system under test that should contain the imported test case or test suite results have to be created.

  2. If the Authentication required for import? flag is set (see Section 10.5.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).

12.5.2. Execution

The URL of the import interface is located at http://${host}:${port}/klaros-web/importer. The content will be transferred via a HTTP PUT request using the above URL and various URL Query parameters.

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:

aunit

AUnit

boost

Boost Test

Check

Check

cpptest

CppTest

cppunit

CppUnit

ctest

ctest

cunit

CUnit

embunit

EmbUnit

fpunit

Free Pascal Unit

gtester

GLib/gtester

googletest

GoogleTest

jbehave

JBehave

jsunit

JsUnit

jubula

Jubula / GUIdancer

junit

JUnit
Robot Framework
Selenium
TestNG

mbunit

MBUnit

mstest

MSTest

nunit

NUnit

phpunit

PHPUnit

qftest

QF-Test

qtestlib

QTestLib

tessy

TESSY

testcomplete

TestComplete

tusar

TUSAR

cpptestunit

UnitTest++

valgrind

Valgrind

xUnit.net

xUnit.net

time

The time of the import. Please make sure the fixed format for the time is dd.MM.yyyy_HH:mm.

createTestSuiteResults

If set to true test suite results are automatically created for the corresponding test suite information contained in the result file. This information may vary with the import format. Additionally a corresponding test suite is created for the test suite result if it did not yet exist.

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


[Tip] The <klaros-app-url> Term

The http://localhost:18080/klaros-web URL shown above is the default klaros application url when accessing Klaros-Testmanagement from the host it is installed on and may vary with your setup. Throughout this this chapter the term <klaros-app-url> will be used instead to reflect this.

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


[Note] 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.

12.5.2.1. Jenkins/Hudson Plugin for Klaros-Testmanagement

This plugin integrates a continuous integration server with Klaros-Testmanagement by publishing the test results of a Jenkins/Hudson 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 Wiki or Hudson Wiki.

12.6. Exporting Table Content to Excel

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.

Export Table Content to Excel

Figure 12.3. Export Table Content to Excel


12.7. Backup/Recovery

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.7, “Backup” explains the import and export functionality in detail.