---
id: pytest-testrail
version: "3.1.1"
license: MIT
license_treatment: permissive
maintenance: aging
---

# pytest-testrail — A pytest plugin for creating TestRail runs and adding results

License: permissive · Maintenance: aging · Downloads: 123.3K/mo

## What it is and what it does

pytest-testrail is a pytest plugin that bridges test execution and TestRail test management. It reads pytest markers to identify which tests should be added to a TestRail test run, executes them, and automatically pushes results back to TestRail. The plugin handles test run creation, result updates, and defect tracking integration.

Version 3.1.1 is a modernized release requiring Python 3.10+, with full type hints, API key authentication (recommended over passwords), connection pooling via requests, automatic retry on rate limiting, and proper exception handling. It depends on pytest and requests, and supports TestRail API pagination for TestRail 6.7+. Configuration is done via INI file or command-line options, and the plugin can be used both as a pytest plugin or as a standalone APIClient for programmatic access.

Use it for:

- Automatically create and populate TestRail test runs from pytest test suites marked with @pytestrail.case decorators.
- Push test results back to TestRail after pytest execution, keeping test management synchronized with CI/CD pipelines.
- Link test failures to defects in Jira or other tracking systems using @pytestrail.defect markers.
- Query TestRail data programmatically via the APIClient for custom reporting or test orchestration.
- Handle paginated TestRail API responses when working with large test case inventories.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A pytest plugin that integrates test execution with TestRail, automatically creating test runs and updating results in TestRail based on pytest markers.

Yes, if you use TestRail and pytest together. The plugin has low install friction, permissive licensing, no known vulnerabilities, and is actively maintained (last commit January 2026). The aging maintenance status (201 days since last release) is not a blocker for stable integrations, but verify that your TestRail version and API requirements align before deploying to production.

## Install

pip install pytest-testrail
uv add pytest-testrail
poetry add pytest-testrail

## Installing pytest-testrail

Before you install: Low install friction with a pure-Python wheel. Maintenance status is aging—last release was 201 days ago—but the repository remains active and not archived, with recent commits as of 2026-01-25.

License in practice: MIT license (permissive) places no restrictions on use, modification, or distribution for commercial or private projects.

Quickstart:

pip install pytest-testrail

from pytest_testrail.plugin import pytestrail

@pytestrail.case('C1234')
def test_example():
    pass

# Run with: pytest --testrail --tr-config=testrail.cfg

Requires Python 3.10 or later; TestRail server credentials (URL, email/API key, project/suite IDs) must be configured via config file or command-line options.

Verify before relying:

- Whether automatic retry on rate limiting (HTTP 429) is fully tested under production load.
- Compatibility with TestRail versions older than 6.7 (pagination support requires 6.7+).
- Performance characteristics when handling large test suites with connection pooling.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 123.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest testrail integration, test rail automation, pytest test management, testrail api client, automated test reporting, pytest markers testrail, test run creation automation, test-management, testrail-integration, ci-cd

[View on SkillFed](https://skillfed.io/packages/pytest-testrail) · [View on PyPI](https://pypi.org/project/pytest-testrail/)