If you are just getting started with TestRail, you might already have existing test cases stored in other documents (such as Excel) or test management tools. Or you plan to generate test cases based on your application and system data. In either case, chances are that you want to import those test cases into TestRail. This article explains how to do just that.
If you are specifically looking into importing test cases from Excel or CSV files, please also have a look at the Excel/CSV import article.
Importing test cases
You can fill a test suite with existing test cases and sections by loading an XML import file into TestRail. When you click on the import icon in the toolbar of a test suite (the icon with an arrow pointing to the left), the import dialog opens and you can select an XML file to import. In case you haven’t already added a test suite to import test cases to, please make sure to create a new (empty) test suite first.
TestRail’s import format
The import file must be given in a specific XML format which is outlined and explained in this section. The XML format represents a tree of sections, test cases and subsections, just like the content of a test suite. The basic format of an import file looks as follows:
<?xml version="1.0" encoding="UTF-8" ?>
<sections>
<section>
<name>...</name>
<description>...</description>
<!--
The test cases of the section. This is just a list of
<case> elements plus fields such as title or type.
This element is optional.
-->
<cases>
<case>
...
</case>
...
</cases>
<!--
The subsections, if any. Can also contain test cases
and further subsections etc. This element is optional.
-->
<sections>
<section>
...
</section>
...
</sections>
</section>
...
</sections>To take a look at an actual TestRail XML file, you can just use the export feature of an existing test suite. The import and export functions use the same file format and taking a look at an actual example might help you better understand the file format. Note that the exported files have an additional top-level element which is automatically ignored when importing a file and can thus be omitted.
The above example explained how to express TestRail’s section tree structure in XML files. We will now take a look at how to specify all the additional fields of the element.
The element supports all properties of a test case in TestRail such as the title, estimate, priority, text fields etc. A fully specified test case thus looks as follows:
...
<case>
<title>Lorem ipsum dolor sit amet ... </title>
<!-- The type of the test case. Please see your TestRail
installation for the supported types. -->
<type>Usability</type>
<!-- The priority of the test case, specified as a simple
number. Please see your TestRail installation for the
supported priorities. -->
<priority>2</priority>
<!-- The estimate of the test case, specified in seconds. -->
<estimate>100</estimate>
<!-- The milestone of the test case. Is looked up in the
project you import the test cases to. -->
<milestone>Beta 1</milestone>
<!-- The references of the test case (a list of IDs, separated
by comma or space). May be used to link the test case to external
references (requirements or user stories, e.g.). -->
<references>REQ-1, REQ-2</references>
<custom>
<!-- Custom fields go here -->
...
</custom>
</case>
...Note that all fields except the <title> are optional. TestRail will automatically choose a default value or leave a field empty if it’s missing.
Custom fields
Custom fields for test cases can be imported as follows:
...
<case>
<!-- Custom fields are grouped under the <!custom> tag. -->
<custom>
<preconds> ... </preconds>
<steps> ... </steps>
<expected> ... </expected>
</custom>
</case>
...Custom fields are grouped under the <custom> tag and use the system name as the XML identifier/tag (as configured in the administration area). The exact import format and behavior depend on the actual custom field type. The following table lists the import formats for the various custom field types:
| Type | Sample Value | Description |
|---|---|---|
| Checkbox | true | “true” or “false” (without the quotes) |
| Date | 2013-06-15 | A valid XML date string in yyyy-mm-dd format |
| Dropdown | <id>5</id> | The ID of the value (as configured in the custom field options in the administration area) in an <id> tag |
| Integer | 1022 | A simple integer number |
| Milestone | <id>2</id> | The ID of the milestone in an <id> tag |
| Multi-select | <item> <id>1</id> </item> <item> <id>2</id> </item> |
A list of <item> records, each with its own ID (so, like a list of Dropdown values) |
| Steps | <step> <index>1</index> <content>Step 1<content> <expected>Result 1<expected> </step> <step> <index>2</index> <content>Step 2<content> </step> |
A list of <step> records, each with its own index, content and optionally expected result |
| String/Text | Foobar | A simple string |
| URL (Link) | http://google.com/ | A simple URL as a string |
| User | <id>3</id> | The ID of the user in an <id> tag |
Generating an XML file
Before you are able to import test cases into TestRail, you first need to convert the test cases (and possibly sections) from your current test management tool to TestRail’s XML file format. If your current tool already supports XML files, developing a quick conversion script would probably be the easiest way to accomplish this (XSLT might come in handy for this). You can also take a look at the TestRail migration scripts.
If you are unsure about how to convert your existing data, contact our support team for assistance.