testrail-api

library1.13.6pypypi✓ verified 22d ago

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.

testing crm-productivity http-networking

pip install testrail-api

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TESTRAIL-API

testrail-api

testingpythonv1.13.6

Install

2.2s avg

Import

377ms

Disk

19MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.13.6 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.388s · 21.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.366s · 22MB

19MB installed

● package 19MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TestRailAPI

✓ from testrail_api import TestRailAPI

✗ from testrail_api.testrail_api import TestRailAPI

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

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}")

Debug

Known issues

breakingPython 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`.

affects: >=1.13.4

gotchaWhen 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`.

affects: All

gotchaWhile 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.

affects: All

gotchaFor 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.

affects: >=1.13.5

Errors

Common errors & fixes

TestRailError: TestRail API returned HTTP 401 ("Unauthorized")

The provided TestRail URL, username, or API key/password is incorrect or lacks the necessary permissions to access the API.

fix

Double-check your TestRail URL, username, and API key (or password) to ensure they are correct and the user has API access permissions: `client = TestRailAPI('https://your-domain.testrail.io/', 'your_username', 'your_api_key_or_password')`

ModuleNotFoundError: No module named 'testrail_api'

The `testrail-api` package has not been installed in the current Python environment or is not correctly added to the Python path.

fix

Install the package using pip: `pip install testrail-api`

AttributeError: 'TestRailAPI' object has no attribute 'get_case'

Methods like `get_case` are part of specific resource objects (e.g., `client.cases`), not directly available on the main `TestRailAPI` client object.

fix

Access methods through the appropriate resource object, such as `case = client.cases.get_case(case_id)`

requests.exceptions.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

The TestRail API returned a response that was not valid JSON, often indicating an unexpected server error (e.g., 500 Internal Server Error, returning HTML) or a malformed API response.

fix

Check the TestRail instance status and the specific API endpoint being called for server-side errors; you might need to inspect the raw response text: `try: response_data = client.cases.get_case(case_id) except requests.exceptions.JSONDecodeError as e: print(f'API returned non-JSON: {e.response.text}')`

TestRailError: TestRail API returned HTTP 400 ("Invalid or unknown run or case")

The parameters provided to the TestRail API method (e.g., `run_id`, `case_id`, `status_id`, `project_id`) are either missing, malformed, or refer to non-existent entities in TestRail.

fix

Verify that all required parameters are provided with correct values and refer to valid, existing entities in TestRail, for example: `client.results.add_result_for_case(run_id=1, case_id=101, status_id=1)`

Upgrade

Version history

1.13.6latest on PyPI · released Jan 16, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

53 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/tolstislon/testrail-api ↗

packagehttps://pypi.org/project/testrail-api/ ↗

homepagehttps://www.gurock.com/testrail/ ↗