TestRail Integration

This page explains how to:

• Import existing TestRail test cases into GPT Driver.

• Push GPT Driver execution results back to TestRail.

Good To Know

• Credentials are encrypted at rest, used only for the current request, and never persisted in plain text.

• Import is idempotent – running it twice updates unchanged cases instead of creating duplicates.

• Missing or invalid fields return 400 Invalid request with a list of offending keys.

Importing Test Cases From TestRail

1. Generate an API Token in TestRail (My Settings → API Keys).

2. POST ​/testrail/import with the payload below.

3. Receive a test_ids array; the referenced tests are ready to run via the usual /tests/execute endpoint.

POST /testrail/import

{
  "organisationId": "org123",
  "testrail": {
    "url": "https://acme.testrail.io",
    "apiToken": "TR_BASIC_XXXXXXXXXXXXXXXXXXXXXXXX",
    "projectId": 42,
    "suiteId": 371 // optional – omit to import all suites
  }
}

Required & Optional Fields

Field	Required	Description
url	yes	Base URL of the TestRail instance
apiToken	yes	Personal access token with “Add & Modify” permission
projectId	yes	Numeric project id
suiteId	no	Limit import to a single suite

How We Translate TestRail Objects

TestRail	GPT Driver
Section	Folder
Test Case	Test
Test Case Step	Command
Preconditions field	Dependency (executed before the main test)

If the Preconditions field references multiple cases we create an ordered dependency chain that runs before the main test. Circular references are detected and rejected with a 409 Conflict response.

Sample Response

{
  "imported": 128,
  "updated": 14,
  "dependenciesCreated": 23,
  "testIds": [
    "te_7Xc1PqM",
    "te_b19Lzg8Y",
    "…"
  ]
}

Exporting Results To TestRail

There are two ways to push execution results back to TestRail:

1. Automatic Push (Recommended)

1. Open Settings  >  Integrations >  TestRail.

2. Enter the same url, apiToken, and projectId values.

3. Save - every completed suite now triggers an automatic push.

2. Custom Push Via Webhook API

If you need custom mapping logic, point the generic Webhook URL to your own service that calls TestRail’s add_run and add_results_for_cases endpoints.

Webhook payload example:

{
  "testSuiteId": "...",
  "totalTests": 1,
  "succeededTests": [
    {
      "testRailId": "1",
      "id": "...",
      "title": "Login with valid password",
      "statusMessage": "Login successful. Home screen is visible.",
      "recording": "..."
    }
  ],
  "failedTests": [],
  "blockedTests": []
}