--- title: "TestRail integration" slug: "testrail-integration-20" updated: 2025-06-30T14:46:25Z published: 2025-06-30T14:46:25Z canonical: "knowledge.curiositysoftware.ie/testrail-integration-20" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.curiositysoftware.ie/llms.txt > Use this file to discover all available pages before exploring further. # TestRail integration This describes how to link Quality Modeller (QM) to TestRail, using the TestRail Integration Connector. This will allow you to import data from TestRail and export tests you have built in QM into TestRail. It is aimed at users of QM who have access to a TestRail instance. ## Requirements - Your company TestRail base URI (Note that we do support the on-premise version of TestRail as well) - A valid TestRail username. This will be the email address of your user - A TestRail API Key (the appendix includes details on how to obtain this in TestRail) ## Setting up the connection ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-0D6OT9WV.png) On the left hand menu of the Curiosity Dashboard: - Click connectors, in the Management section. - Click the Add Connection button (Top right of the screen). - In the Configuration dialog box, fill in the fields as listed in the [Configuration dialog box fields](/kb/docs/testrail-integration-20#configuration-dialog-box-fields) section. - Click save or cancel to save or discard the new connection. ## Configuration dialog box fields ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724324140358.png) | Button | Action | | --- | --- | | Validate | This checks the URL is a valid one in the connection field | | Cancel | dismiss this dialog box without saving | | Save | Save the new connection. Note that any error message that prevents it being saved will appear as a popup message on the top right of the page. | ### Details tab This tab allows you to choose the connector type and name it. ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724324140358.png) | Field | Usage/Action | | --- | --- | | Connector Type | This is a drop-down list that can be filtered by typing. Select the TestRail Connector Type | | Profile Name | The name for your connection | | Shared | Toggle this option ON to make this connection visible to other Workspace users. By default, it is OFF | ### Connection tab This tab allows you to set the configuration for the TestRail connection ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724255373562.png) | Field | Usage/Action | | --- | --- | | Url | The base URL for your TestRail instance. | | Username | The email address of the user. | | API Key | The TestRail API Key. Note: see the section: [Creating a TestRail API Key](/kb/docs/testrail-integration-20#creating-a-testrail-api-key), if you do not already have a key. | | Project Key | A drop down list of the available projects in TestRail. Note: You must click the refresh button to retrieve the list of projects available. | | Issue Type | A drop down list of the issue types/suites available in TestRail for the selected project. Note: When you select/update the Project Key, you must click the refresh button to retrieve the list of available issue types. | | ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724326100119.png) | Refresh button | ### Field Mappings tab This tab allows you to map TestRail fields, either to a fixed value or to a Model field. There are a number of different types of field types available in TestRail and these are listed in the [mapped field type section](/kb/docs/testrail-integration-20#mapped-value-field-types). If new fields are required, then these should be added in your TestRail application and then they can be imported into QM. **Note: any changes made here on an existing connector will be saved to the connector, even if the cancel button is clicked.** ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-UUU92ZBP.png) | Field/Column | Usage/Action | | --- | --- | | ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724326141388.png) | Click this to add a field that is not set up in TestRail, but will only be used in modeller. | | ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724326100119.png)refresh | Click this to refresh the list of fields from those in TestRail. | | Field (column) | The label in TestRail for the field. | | System Name (column) | The System Name in TestRail for the field. | | Required | If checked then the field is marked as required in TestRail and so cannot be deleted. | | Export Value | The value of the field that will be exported with the tests. | | Mapping ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724326002399.png)![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724326031266.png) | Locked: You set a fixed value for this field in the Export value field. This cannot be altered when exporting the tests into TestRail. Unlocked: This allows the value of the field to be mapped to a model/path field value. In this scenario, the 'Export value' column contains a drop-down list of the available modeller/path value names that you can choose. The following values will have a second field, as follows: - ChatGPT Template - this allows you to select a value from the AI prompts list. You can see this list by opening the menu: - management -> Workspace-> configuration on the Generative AI Prompts tab - Export Override - this allows you to set a default value here, but the value is available to be overridden when you export the tests. | | Delete ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724326064913.png) | Delete the field mapping. Note: this is not available for Variables marked as required in TestRail. | ## Mapped value field types A list of the currently available field types in TestRail | **Field Type** | **Description** | **Sample Values** | | --- | --- | --- | | Checkbox | Used to enter/store a boolean value. Checked is true. | checked | | Date | Used to enter/store a date value. Click the field to show the drop-down date picker. The date will appear in the field in MM/DD/YYYY format. | 10/31/2021 | | Dropdown | Used to allow choice of one option from a list of options. Click the field to display the dropdown and then click an option to select it. | orange | | Integer | Used to enter/store an integer number. | 2011 | | Milestone | A drop-down list, used to allow choice of a milestone from the milestones of the current project. Click the field to display the dropdown and then click an option to select it. | SubMilestone | | Multi-select | Used to allow choice of multiple options from a list. Click the field to show the drop-down menu and click options to select them or the x to deselect them. | option1 option2 option5 | | String | Used to enter/store a single line text value. | Curious? | | Text | Used to enter/store a multi-line text value. | Multi-Line Text | | Url (Link) | Used to enter/store a web address. This can be a public internet address or a local intranet web page. | [https://www.curiositysoftware.ie/](https://www.curiositysoftware.ie/) | | User | A drop-down list, used to select a user from a list of users in the TestRail installation. Click the field to display the dropdown and then click an option to select it. Note: only admin users can access user IDs inside of TestRail | Gloria Lopez | ## Exporting tests ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724774963979.png) - On the Scenarios window of your model, click the Export button. This will display the Exports dialog. ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724774991527.png) - Click the 'Test Cases' option. This will allow you to specify where the test scenarios should be exported to. ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/image-1724775044097.png) - Fill in the Export Test Scenarios dialog. The fields and buttons are listed below. | Field/Button | Value/usage/action | | --- | --- | | Connector Profile | A dropdown list of available connection profiles (this is set up in [Setting up the connection](/kb/docs/testrail-integration-20#setting-up-the-connection)). This should select your TestRail Connection. | | Exports tab | Details of the location for the test scenarios export. | | Custom Parameters tab | The fields that can be altered on export. These are fields where the Export Value is set to 'Export Override', see the [Field Mappings tab](/kb/docs/testrail-integration-20#field-mappings-tab) section. | | Edit Existing | Yes: update scenarios in an existing folder in TestRail. No: create a new folder in TestRail for these test scenarios. | | New Folder/Folder list | Dependant on value of 'Edit Existing'. Yes: this is a drop down list of existing folders in TestRail. No: this is a text box so you can give a new folder name to add to TestRail. | | Cancel | Cancel this action. | | Back | Back to the previous screen which allows you to choose the export type. | | Execute | Export the scenarios. | - Once the fields are filled in appropriately, click the execute button. ## Appendix ### Creating a TestRail API Key If you do not already have an API key for TestRail, you can generate one: 1. Open your TestRail dashboard and open My Settings 2. Select the API KEYS tab 3. Click Add Key and enter a name for the key 4. Click generate Key 5. Securely record the generated key, as it is only visible when generated and cannot be retrieved afterwards. Note that in order to be able to generate an API key, your TestRail user has to be enabled to use it on the TestRail Administration dashboard →side panel → Site Settings → API ![](https://cdn.document360.io/77f722a6-2d0a-49fa-8074-572515a6c4b8/Images/Documentation/TestRailAdminAPIview.png) A Connector is a link to an API. Quality Modeller has many built-in connectors including Excel, Word, Visio, Gherkin, Disco, BPMN, Jira, Confluence and draw.io. As many new connectors can be created as needed for a project. Do this in the Connectors sub-section of the Profile section within Management on the Navigation Panel. The Quality Modeller Dashboard is the default view in Modeller. It displays a set of quick links to tutorials, activities and other useful information. The Configuration section of Quality Modeller allows you to view and change a range of settings. This includes, Sequences, Functions, Categories, Defaults, TDM Audit, Queries and Internal settings. In the Profile section of Modeller you can manage your workspace, create a new one, update your password for Modeller. Additionally, you can also manage the API Key for Modeller in the Profile section. The Workspace Section of Modeller allows you to view and edit Data Rules, Code Templates, Tags and Custom Fields which have been set up by default or by the users. A Project in Modeller represent the current collection of work the user is working on. Users can create multiple Projects within Modeller and switch between them at any time, this can be used to manage Models and User Teams. A Model is a canvas and the Flow that is built onto it. There are several types of Model, some of which display different tabs and tools on the toolbar in Quality Modeller. Test Data Variables are sets of data that can be attached to blocks in models. This data can be custom, synthetic, automated etc. Variables are basically assigned data values and rules to blocks, and this data is used when automation is run.