testrail-to-zephyr

A CLI tool to migrate test cases from TestRail to Zephyr Scale, preserving section hierarchy and handling complex field mappings.

Motivation

• Preserve section hierarchy: TestRail's nested sections → Zephyr's folder structure
• Handle complex fields: Array fields like custom_steps_separated → Zephyr test steps
• Flexible mapping: Custom field mapping via YAML configuration

Installation

npm install -g testrail-to-zephyr

Quick Start

1. Create project configuration

Create project.yaml:

Finding Zephyr folderId (optional): If you want to create test cases in a specific folder:

1. Open Zephyr in Chrome
2. Navigate to the target folder
3. Open Chrome DevTools (F12) → Elements tab
4. Find the folder name element with data-testid="folder-name-with-count-{folderId}"

   <span class="name-wrapper" data-testid="folder-name-with-count-111111">

5. Extract the folder ID from the attribute (e.g., 111111)
6. Set folderId: 111111 in project.yaml (or leave as null for project root)

testRail:
  baseUrl: https://your-domain.testrail.io
  projectId: 1
  suiteId: 123
  user: [email protected]
  apiKey: your-api-key

zephyr:
  projectKey: YOUR_PROJECT_KEY
  folderId: null
  apiKey: your-api-key

2. Prepare mapping

Fetch sample data and generate mapping template:

testrail-to-zephyr prepare -p project.yaml

This creates:

• projects/{suiteId}/sample_testrail_cases.json - Sample TestRail test cases
• projects/{suiteId}/sample_zephyr_test_cases.json - Sample Zephyr test cases
• projects/{suiteId}/mapping.yaml - Field mapping template

3. Configure mapping

Edit projects/{suiteId}/mapping.yaml to map fields:

fields:
  name: title
  precondition: custom_preconds
  objective: custom_expected
  testSteps:
    source: custom_steps_separated
    mapping:
      description: content
      expectedResult: expected

# Fields to remove line breaks from
# Supports nested fields (e.g., "testSteps.description")
deleteLineBreaks:
  - name

defaults:
  priorityName: Normal
  statusName: Draft

deleteLineBreaks option:

• Removes line breaks (\n, \r\n) from specified fields
• Useful for fields that don't accept multi-line values (e.g., name)
• Can be applied to nested fields: testSteps.description, customFields.myField

4. Convert data

Transform TestRail data to Zephyr format:

testrail-to-zephyr convert -p project.yaml -m projects/{suiteId}/mapping.yaml

5. Migrate to Zephyr

Create folders and test cases in Zephyr:

testrail-to-zephyr migrate -p project.yaml

Commands

prepare

Fetch sample data and generate mapping template.

Options:

• -p, --project <path> - Path to project.yaml (required)

convert

Transform TestRail data to Zephyr format using mapping configuration.

Options:

• -p, --project <path> - Path to project.yaml (required)
• -m, --mapping <path> - Path to mapping.yaml (required)

migrate

Create folders and test cases in Zephyr.

Options:

• -p, --project <path> - Path to project.yaml (required)

Note: Migration is batched (50 test cases per batch) with 15-second delays to avoid API rate limits.

Output Structure

projects/{suiteId}/
├── sample_testrail_cases.json       # Sample data from TestRail
├── sample_zephyr_test_cases.json    # Sample data from Zephyr
├── mapping.yaml                      # Field mapping configuration
├── artifacts/                        # Intermediate files
│   ├── testrail_sections.json       # All sections (sorted by depth)
│   ├── testrail_cases.json          # All test cases
│   ├── testcase_requests.json       # Transformed Zephyr requests
│   └── section_mapping.json         # Section → Folder mapping
└── results/                          # Final output
    └── testcase_mapping.json        # TestRail → Zephyr mapping

Test Case Mapping Output

After migration, results/testcase_mapping.json contains the mapping between TestRail and Zephyr test cases:

[
  {
    "testRailCaseId": 123,
    "testRailCaseName": "General User can't see the settings page",
    "testRailSectionId": 10,
    "zephyrTestCaseId": "10001",
    "zephyrTestCaseName": "PROJ-T1"
  },
  {
    "testRailCaseId": 124,
    "testRailCaseName": "Admin user can access the settings page",
    "testRailSectionId": 10,
    "zephyrTestCaseId": "10002",
    "zephyrTestCaseName": "PROJ-T2"
  }
]

Use this file to:

• Track which TestRail cases were migrated to which Zephyr cases
• Reference test case IDs in other tools
• Verify migration completeness

Features

• Section hierarchy preservation: Maintains TestRail's nested section structure as Zephyr folders
• Array field mapping: Maps TestRail array fields (e.g., custom_steps_separated) to Zephyr test steps
• Nested field support: Handles nested Zephyr fields like customFields.automationType
• Batch processing: Processes test cases in batches with delays to avoid rate limits
• Error resilience: Continues on failures and provides detailed summary
• Traceability: Generates mapping files to track TestRail ID → Zephyr ID relationships

Debug Mode

Enable debug logging:

DEBUG=true testrail-to-zephyr prepare -p project.yaml

License

MIT

Author

bun913