TestRail API: Automating Test Runs from CI/CD Pipelines

TestRail API: Automating Test Runs from CI/CD Pipelines

Running automated tests in CI without reporting results back to TestRail is half-baked. Your CI pipeline knows which tests passed and failed, but that information stays in GitHub Actions logs — invisible to QA leads, product managers, and anyone tracking release readiness. The TestRail API bridges this gap: create runs programmatically, post results automatically, and close runs when the suite finishes.

This guide covers the complete TestRail API workflow: authentication, creating runs, updating results from pytest/Jest/JUnit output, querying results, and a complete GitHub Actions example.

TestRail REST API Basics

TestRail's API is REST-based, uses Basic Auth, and returns JSON. Base URL structure:

https://your-domain.testrail.io/index.php?/api/v2/{method}

Authentication uses your TestRail email and an API key (not your password). Generate the API key in TestRail under My Settings > API Keys.

# Test authentication
curl -u "your@email.com:YOUR_API_KEY" \
  "https://your-domain.testrail.io/index.php?/api/v2/get_projects"

All POST requests require Content-Type: application/json.

Key Resource IDs

You'll need to reference these by ID throughout the API:

  • Project ID (project_id): Found in the URL when viewing a project: .../overview/1
  • Suite ID (suite_id): Found in the URL when viewing a suite: .../suites/view/5
  • Milestone ID (milestone_id): Found in the URL: .../milestones/view/3
  • Test Case ID (case_id): Shown in the case list as C123 (strip the C for the API)
  • Test Run ID (run_id): Created by the API or found in run URLs
  • Test ID (test_id): Different from case ID — the per-run instance of a case

The test_id vs case_id distinction is important: when you add cases to a run, TestRail creates test instances with their own IDs. Use get_tests to retrieve test IDs for a run, then use those IDs when posting results.

Creating Test Runs via API

curl -u "$TESTRAIL_EMAIL:$TESTRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://your-domain.testrail.io/index.php?/api/v2/add_run/1" \
  -d '{
    "suite_id": 5,
    "name": "Automated: Main Suite - 2026-06-01 #42",
    "description": "GitHub Actions run #42, commit abc123",
    "milestone_id": 3,
    "include_all": false,
    "case_ids": [1, 2, 3, 4, 5]
  }'

Response:

{
  "id": 87,
  "suite_id": 5,
  "name": "Automated: Main Suite - 2026-06-01 #42",
  "milestone_id": 3,
  "created_on": 1748736000,
  "is_completed": false,
  "passed_count": 0,
  "failed_count": 0,
  "untested_count": 5
}

The returned id (87 here) is your run ID for subsequent API calls.

include_all: true includes all cases in the suite. include_all: false with case_ids includes only specific cases. For automated test runs, map your test names to TestRail case IDs and only include cases that have automation.

Getting Tests from a Run

Before posting results, fetch the test instances to get test_id values:

curl -u "$TESTRAIL_EMAIL:$TESTRAIL_API_KEY" \
  "https://your-domain.testrail.io/index.php?/api/v2/get_tests/87"

Response:

{
  "offset": 0,
  "limit": 250,
  "size": 5,
  "tests": [
    {
      "id": 1001,
      "case_id": 1,
      "title": "Login with valid credentials",
      "status_id": 3
    },
    {
      "id": 1002,
      "case_id": 2,
      "title": "Login with invalid password",
      "status_id": 3
    }
  ]
}

Status IDs: 1=Passed, 2=Blocked, 3=Untested, 4=Retest, 5=Failed.

Posting Test Results

Single Result

curl -u "$TESTRAIL_EMAIL:$TESTRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://your-domain.testrail.io/index.php?/api/v2/add_result/1001" \
  -d '{
    "status_id": 1,
    "comment": "Passed in 0.34s",
    "elapsed": "0s",
    "defects": ""
  }'

Bulk Results (Preferred for Automation)

The add_results_for_cases endpoint is more efficient — post all results for a run in one call using case IDs directly:

curl -u "$TESTRAIL_EMAIL:$TESTRAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://your-domain.testrail.io/index.php?/api/v2/add_results_for_cases/87" \
  -d '{
    "results": [
      {
        "case_id": 1,
        "status_id": 1,
        "comment": "Passed in 0.34s",
        "elapsed": "1s"
      },
      {
        "case_id": 2,
        "status_id": 5,
        "comment": "FAILED: Expected 401, got 200\n\nStack trace:\n  test_login.py:45",
        "defects": "JIRA-1234",
        "elapsed": "2s"
      },
      {
        "case_id": 3,
        "status_id": 1,
        "elapsed": "0s"
      }
    ]
  }'

Use add_results_for_cases over add_result (per test) whenever possible. It reduces API calls from N to 1.

Parsing pytest Results

pytest generates JUnit XML output that you can parse to build TestRail results. The key is mapping pytest test names to TestRail case IDs.

The simplest approach: embed the case ID in the test name or docstring:

# tests/test_login.py

def test_login_valid_credentials():
    """TestRail: C1 - Login with valid credentials"""
    # ... test code
    pass

def test_login_invalid_password():
    """TestRail: C2 - Login with invalid password shows error"""
    # ... test code
    pass

Or use a custom pytest marker:

import pytest

@pytest.mark.testrail(case_id=1)
def test_login_valid_credentials():
    pass

@pytest.mark.testrail(case_id=2)
def test_login_invalid_password():
    pass

Then a conftest or CI script reads the marker and maps results:

# scripts/report_to_testrail.py
import subprocess
import json
import xml.etree.ElementTree as ET
import requests
import os

TESTRAIL_URL = os.environ["TESTRAIL_URL"]
TESTRAIL_EMAIL = os.environ["TESTRAIL_EMAIL"]
TESTRAIL_API_KEY = os.environ["TESTRAIL_API_KEY"]
PROJECT_ID = int(os.environ.get("TESTRAIL_PROJECT_ID", "1"))
SUITE_ID = int(os.environ.get("TESTRAIL_SUITE_ID", "5"))
MILESTONE_ID = int(os.environ.get("TESTRAIL_MILESTONE_ID", "0")) or None

auth = (TESTRAIL_EMAIL, TESTRAIL_API_KEY)
base_url = f"{TESTRAIL_URL}/index.php?/api/v2"

def parse_junit_xml(xml_file):
    """Parse JUnit XML and extract test results with TestRail case IDs."""
    tree = ET.parse(xml_file)
    root = tree.getroot()
    results = []

    for testcase in root.iter("testcase"):
        # Look for testrail_id in properties or classname
        properties = testcase.find("properties")
        case_id = None

        if properties:
            for prop in properties:
                if prop.get("name") == "testrail_case_id":
                    case_id = int(prop.get("value"))

        if not case_id:
            continue  # Skip test cases without a TestRail mapping

        failure = testcase.find("failure")
        error = testcase.find("error")

        if failure is not None:
            status_id = 5  # Failed
            comment = f"FAILED: {failure.get('message', '')}\n\n{failure.text or ''}"
        elif error is not None:
            status_id = 5
            comment = f"ERROR: {error.get('message', '')}\n\n{error.text or ''}"
        else:
            status_id = 1  # Passed
            comment = f"Passed in {testcase.get('time', '0')}s"

        elapsed_s = float(testcase.get("time", "0"))
        elapsed_str = f"{int(elapsed_s)}s" if elapsed_s >= 1 else "1s"

        results.append({
            "case_id": case_id,
            "status_id": status_id,
            "comment": comment,
            "elapsed": elapsed_str,
        })

    return results

def create_run(name, case_ids, milestone_id=None):
    payload = {
        "suite_id": SUITE_ID,
        "name": name,
        "include_all": False,
        "case_ids": case_ids,
    }
    if milestone_id:
        payload["milestone_id"] = milestone_id

    response = requests.post(
        f"{base_url}/add_run/{PROJECT_ID}",
        json=payload,
        auth=auth,
    )
    response.raise_for_status()
    return response.json()["id"]

def post_results(run_id, results):
    response = requests.post(
        f"{base_url}/add_results_for_cases/{run_id}",
        json={"results": results},
        auth=auth,
    )
    response.raise_for_status()

def close_run(run_id):
    response = requests.post(
        f"{base_url}/close_run/{run_id}",
        auth=auth,
    )
    response.raise_for_status()

if __name__ == "__main__":
    import sys
    xml_file = sys.argv[1]
    run_name = sys.argv[2] if len(sys.argv) > 2 else "Automated Run"

    results = parse_junit_xml(xml_file)
    if not results:
        print("No TestRail-mapped test results found.")
        sys.exit(0)

    case_ids = [r["case_id"] for r in results]
    run_id = create_run(run_name, case_ids, MILESTONE_ID or None)
    print(f"Created TestRail run: {run_id}")

    post_results(run_id, results)
    print(f"Posted {len(results)} results")

    close_run(run_id)
    print(f"Closed run {run_id}")

    failed = sum(1 for r in results if r["status_id"] == 5)
    print(f"Summary: {len(results) - failed} passed, {failed} failed")
    if failed > 0:
        sys.exit(1)

Parsing Jest Results

Jest with --reporters=jest-junit generates JUnit XML. Map test names to case IDs:

// jest.config.js
module.exports = {
  reporters: [
    "default",
    ["jest-junit", {
      outputDirectory: "test-results",
      outputName: "junit.xml",
      classname: "{classname}",
      title: "{title}",
      // Add custom properties with case IDs
    }]
  ]
};

In test files, add the case ID as a custom property:

// login.test.js
describe("Login", () => {
  test("C1: valid credentials redirect to dashboard", async () => {
    // test code
  });

  test("C2: invalid password shows error message", async () => {
    // test code
  });
});

Then parse the C123 prefix in test titles to extract case IDs in the reporting script.

Complete GitHub Actions Example

# .github/workflows/test-and-report.yml
name: Test Suite with TestRail Reporting

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      TESTRAIL_URL: ${{ secrets.TESTRAIL_URL }}
      TESTRAIL_EMAIL: ${{ secrets.TESTRAIL_EMAIL }}
      TESTRAIL_API_KEY: ${{ secrets.TESTRAIL_API_KEY }}
      TESTRAIL_PROJECT_ID: "1"
      TESTRAIL_SUITE_ID: "5"
      TESTRAIL_MILESTONE_ID: ${{ secrets.TESTRAIL_MILESTONE_ID }}

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install pytest pytest-junit requests

      - name: Run tests with JUnit output
        run: |
          pytest tests/ \
            --junitxml=test-results/junit.xml \
            -v \
            --tb=short
        continue-on-error: true  # Don't fail here — report results first

      - name: Report results to TestRail
        if: always()  # Run even if tests failed
        run: |
          RUN_NAME="CI: ${{ github.ref_name }} - $(date +%Y-%m-%d) #${{ github.run_number }}"
          python scripts/report_to_testrail.py test-results/junit.xml "$RUN_NAME"

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-results
          path: test-results/

      - name: Fail if tests failed
        if: failure()
        run: exit 1

The key pattern: continue-on-error: true on the test step, then if: always() on the reporting step. This ensures results always get reported to TestRail even when tests fail.

Querying Results for Reporting

Get results from a run for custom reporting:

# Get all results for a run
curl -u "$TESTRAIL_EMAIL:$TESTRAIL_API_KEY" \
  "https://your-domain.testrail.io/index.php?/api/v2/get_results_for_run/87?limit=250"

# Filter by status (1=passed, 5=failed)
curl -u "$TESTRAIL_EMAIL:$TESTRAIL_API_KEY" \
  "https://your-domain.testrail.io/index.php?/api/v2/get_results_for_run/87?status_id=5"

Get milestone progress:

curl -u "$TESTRAIL_EMAIL:$TESTRAIL_API_KEY" \
  "https://your-domain.testrail.io/index.php?/api/v2/get_milestone/3"

The milestone response includes is_completed, dates, and counts of completed vs. total runs. Use this to build custom Slack notifications or dashboard integrations.

Closing Test Runs

Always close runs when automation finishes. Open runs remain visible in active dashboards and skew coverage metrics:

curl -u "$TESTRAIL_EMAIL:$TESTRAIL_API_KEY" \
  -X POST \
  "https://your-domain.testrail.io/index.php?/api/v2/close_run/87"

Closed runs are read-only but visible in historical reports. Close them immediately after all results are posted — not at end of day, not at end of sprint, immediately after the CI job finishes.

Connecting TestRail to CI turns test case management from a manual tracking exercise into a live release quality dashboard. Every push updates the milestone progress. Every failure links directly to a runnable test case. Every go/no-go decision is backed by data from actual test runs rather than someone's estimate.

Read more

Start now free