With TestRail, you can migrate any existing test cases you might have in Excel files or other test management tools by importing them via CSV. You can also create new test cases in bulk by scripting them in Excel or Google Sheets and importing them to your TestRail instance via CSV. This article walks you through the process of formatting your source CSV file in the correct format and importing your test cases to TestRail.
Prepare your source file to import
To import existing test cases to TestRail via CSV, you will first need to prepare your CSV import file. You may need to export your existing test cases to a CSV or Excel file from another test management system first, and then make some minor formatting changes to properly import your test cases into TestRail.
Saving an Excel file as a CSV
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, and selecting CSV (Comma delimited) (*.csv) as the 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, such as in the template file below.
Exporting a CSV from Google Sheets
If you currently use Google Sheets to document your test cases, you can export your data to a CSV file with File > Download as, then .csv.
Formatting your CSV(s) to Import
TestRail test cases are one of the most powerful features of TestRail because they are completely customizable and support custom fields with a wide variety of data types. Out of the box, TestRail comes with three default test case templates:
- Exploratory Session
- Test Case (Text)
- Test Case (Steps)
Each test case template comes with a slightly different set of fields to support the specific type of testing you are trying to accomplish. For example, the Exploratory Session template uses large text fields where you can define your Charter and Goals, and document notes, attach screenshots, and upload log files as you carry out your exploratory sessions.
The other two default templates, Test Case (Text) and Test Case (Steps) , both provide you with areas to specify Preconditions, Test Steps, and Expected Results. The Test Case (Text) template allows for you to describe the steps testers should take to test a given case more fluidly, while the Test Case (Steps) template allows you to delineate individual Steps along with the Expected Result for each step.
You may not always need to specify this level of detail for every test in your test suite, but specifying separated steps can give you a lot more visibility and traceability because you can add individual test result statuses, and add links to specific defects, requirements, or other external entities for each step using the Defect/Reference integrations, and re-use steps across multiple test cases where applicable.
You can learn more by reading our articles on Custom Fields in TestRail and Separated Test Steps.
Format your CSV depending on what test case template you’re using
Depending on the template you are using for your test cases in TestRail, you may need to format your import CSV differently.
When using Test Case (Text) template, your import file should use the standard one row format – meaning all of the contents for a single test case in your CSV will be on one single row. This means all of the relevant steps and expected results for your test cases will be in their own single cells, and when imported, will populate their own large text fields. You can download an example of a CSV formatted for the Test Case (Text) template below, as well as a template for your own test cases.
When using the Test Case (Steps) template, each test case that has multiple steps should span multiple rows, where all of the standard fields and the first step and expected result are defined in the first row, and each additional step and expected result should be on a separate row in the same column.
Additional Fields and Field Values
When mapping the data columns in the CSV to the relevant fields in TestRail during the Import process, there may be fields or field values in your spreadsheet that are not present by default in the TestRail system. In some cases, there may be a similar option in TestRail that can be used, or you may need to add a custom field or customize an existing field to accommodate your needs.
For example, you are defining test case priority using numbers, where 0 is least important and 3 is most important, you can map that to the default TestRail priorities as written out from Low to Critical.
On the other hand, if you have a field that defines what platforms a specific test should be run on (like mobile OS or browser), you would want to create a new custom field for that data point with the field values you use internally to map that CSV column to.
Importing your CSV to TestRail
To start the import process, first navigate to the test case repository in TestRail you would like to import into. This may be the Test Cases tab of a single repository project, or within a Suite or Baseline if you’re using one of the alternative project types.
You can then open the Import CSV dialog in the toolbar of the test suite/test case repository using the Import icon (the window with the green arrow pointing in):
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.
Import Step 1 – File Selection and Options
You’ll see a number of options present on the first page of the import wizard:
First, under File, select the CSV file you’re wanting to import. Below that, the option for format & Mapping will let you select a configuration file if you have one. After a successful import, you’ll be given the option to download the configuration file for the import, which will save all of the import configuration settings, allowing you to save time and effort when importing subsequent CSV files.
The upload size limit for CSV imports is 10MB. If your file is larger than 10MB, please split it into smaller files or remove any unnecessary data prior to importing.
In the Advanced Options section you will have a few additional settings to configure prior to continuing:
| Option | Description |
|---|---|
| Import to | The base section or folder you would like to add your test cases to. Sections defined on your test cases in the imported CSV file will be added as sub-sections under this section. By default, will select a blank value, which will add all defined sections as top-level, or they will be added to a generic “Test Cases” section if one is not defined in the CSV. |
| Encoding | The file encoding of the CSV file. Excel/Windows commonly uses Windows-1252 (Latin) for CSV files whereas most other tools (including Google Sheets) prefer the Unicode-compatible UTF-8 encoding. |
| Delimiter | The text character used to indicate where information for the next cell should start. Standard CSV (short for Comma Separated Values) uses a Comma (,) but some sheets may be configured differently based on user preferences, how the file was created, or other factors. Generally, the comma will be the correct option. |
| 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 content in the CSV file is a header row. A header row describes the CSV file and contains the identifiers used to match to the relevant fields in TestRail to 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. Depending on the template you are using, some additional formatting may need to be done to ensure compatibility with the selected template, most notably when using the Test Case (Steps) template. |
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.
Import Step 2 – Column Mapping
The next step to get your data imported is to map the columns of your spreadsheet to their respective fields inside of TestRail. When you get to this step, the first option will be to specify whether test cases span a single row or multiple rows. 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. When selected, you will also need to select the column which detects the start of a new test case (for example, an ID or Name/Title column which is unique per test case).
As mentioned above, a multi-row layout is used for test cases with multiple individually defined steps and expected results and one row/record per step/expected result.
In the main section of the import dialog, on the left side you’ll see a list of all of the column headings that the importer was able to find in your sheet, and on the right side you’ll see a number of dropdown fields showing the full selection of TestRail fields available for use in the project you’re importing to.
For each spreadsheet column heading, select the relevant, matching field from within TestRail. In some cases, you may have values in the spreadsheet that don’t directly match a TestRail field by name, but would make sense to associate.
For example, if you plan to sort your test case repository by functional area of your product (in categories like “Installation”, “Authentication”, etc.) and you have a column in your spreadsheet with those types of categories, you can map that to the section field here to create those folders.
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.
Importing Folders / Sections
When importing your test cases, you can have the system automatically create sections and subsections in your test case repository as part of the test case import process. During the import process, if you have a column that can match to sections, it can be mapped to section, and any values present in the spreadsheet that do not match an existing section will be created as a folder in your test case hierarchy.
If you’d like to create sub-sections, this can also be done by naming all sections and subsections, separated by a `>`
Example – There is a section column in an import file, one test case has a value of “Login”, which contains test cases related to the login screen and authentication. There is a separate mechanism used for a “Forgot Password” option with multiple test cases for this process that should be in a subsection of the login section. In this case during the import, a user can set it up with the value `Login > Forgot Password.`
This can be extended with multiple subsections as needed:
Top Section > Sub-section 1 > Sub-section 2
The CSV column “Section Hierarchy“ needs to be mapped to the “Section” column in the import wizard to retain the section hierarchy.
Import Step 3 – Value Mapping
With your columns mapped to their respective fields, the next step will be to map the values of those fields to their corresponding values in the spreadsheet.
You should see all of the columns that were mapped to fields in the previous step, and if the field supports a drop-down or multi-select option, you will see the values present in the CSV on the left, and a series of menus allowing you to select the relevant field values from inside TestRail. If the values from the CSV match a field option exactly, they should be automatically linked, however if you use different terms or values for certain fields, you may need to manually link them.
Example: TestRail by default defines priority using Low, Medium, High and Critical. If your team is using something like numerical values or different terms for your priority definition, you’ll need to use the value mapping to select the most appropriate analog from in the TestRail system. Note – it is also possible to customize the fields prior to importing to match your preferred nomenclature, or add/remove field selections if required.
For all fields in this step, you also have the option to strip any HTML tags from the field values. This is useful if you’re importing from a separate tool that exports HTML tags in the CSV content.
Import Step 4 – Preview, Finalize, and Configuration Files
The final step will be to preview the import. TestRail will show you the general examples of how the first few test cases will appear during import. Once you’ve confirmed that all of the information appears correct, you can finish the process by clicking “Import.”
When completed, you’ll see a pop-up confirming that everything was successful, and provide you with a link to download the configuration file for the import that has been processed. This file can be loaded on the first wizard step in future imports, and will automatically pre-configure all wizard steps and import options to what was set throughout this import. 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 if they will be performing similar imports.