Creating and Managing Test Specifications

In Polarion, specifications for individual tests are broken down into "Test Case" type Work Items. Test cases may be aggregated in a Document, or created individually in the integrated tracker. With either approach, the test cases are managed with the project's workflow through each step of your process. You can import existing test cases you have written up in Microsoft Office documents, or you can author them "from scratch" using Polarion tools. Once you have Test Case type Work Items created, you can link them for traceability. You can link Test Cases to other Test Cases, to Requirement type Work Items verified by the Test Cases, to Defect type Work Items that you may create during testing, or any other way to create exactly the traceability you need.

Importing from Microsoft Office

If you have test cases written up in Microsoft Word or Microsoft Excel, you can import existing documents to Polarion, creating Test Case type artifacts in projects which can then be tracked and managed with project workflows. If you import from Microsoft Word, you create a new LiveDoc documents, creating Test Case type Work Items according to rule you set up to recognize such artifacts from the original document content. If you import from Microsoft Excel, you can either import into a LiveDoc Document, if you prefer a document-based approach, or into the integrated tracker, if you prefer a tool-based approach.

For more detailed information on importing information to create Work Items, please see User Guide: Work Items Topic: Importing Work Items.

Importing Multivalued Data

You may want to specify data in an Excel worksheet to be imported into multivalued fields in Polarion. For example, the Category field can contain multiple values. Your project might also have some multivalued custom fields. If properly formatted in the Excel sheet, the Polarion importer will recognize multiple values and import them correctly. There are 2 options for formatting multiple values:

  • Specify each value in a cell under the column for the field, and merge that column to span all the values

  • Specify all values in a single cell under the column for the field, separating each value with a comma character.

Figure 20.1. Multivalued Data Import

Multivalued Data Import

Alternatives for formatting Excel data for import to Polarion multivalued fields

Recognition of multivalued data can be toggled on or off in the import wizard using the Separate multiple values option. When this option is checked, delimited values in a mapped column are imported to Polarion as multiple values in the target field. Recognized delimiters are comma (,) and semi-colon (;) characters. Detection of merged heading cells in Excel is automatic.

For reference information on supported fields, see the User Reference topic Import from Excel: Multivalued Data and Fields.

Defining Test Steps in Excel

When defining Test Cases having discreet test steps, you can format your Excel worksheet in such a way as to facilitate import into Polarion. Here are a few tips:

  • Specify a column with a name like "Title" to identify each Test Case. You can include another column such as "Description" for the general description of each Test Case.

  • Define columns corresponding to those defined in your projects Test Step Columns configuration. For example: "Step Name", "Step Instruction", "Expected Result".

  • When writing up the test steps, use one row for each step. Then, when these are complete, vertically merge the Title and Description columns so that they encompass the test step rows (see figure below).

    You may wish to leave an empty row between test cases. This can give you an additional import rule condition when importing your test cases.

Figure 20.2. Test Steps in Excel

Test Steps in Excel

One way to format test cases with test steps to facilitate import into Polarion.

When you import the Excel workbook, you can then map test steps to the Test Steps field of Test Cases. For more information on importing from Excel and mapping columns to fields, see the User Guide topic Importing from Excel.

The following sections discuss creating new Work Items in existing Documents and the Work Item Tracker.

Defining Test Cases in Documents

Polarion's LiveDoc Documents ("Documents") are often preferred for defining test cases by teams who are accustomed to work with document-based test case specifications. Content in Documents can be marked as Test Case type Work Items, which can be tracked and managed with project workflow yet still appear as content in a document.

When you create a Document for specifying test cases, be sure to select Test Case as the Work Item type the new Document should contain. (If you accidentally select a different type, or you want to have multiple Work Item types in the Document, you can configure the Document after is it created.)

To learn all about how to work with Documents, please go through the User Guide chapter: Documents and Pages Topic.


Projects can be configured by an administrator to include a table of manual test steps in Test Case type Work Items. When Test Steps support is enabled, discrete test steps can be defined in this special Test Steps field. The results of individual test steps can then be logged when testers execute manual tests.

When configured this way, the Document's Work Item presentation will display the Test Steps table in Work Items. Rows can be added to the table using the Add Row button, which appears when the cursor is located inside the test steps table when the Description field is in Edit mode.

If you do not see the Test Steps in Test Case items in a Document, it is possible that another user changed the Work Item presentation to some setting that does not display test steps. To show the Test Steps table in Document-based Work Items, you can set the Document's Work Item Presentation. Click the drop-down control beside the Work Item icon in the Document Editor toolbar, and on the menu choose Configure. In the dialog, select one of the options that includes Test Steps.

For more information, see Executing a Test Run and the Administrator's Guide topic Enabling Manual Test Steps.

Exporting Test Documents to Word

You can use the Round-trip for Microsoft Word feature to export test specification Documents to Word for review, comment, and collaboration. For more information, see the User Guide topic: Sharing Documents Using Word Round-trip.

You should note the following when exporting test specification Documents containing Test Steps in Test Cases:

  • A Document that is configured to show Title, Description and Test Steps, or Title and Test Steps, can be exported for Review, Prioritization, or Collaboration.

  • When exported for Review or Prioritization, the Test Steps can be commented. Comments will be written to the Description field upon re-import to Polarion.

  • The content of test steps cannot be edited in the exported file.

Defining Test Cases in the Tracker

If your team prefers a tool-based approach to defining test cases, you can create Test Case type Work Items directly in the integrated Work Item tracker. If your project is based on one of the standard Polarion project templates with QA/testing support, the Test Case type is pre-configured. If your project's configuration has been customized, the Work Item type corresponding to a test case may have some different name, which you should substitute for "Test Case" in the procedure that follows.

To define a new Test Case in the tracker:

  1. Log in and open the relevant project. Your user permissions for the project must allow you to create new Work Items.

  2. In Navigation, select the Work Items topic.

  3. On the toolbar of the Work Items page, click the Create button and choose Test Case on the menu. A new empty Work Item form appears in the viewer/editor pane of the page.

    (You cannot create new Work Items in the Matrix and Time Sheet views of the Work Items topic.)

  4. Fill in the fields, making sure to supply a value for all required fields. Optionally create links to other Work Items, specify hyperlinks to relevant resources, add attachments, etc.

  5. When finished, click the Create button on the viewer/editor toolbar to create the new Test Case item.


Projects can be configured by an administrator to include a table of manual test steps in the Description field of Test Case items. When Test Steps support is enabled, the results of individual test steps can be logged for manual tests. If there are multiple tables in the Description, the table of test steps must be the first table in the field. Rows can be added to the table using the Add Row button, which appears when the cursor is located inside the test steps table when the Description field is in Edit mode. For more information, see Executing a Test Run and the Administrator's Guide topic Enabling Manual Test Steps.

Linking Test Cases

In the default configuration of projects based on a Polarion project template that provides QA/testing support, Test Cases can be linked to each other and to other Work Item types such as Defects or Requirements/User Stories. Linking is vital for future traceability and impact analysis. You can link items to others in the same project, or in different project. (In systems configured for multiple concurrent Polarion servers, it is possible to link to items residing on a different server, but the linking is not as robust as when items are linked within or across projects residing on the same server.)

Typical links in QA/testing projects include:

  • Linking Test Case items to Requirement items with a "verifies/is-verified-by" link role (relationship).

  • Linking Defect items to Test Case items with a "is-triggered-by/triggers" link role (relationship). When using test execution features of Polarion's QA/testing project templates, Defect items with such link roles are created automatically upon failure of tests.

Linking of Work Items is discussed in more detail in User Guide: Managing Work Items: Linking Work Items.

Specifying Manual Test Steps

You can optionally define discrete Test Steps in Test Cases.

The advantage of this approach is threefold:

  • Any failure can be linked and easily traced to the test step in which it occurred.

  • Test Steps data is separated from the Description field, which can be then reserved for general information about the Test Case.

  • If a Test Run is exported to Excel for manual execution of tests off line, only test step and results data are involved in the round-trip. Other Test Case data, such as the Description cannot be modified by external testers.

Specify Manual Test Steps in the Classic Execution View

You can switch back to the classic execution view method described below by entering the following property in the Properties section.


Classic test execution view will become obsolete

To give current testers some time to transition to the new Test Execution View workflow, we will still support the Classic Test Execution View for a few more releases. Recommendation: Get to know the improved workflow outlined in the Executing a Test Run Using Polarion section.

Your project administrator can then enable the specification of manual test steps in the project configuration.

(See Administrator's Guide topic: Enabling Manual Test Steps ).

When correctly configured, a table of test steps appears in the Custom Fields section of new Test Case items (unless the administrator opted to display the table separately). Testers can specify each test step as a row in the Test Steps table. The table is rendered as executable test steps in a panel in the Execute Test Case section of the Test Case Work Item when the Test Case is executed during a Test Run.

Figure 20.3. Test Case with Test Steps Configured

Test Case with Test Steps Configured

Testers can log results of individual test steps

Editing Test Steps in Documents

When Test Steps are enabled in your project, they are a field of your Test Case type Work Items, so the steps can be edited in Test Cases defined in Documents. You need to set the Presentation Configuration in the Document, selecting either Title and Test Steps or Title, Description and Test Steps in the Content column of the Configure Work Item Presentation dialog (see User Guide topic Multiple Work Item Types for more information on this dialog).