Table of Contents

Importing test cases and sections (XML)

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 you 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 our Excel/CSV import.

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 <suite> 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 <case> element.

The <case> 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 and 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 2010-07-01 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 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 on how to convert your existing data, please just contact our support as we might be able to help you convert your test cases.