py-testrail-cli 0.1.0

Python-based CLI for complete TestRail REST API access and CSV-driven case management

TestRail CLI

A powerful Python-based CLI for complete TestRail REST API access with CSV-driven case management.

Features

• Complete API Coverage: Access all TestRail REST API endpoints through intuitive commands
• Multi-Profile Support: Manage multiple TestRail instances with named profiles
• CSV Import/Export: Bulk import test cases from CSV with field mapping
• Flexible Output: JSON, table, or filtered field output formats
• CI/CD Ready: Perfect for automation pipelines and scripting
• Type-Safe: Full type hints and mypy validation
• Well-Tested: Comprehensive test coverage with pytest
• Modern Tooling: Built with Poetry, Ruff, and pre-commit hooks

Installation

Using pip

pip install testrail-cli

Using pipx (recommended for CLI tools)

pipx install testrail-cli

Using Poetry

poetry add testrail-cli

From source

git clone https://github.com/mokson/testrail-cli.git
cd testrail-cli
poetry install

Quick Start

Interactive Configuration

testrail config init

This will prompt you for your TestRail URL, email, and API key, then create ~/.testrail-cli.yaml.

Environment Variables

export TESTRAIL_URL=https://your-org.testrail.io
export TESTRAIL_EMAIL=[e-mail]
export TESTRAIL_PASSWORD=your-api-key

testrail projects list

Configuration File

Create ~/.testrail-cli.yaml:

profiles:
  default:
    url: https://your-org.testrail.io
    email: [e-mail]
    password: your-api-key
    timeout: 30
    verify: true

  staging:
    url: https://staging.testrail.io
    email: [e-mail]
    password: staging-api-key

Use profiles with --profile flag:

testrail --profile staging projects list

Configuration Precedence: CLI flags > Environment variables > Config file

See examples/example-config.yaml for all configuration options.

Common Use Cases

Managing Projects and Suites

# List all projects
testrail projects list

# Create a new project
testrail projects add --name "My New Project" --announcement "Welcome!"

# List suites for a project
testrail suites list --project-id 1

# List sections within a suite
testrail sections list --project-id 1 --suite-id 5

Working with Test Cases

# List all test cases
testrail cases list --project-id 1 --suite-id 5

# Filter by priority and creation date
testrail cases list --project-id 1 --priority-id 1,2 --created-after 2024-01-01

# Add a new test case
testrail cases add \
  --section-id 10 \
  --title "Test user login with valid credentials" \
  --priority-id 2 \
  --estimate "5m" \
  --refs "JIRA-123"

# Update existing test case
testrail cases update 123 --title "Updated test title" --priority-id 1

# Delete test case (soft delete)
testrail cases delete 123 --soft 1 --yes

CSV Import: Bulk Test Case Creation

The CSV import feature is perfect for migrating test cases or bulk creation:

testrail cases import \
  --project-id 1 \
  --suite-id 5 \
  --csv test-cases.csv \
  --section-path "API/Authentication" \
  --create-missing-sections \
  --mapping field-mapping.yaml

Example CSV (test-cases.csv):

Title,Priority,Estimate,Steps,Expected Result,References
Login with valid credentials,High,2m,1. Enter username\n2. Enter password\n3. Click Login,User is logged in,JIRA-101
Login with invalid password,High,2m,1. Enter username\n2. Enter wrong password\n3. Click Login,Error message shown,JIRA-102

Example Mapping (field-mapping.yaml):

csv_to_testrail:
  Title: title
  Priority: priority_name
  Estimate: estimate
  Steps: custom_steps
  Expected Result: custom_expected
  References: refs

priority_mapping:
  High: 1
  Medium: 2
  Low: 3

See examples/example-cases.csv and examples/example-mapping.yaml for complete examples.

Test Runs and Results

# Create a new test run
testrail runs add \
  --project-id 1 \
  --suite-id 5 \
  --name "Sprint 10 Regression" \
  --include-all true \
  --assignedto-id 5

# Add a single test result
testrail results add \
  --test-id 1001 \
  --status-id 1 \
  --comment "Test passed successfully" \
  --elapsed "5m"

# Bulk add results from JSON file
testrail results add-bulk --run-id 50 --results-file results.json

# Close a test run
testrail runs close 50

Bulk Results Format (results.json):

[
  {
    "test_id": 1001,
    "status_id": 1,
    "comment": "Test passed",
    "elapsed": "2m"
  },
  {
    "test_id": 1002,
    "status_id": 5,
    "comment": "Test failed: timeout",
    "defects": "BUG-456",
    "elapsed": "5m"
  }
]

Test Plans and Milestones

# List milestones
testrail milestones list --project-id 1

# Create a milestone
testrail milestones add \
  --project-id 1 \
  --name "Release 2.0" \
  --description "Q4 2024 Release" \
  --due-on 2024-12-31

# List test plans
testrail plans list --project-id 1 --is-completed 0

# Close a test plan
testrail plans close 25

Output Formats and Filtering

# JSON output (default)
testrail projects list --output json

# Table output
testrail projects list --output table

# Table with specific fields only
testrail projects list --output table --fields id,name,is_completed

# Filter specific fields in JSON
testrail cases list --project-id 1 --suite-id 5 --fields id,title,priority_id

Raw API Access

For endpoints not yet covered by specific commands, use the raw command:

# GET request
testrail raw --endpoint get_projects --method GET

# POST with inline data
testrail raw \
  --endpoint add_case/123 \
  --method POST \
  --data title="New test case" \
  --data priority_id=2

# POST with JSON file
testrail raw \
  --endpoint add_run/1 \
  --method POST \
  --payload-file run.json

CI/CD Integration

GitHub Actions Example

name: TestRail Integration

on:
  workflow_run:
    workflows: ["Tests"]
    types: [completed]

jobs:
  upload-results:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install TestRail CLI
        run: pipx install testrail-cli

      - name: Upload test results
        env:
          TESTRAIL_URL: ${{ secrets.TESTRAIL_URL }}
          TESTRAIL_EMAIL: ${{ secrets.TESTRAIL_EMAIL }}
          TESTRAIL_PASSWORD: ${{ secrets.TESTRAIL_API_KEY }}
        run: |
          testrail results add-bulk --run-id ${{ secrets.RUN_ID }} --results-file results.json
          testrail runs close ${{ secrets.RUN_ID }}

Jenkins Pipeline Example

pipeline {
    agent any
    stages {
        stage('Upload Results') {
            steps {
                withCredentials([
                    string(credentialsId: 'testrail-url', variable: 'TESTRAIL_URL'),
                    string(credentialsId: 'testrail-email', variable: 'TESTRAIL_EMAIL'),
                    string(credentialsId: 'testrail-key', variable: 'TESTRAIL_PASSWORD')
                ]) {
                    sh '''
                        testrail results add-bulk --run-id ${RUN_ID} --results-file results.json
                        [ $? -eq 0 ] && testrail runs close ${RUN_ID}
                    '''
                }
            }
        }
    }
}

Shell Script Example

#!/bin/bash
set -e

RUN_ID=$1
RESULTS_FILE="test-results.json"

# Upload results to TestRail
echo "Uploading test results to TestRail run ${RUN_ID}..."
testrail results add-bulk --run-id "${RUN_ID}" --results-file "${RESULTS_FILE}"

# Close the run if upload succeeded
if [ $? -eq 0 ]; then
    echo "Closing test run ${RUN_ID}..."
    testrail runs close "${RUN_ID}"
    echo "Test run closed successfully"
else
    echo "Failed to upload results"
    exit 1
fi

Available Commands

Core Resources

• projects - Manage projects
• suites - Manage test suites
• sections - Manage test sections
• cases - Manage test cases (includes CSV import)
• runs - Manage test runs
• plans - Manage test plans
• tests - View individual tests
• results - Add and manage test results
• milestones - Manage milestones
• attachments - Manage attachments

Administrative

• users - List users
• statuses - List test statuses
• priorities - List priorities
• case-types - List case types
• case-fields - List custom case fields
• result-fields - List custom result fields

Utilities

• config - Initialize and manage configuration
• raw - Direct API endpoint access

Use testrail <command> --help for detailed options on any command.

Getting Your TestRail API Key

1. Log in to your TestRail instance
2. Click on your profile icon (top right)
3. Select "My Settings"
4. Go to the "API Keys" section
5. Click "Add Key"
6. Copy the generated API key (treat it like a password)

Documentation

• Installation Guide
• Configuration Guide
• Command Reference
• CSV Import Guide
• Development Guide
• Contributing Guidelines

Development

Setup

# Clone the repository
git clone https://github.com/mokson/testrail-cli.git
cd testrail-cli

# Install dependencies
poetry install

# Set up pre-commit hooks
make pre-commit

Running Tests

# Run all tests
make test

# Run with coverage
poetry run pytest --cov

# Run specific test file
poetry run pytest tests/unit/test_config.py

Code Quality

# Format code
make format

# Run linter
make lint

# Type check
make type-check

# Run all checks
make lint && make type-check && make test

See CONTRIBUTING.md for detailed development guidelines.

Contributing

We welcome contributions! Please see our Contributing Guidelines and Code of Conduct.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: docs/

Changelog

See CHANGELOG.md for a list of changes in each release.

Acknowledgments

• Built with Typer for CLI framework
• Uses Rich for beautiful terminal output
• API wrapper provided by testrail-api