TestRail Configuration Guide

Overview

DMtools provides 15 MCP tools for TestRail integration, enabling automated test case creation, requirement linking, and test management directly from Jira/ADO stories.

If you only need the TestRail-focused AI assistant package, install /dmtools-testrail with the instructions in ../../installation/README.md#install-only-the-skills-you-need.

API Key Generation

Step 1: Create TestRail API Key

1. Log in to your TestRail instance
2. Go to My Settings (top-right user menu)
3. Open the API Keys tab
4. Click “Add Key”, give it a name (e.g. “DMtools Integration”)
5. Copy the key immediately

Step 2: Configure DMtools

Add to your dmtools.env:

# TestRail Configuration
TESTRAIL_BASE_PATH=https://yourcompany.testrail.io
TESTRAIL_USERNAME=your-email@company.com
TESTRAIL_API_KEY=your_api_key

Configuration Variables

Required Variables

Optional Variables

Markdown Output for Test Case Fields

TestRail case fields (preconditions, steps, expected results) are often pasted from Google Docs or a browser, which bakes every computed CSS property into inline style="..." attributes on every tag — this can make the raw HTML 20-30x larger than the actual visible text, wasting tokens when fed to an LLM.

testrail_get_case, testrail_get_all_cases, and testrail_search_cases accept an optional format parameter: pass format=md (or format=markdown) to receive these fields converted to clean Markdown instead (tables are preserved as GitHub-Flavoured Markdown tables, so no data is lost).

# Explicit per-call opt-in
dmtools testrail_get_all_cases "My Project" --format md

To make Markdown the default for every TestRail read — including internal callers like TestCasesGenerator’s “find related existing test cases” search, which don’t pass format themselves — set TESTRAIL_DEFAULT_FORMAT=markdown in dmtools.env. An explicit format argument on any call always overrides this default.

# dmtools.env
TESTRAIL_DEFAULT_FORMAT=markdown

Testing Your Configuration

# List all projects (basic connection test)
dmtools testrail_get_projects

# Get all cases in a project
dmtools testrail_get_all_cases "My Project"

# Find cases linked to a Jira story
dmtools testrail_get_cases_by_refs PROJ-123 "My Project"

Generating Test Cases from Jira Stories

The TestCasesGenerator job reads stories from Jira and creates test cases in TestRail.

Steps Template (recommended)

# Create agents/testrail_test_cases_generator.json with your config
dmtools run agents/testrail_test_cases_generator.json

{
  "name": "TestCasesGenerator",
  "params": {
    "inputJql": "key in (PROJ-123)",
    "outputType": "creation",
    "customTestCasesTracker": {
      "type": "testrail",
      "params": {
        "projectNames": ["My Project"],
        "creationMode": "steps",
        "typeName": "Functional",
        "labelNames": ["ai_generated"]
      }
    },
    "testCasesPriorities": "Critical, High, Medium, Low",
    "testCasesCustomFields": ["custom_preconds", "custom_steps_json"],
    "customFieldsRules": "custom_preconds: Write preconditions as plain text. custom_steps_json: Write test steps as a JSON array where each object has 'content' (the action to perform) and 'expected' (the expected result for that step). Example: [{\"content\":\"Open the app\",\"expected\":\"App opens successfully\"}]",
    "isFindRelated": true,
    "isLinkRelated": true,
    "isGenerateNew": true,
    "isConvertToJiraMarkdown": false
  }
}

Using Project IDs (large TestRail instances)

If your TestRail instance has more than 250 projects and the target project doesn’t appear at the top of the list, use projectIds instead of (or alongside) projectNames to bypass name-based resolution entirely:

"customTestCasesTracker": {
  "type": "testrail",
  "params": {
    "projectIds": [42],
    "targetProjectId": 42,
    "creationMode": "steps",
    "typeName": "Functional",
    "labelNames": ["ai_generated"]
  }
}

To find a project ID:

dmtools testrail_get_projects

Full guide: ../../test-generation/testrail-manual.md

Generating Diagrams from TestRail Test Cases

You can generate a Mermaid diagram for every TestRail test case in a project or suite.

# Generate diagrams for all cases in a TestRail project/suite
dmtools mermaid_index_generate testrail '["project_id=5&suite_id=3"]' '[]' ./mermaid-diagrams

Requirements:

• TESTRAIL_BASE_PATH, TESTRAIL_USERNAME, and TESTRAIL_API_KEY must be configured.
• The first include_patterns entry is passed directly to TestRail as the API query for get_cases.

Output is stored under ./mermaid-diagrams/testrail/CASE_KEY/CaseTitle.mmd, for example:

./mermaid-diagrams/testrail/
└── C12345
    └── Verify_Login_Page.mmd

Read generated diagrams back with:

dmtools mermaid_index_read testrail ./mermaid-diagrams

Available TestRail MCP Tools

Complete reference: ../../mcp-tools/testrail-tools.md — all 16 TestRail tools with parameters.

Quick Examples

# Get all projects
dmtools testrail_get_projects

# Get test cases linked to a story
dmtools testrail_get_cases_by_refs PROJ-123 "My Project"

# Get available case types
dmtools testrail_get_case_types

# Get labels for a project
dmtools testrail_get_labels "My Project"

# Delete a test case (numeric ID without 'C' prefix)
dmtools testrail_delete_case 42

JavaScript Agent Access

// Direct MCP tool access in agents
const projects = testrail_get_projects();
const cases = testrail_get_cases_by_refs("PROJ-123", "My Project");
const caseTypes = testrail_get_case_types();
testrail_link_to_requirement("42", "PROJ-123");

Troubleshooting

Authentication Failed (401)

# Verify credentials
# Check TESTRAIL_USERNAME is your login email (not display name)
# Regenerate API key in TestRail My Settings → API Keys

Project Not Found

# List all projects to get exact names (case-sensitive)
dmtools testrail_get_projects

Enable Debug Logging

# dmtools.env
TESTRAIL_LOGGING_ENABLED=true

# Re-run your command — all API requests/responses will be logged

Security Best Practices

# Never commit credentials
echo "dmtools.env" >> .gitignore

# Use environment variables in CI/CD
export TESTRAIL_API_KEY=${{ secrets.TESTRAIL_API_KEY }}

Next: TestRail Test Generation Guide | TestRail MCP Tools | Jira Setup