TestRail migration

WARNING

MIGRATION AVAILABLE FOR ALLURE TESTOPS VERSION > 4.26.0

Prerequisites

Make sure your TestRail instance has API calls enabled. And you have generated a valid API token.

Enable API

Jump to the url https://COMPANY.testrail.io/index.php?/admin/site_settings

Generate and (very important) save API token.

Configuration file example

Create the json file with content like:

{
  "type": "testrail",
  "debug": true,
  "requestLog": false,
  "oneByOne": false,
  "allureConfig": {
    "endpoint": "https://demo.testops.cloud/",
    "token": "allure-testops-token",
    "sslTrustAll": true,
    "projectId": 6, 
    "migrationTagPrefix": "testrail",
    "folderCfPrefix": "Section",
    "issueTrackerId": 3
  },
  "testrailConfig": {
    "endpoint": "https://testrail-endpoint/",
    "username": "username/email to connect testrail",
    "password": "j8YLcMqPQy.khJ2LGW2M-RouSqHtedR3qbY/k1e.t",
    "testRailSessionCookie": "tr_session=691f4eb4-5758-48d7-884d-dfcf460888f5",
    "sslTrustAll": true,
    "projectId": 1,
    "suiteIds": [1,2],
		"caseIds": [1,2,3],
    "suitePattern": "{suite_name}",
		"noMdSteps" : true
		"descriptionFieldName": "custom_description",
    "preconditionStructure": [
      {
        "customFieldName":"custom_preconds",
        "displayName":""
      }
    ],
		"stepsSeparatedFieldName": "custom_steps_separated",
    "useParentDescription": false,
    "stepsAsPrecondition": true,
    "requiredCfMapping": true,
    "createdByAsOwner": false,
		"withDeleted": false,
    "oldBulkApi": false,
		"statusMapping":  [
      {
        "name": "custom_status",
        "workflowId": 1,
        "values": {
          "1": "Draft",
          "2": "Active"
        }
      },
      {
        "name": "custom_status_auto",
        "workflowId": 2,
        "values": {
          "1": "Start",
          "2": "Automated"
        }
      }
    ],
		"customFields": {
      "suite_id": "Suite",
      "priority_id": "Priority",
      "custom_tester": "Owner",
      "custom_system": "System"
    },
    "customFieldsMapping": [
      {
        "name": "priority_id",
        "values": {
          "1": "Low",
          "2": "Medium",
          "3": "High",
          "4": "Critical"
        }
      },
      {
        "name": "custom_tester",
        "values": {
          "1": "Tester QA1",
          "2": "Tester QA2",
          "3": "Tester QA3",
          "4": "Tester QA4"
        }
      }
    ]
  }
}

Additional settings

1. Migrate custom tags into TestOps tags:

Add the property into customFields settings area:

"custom_tag": "TESTOPS_TAG",

In this case the tags will be migrated as tags and not a custom fields.

2. If you want some TestRail custom field will be migrated as TestOps TestLayer you need:

Add the property into customFields settings area:

"type_id": "TESTOPS_TEST_LAYER",

3. If you want some TestRail custom field will be migrated as TestOps comment you need:

Add the property into customFields settings area:

"custom_comment": "TESTOPS_COMMENT",

4. The created_by testrail field will be migrated as Member (Owner) into TestOps if the flag createdByAsOwner setted into true.

The additional mapping will needed in this case.

Add the mapping into customFieldsMapping area:

{
  "name": "created_by",
  "values": {
		"1": "username1",
    "2": "username2"
  }
},

The value pattern: "TestRail user id" : "TestOps username".

Migration script can create a user for you if you didn't add such mapping. Set property "createOwner": true in allure config area. The username will be an email from TestRail user information.

Configuration parameters

Name	Mandatory	Description	Example
commonProperties	yes	see description here: Common properties
allureConfig	yes	see description here: Allure TestOps properties
endpoint	yes	Testrail instance url
username	yes	Testrail username (email)
password	yes	Testrail api token generated on TR ui or password if you are using LDAP for auth.
testRailSessionCookie	no	This settings should be provided in case your project have old style of attachments. Looks like  in TestOps view after migration. THis parameter can be taken from browser, use “Network” tab in the browser dev tool.	tr_session=691f4eb4-5758-48d7-884d-dfcf460888f4
oldAttachmentApi	no	If you use the old version of TR ( < 7.1 ), please set this parameter as true	true
oldBulkApi	no	If you use the old version of TR (< 7.1), please set this parameter as true	true
sslTrustAll	no	Defines if the ssl validation should be omitted (true for omitting the validation, false for validation)	true
projectId	yes	TestRail project id	2
suiteIds	no	A list of specific suites for migration can be specified. Without this parameter the migration will take place for all suites in the project	[1,2]
caseIds	no	A list of specific cases for migration can be specified. Without this parameter the migration will be done for all cases in the project/sute	[1,2,3]
suitePattern	no	pattern for suite custom field, default value is "{suite_name}" can be extended with a project name: "{project_name} {suite_name}"	{project_name}
descriptionFieldName	no	set this property if your description system field name in TestRail different from "custom_description"	custom_description
expectedFieldName	no	set this property if your expected system field name in TestRail different from "custom_expected"	custom_expected
preconditionStructure	no	set this property if your description system field name in TestRail different from "preconds" or you want to migrate a several fields into precondition you can define the structure like: preconditionStructure: [   {     "customFieldName":"custom_field1",     "displayName":"Precondition1"   },   {     "customFieldName":"custom_field2",     "displayName":"Precondition2"   } ] Where: - customFieldName is the name from testrail - displayName the name for section in the TestOps’s Precondition area in testcase The result will be like: Precondition1 Some text from custom field (custom_field1) Precondition2 Some text from custom field (custom_field2)	preconditionStructure: [   {     "customFieldName":"custom_field1",     "displayName":"Precondition1"   },   {     "customFieldName":"custom_field2",     "displayName":"Precondition2"   } ]
stepsSeparatedFieldName	no	set this property if your description system field name in TestRail different from "custom_steps_separated"	custom_steps_separated
useParentDescription	no	Flag to augment the test case description with the description of its parent sections and suites. “TestRail Suite description” → “TestOps test case description”	false
stepsAsPrecondition	no	Flag to set the value from testrail custom_steps into allure precondition field in format: <Value from precondition> <Value from steps>	false
usePrimarySeparatedSteps	no	if you have both steps and steps_separated you can specify that steps_sepaated as a base for migration
requiredCfMapping	no	Flag to indicate if the custom field mapping is required. If setted to false the int value will be taken as a value for allure custom field.	true
createdByAsOwner	no	If you want migrate created by field as testops member owner	false
withDeleted	no	If you want to migrate the cases which were marked as is_deleted; with work only with oldBulkApi=false or unsetted	true
withSharedSteps	no	!!! use this option only if you are sure that allure testops support shared steps	false
withExpectedStep	no	use it if you want migrate expected result as expected part of TestOps’s step	false
withFieldStepMapping	no	If you see an error like: LinkedHashMap cannot be cast to Field$Step set this property to false	true
refsAsLinks	no	Allows you to migrate the TestRail case field "refs" as links to the TestOps testcase. Use it if you store links in the "refs" field.	false
stepsFieldAsSingleStep	no	Set to true to use the content from the field custom_steps as a single step in TestOpst	false
customTagSeparator	no	Set separator for tags if needed If your TR field contains values like “tag1, tag2, tag3” you can use “,” as customTagSeparator to split them.	,
attachmentsLinkPattern	no	If you have an attachment in TestRail case's steps in the markdown format like  you can convert it into the html attachment. Please specify the regex to collect your link address. Important to use "link" and "name" groups	!\\[]\$begin:math:text$(?<link><http://some.url/%5Ba-zA-Z0-9%5D+/(?%3Cname%3E%5Ba-zA-Z0-9-%5D+)%5C%5C.jpg>)\\$end:math:text$
customFieldsAsLinks	no	If you want to set some customefield value as TestOps link	customFieldsAsLinks: [   "custom_link", "custom_links_url" ]
statusMapping	no	name - the name of custom field in the TR system "workflowId" - id of the workflow from TestOps values in format ”testRailStatusId”:”Allure TestOps status name” !!! The first founded mapping will be used for the migration	statusMapping: [   {     "name": "custom_status",     "workflowId": 1,     "values": {       "1": "Draft",       "2": "Active"     }   },   {     "name": "custom_status_auto",     "workflowId": 2,     "values": {       "1": "Start",       "2": "Automated"     }   } ]```
customFields	no	A list of testrail fields which need to be migrate to allure as custom fields. Structure: "testrail_field_name": "Allure_custom_field_name" If the value represented as an id in the testrail system the values mapping can be specified in customFieldsMapping field To get the real TestRail system names please execute a request: GET <TR-url>/index.php?/api/v2/get_case/{case_id} With basic auth and credentials from this config. In the json response will be all fields names with prefix "custom_".	customFields: {   "suite_id": "Suite",   "priority_id": "Priority",   "custom_tester": "Owner",   "custom_system": "System" }
customFieldsMapping	no	A TestRail id to value mapping. Structure: name: TestRail field name values: A map with id and its value.	customFieldsMapping: [   {     "name": "priority_id",     "values": {       "1": "Low",       "2": "Medium",       "3": "High",       "4": "Critical"     }   },   {     "name": "custom_tester",     "values": {       "1": "Tester QA1",       "2": "Tester QA2",       "3": "Tester QA3",       "4": "Tester QA4"     }   } ]```