Importing test cases and sections (Excel/CSV)

If you are just getting started with TestRail, you might already have existing test cases stored in other documents (such as Excel or Google Spreadsheets) or other test management tools. Chances are that you want to import those test cases into TestRail and this article explains how to do just that based on simple CSV files.

Exporting an Excel file

If you currently manage your test cases in Excel, you first need to export your Excel sheets to one or more CSV files. You can do this in Excel under File | Save As, using CSV (Comma delimited) (*.csv) as file type. This will save your test cases as a CSV file which you can import into TestRail. Please note that it's sometimes necessary to simplify the layout of your Excel sheets so that TestRail can find and extract your test cases. We generally recommend using a simple layout with a single or multiple rows per test case.

Exporting a Google Docs/Spreadsheets file

If you currently use Google Docs/Spreadsheets to manage test cases instead, you can export your data to a CSV file with File | Download as, then .csv.

Importing CSV files

You can import CSV files directly in TestRail. To do this, open the project you want to import the test cases to and then navigate to Test Suites & Cases (and open a test suite) or Test Cases (depending on your project configuration).

You can then open the Import CSV dialog in the toolbar of the test suite/test case repository:

The CSV import allows you to migrate existing test cases using a simple wizard dialog. TestRail supports all typical CSV variants, the conversion of common character encodings and various CSV formats. You can upload your CSV file and configure various file related options on the first wizard step:

The following options are supported:

Option Description
Import To The base section you would like to add your test cases to. New sections and cases imported from the CSV file will be added under this section.
Encoding The file encoding of the CSV file. Excel/Windows commonly uses Windows-1252 (Latin) for CSV files whereas most other tools (including Google Spreadsheets) prefer the Unicode-compatible UTF-8 encoding.
Delimiter The delimiter that separates your CSV columns. This is most commonly a simple , character (comma) but you can change this to something else if your CSV file uses a different separator (such as a semi-colon ; or horizontal tab \t).
Start Row The index (starting at 1) of the row where TestRail should start looking for test cases in the CSV file. This can be used to ignore or skip lines at the beginning of the CSV file.
Header Row Indicates if the start row of the CSV file is a header row. A header row describes the CSV file and contains the column names. Excel or Google Spreadsheet documents usually have such a header row.
Template The case template to use for the imported test cases. The template specifies the field layout and supported system/custom fields for the test cases (added with TestRail 5.2).

The first wizard step also allows you to upload a previously created configuration file (created at the end of the import process) with all import options of the previous import. This is useful if you need to import multiple CSV files with a similar or the same file layout.

Column mapping

One of the main goals of the CSV import is it to make it as easy as possible to import CSV files (without having to prepare, update or convert your data first). This way you can often directly export any existing test cases from Excel, Google Spreadsheets or legacy test management tools and import your data to TestRail with just a few clicks.

To support this for as many CSV formats as possible, you can simply map your CSV columns to TestRail’s test case fields. TestRail also supports importing separate test steps and expected results if you use multiple rows for a single test case. This so called column mapping can be configured on step 2 of the CSV import wizard:

TestRail differentiates between single- and multi-row case layouts for CSV files. A single-row layout means that every test case is represented by a single row or record in the CSV file. This is the standard layout for most CSV files.

If a test case spans or may span multiple rows/records in a CSV file, TestRail supports this by selecting the multi-row layout. You also need to select the column which detects the start of a new test case in this case (for example, an ID or Name/Title column which is unique per test case). This layout is commonly used for test cases with multiple steps and expected results and one row/record per step/expected result.

The last option on this step specifies if TestRail should ignore CSV rows/records without a valid, non-empty title column. It is recommended to keep this option enabled to filter out empty rows at the beginning/end of the CSV file or between regular test cases.

What about sub sections? You can also import full section hierarchies from CSV files. To do this, you would simply specify all sections and sub sections in a single column, separate them with the greater-than character (>) and select the Section TestRail field. Like this:

Top Section > Sub Section #1 > Sub Section #2

Value mapping

Mapping columns to fields is great, but mapping the actual values to dropdown options, checkboxes or multi-select fields is at least as important. TestRail’s CSV import allows you to do all this and it supports configurable value mappings for both built-in and custom fields. TestRail also provides options to clean your import data, such as removing unnecessary HTML tags from texts.

The value mapping is configured on step 3 of the wizard:

Preview & import

The last step before the actual import is to review the (first few) test cases that TestRail found in the CSV file. This is a good opportunity to review the file options as well as column & value mappings you've configured on the previous steps. You can go back and forth with the Previous and Next buttons to make changes to the file options or fine-tune the column or value mappings. Once you are satisfied with how the test cases look like in the preview, you can click the Import button to import your sections & test cases.

The last wizard step shows the amount of imported sections & test cases and allows you to download a configuration file with the wizard options you used. This file can be loaded on the first wizard step (with future imports) and automatically pre-configures all wizard steps and import options. This is especially useful if you need to import multiple CSV files with a similar or same layout. You can also share this configuration file with other team members.