TestRail API Python Wrapper

1.13.6 · active · verified Sat Apr 11

testrail-api is a Python wrapper for the TestRail API, enabling programmatic interaction with TestRail instances for managing test cases, runs, results, and more. It is actively maintained with frequent minor releases, typically addressing new TestRail API features, bug fixes, and Python version compatibility. The current version is 1.13.6.

Warnings

breaking Python 3.8 support was removed in version 1.13.4. Users on Python 3.8 or older must upgrade their Python environment to 3.9+ or pin the library version to `<1.13.4`.
Fix: Upgrade Python to 3.9 or higher, or explicitly install `testrail-api<1.13.4`.
gotcha When using an API Key for authentication (recommended by TestRail), the key should be passed to the `password` argument, not `api_key` or another field. TestRail's API documentation refers to this as the 'password' for HTTP Basic Auth.
Fix: Always pass your TestRail API key value to the `password` parameter when initializing `TestRailAPI`.
gotcha While the library includes custom exception retry handling (since 1.11.0), applications should still implement robust error handling for TestRail API rate limits (HTTP 429 Too Many Requests) and other server-side errors to ensure stability.
Fix: Wrap API calls in `try...except` blocks to catch potential `TestRailError` exceptions or other HTTP client errors and implement custom retry logic if necessary beyond the library's defaults.
gotcha For retrieving large datasets of suites or users, prefer the recently added bulk methods (`get_suites`, `get_users` with `offset`/`limit` parameters or dedicated bulk methods like `get_suites_bulk`, `get_users_bulk` if available) to avoid hitting API rate limits or performance issues associated with many individual requests.
Fix: Consult the library documentation for available bulk or paginated methods when fetching large collections of resources.

Install

pip install testrail-api Install stable version

Imports

TestRailAPI
```
from testrail_api import TestRailAPI
```
The main class is directly importable from the top-level package, not from a nested module.

Quickstart

This quickstart demonstrates how to initialize the TestRail API client using environment variables for credentials and fetch a list of projects. Ensure you replace the placeholder values or set your environment variables correctly.

import os
from testrail_api import TestRailAPI

# Ensure these environment variables are set:
# TR_BASE_URL (e.g., 'https://yourinstance.testrail.io/')
# TR_USER (e.g., 'user@example.com')
# TR_PASSWORD_OR_API_KEY (API key is recommended)

TR_BASE_URL = os.environ.get('TR_BASE_URL', '')
TR_USER = os.environ.get('TR_USER', '')
TR_PASSWORD_OR_API_KEY = os.environ.get('TR_PASSWORD_OR_API_KEY', '')

if not all([TR_BASE_URL, TR_USER, TR_PASSWORD_OR_API_KEY]):
    print("Please set TR_BASE_URL, TR_USER, and TR_PASSWORD_OR_API_KEY environment variables.")
    exit(1)

try:
    client = TestRailAPI(
        base_url=TR_BASE_URL,
        user=TR_USER,
        password=TR_PASSWORD_OR_API_KEY,
    )

    # Example: Get all projects
    projects = client.projects.get_projects()
    print(f"Successfully connected. Found {len(projects)} projects.")
    if projects:
        print(f"First project: {projects[0]['name']}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →