The TestRail CLI is commonly used in:

• CI/CD pipelines
• Automated test result uploads
• Containerised and headless environments

In these scenarios, logs are often the only way to understand what happened during execution.

TR CLI includes a built-in logging and observability system designed specifically for command-line tools. It provides structured logging with automatic credentials sanitisation, making it easy to integrate with CI/CD pipelines and observability tools.

Detect and Track Errors

Logging helps capture issues such as:

• TestRail API failures
• Authentication or permission errors
• Invalid parameters or configuration mistakes
• Network or connectivity problems

This reduces the risk of silent failures in CI pipelines.

Troubleshoot Faster

Logs provide visibility into:

• Which command was executed
• Input parameters and configuration
• Execution flow and API responses
• Timing and performance details

This makes it easier to diagnose issues without reproducing them locally.

Support Audit and Compliance Needs

Logging enables you to:

• Track when TR CLI was executed
• Identify which project, run, or results were affected
• Understand what data was uploaded and by whom

This is especially useful in regulated or enterprise environments.

Gain Operational Insights

Structured logs can be used to measure:

• Execution duration
• Number of test cases or results processed
• Retry attempts and partial failures

These insights can be turned into dashboards or alerts using log-based monitoring tools.

Benefits

Reduced Troubleshooting Time

• Faster root-cause analysis in CI failures
• Clear, actionable error messages

Lower Risk in Production Pipelines

• Early detection of failed uploads
• Fewer silent or partial failures

Improved Operational Efficiency

• Less time spent on support and triage
• Better feedback loops for developers and QA teams

Key Features

• Structured Logging: JSON (NDJSON) and text formats for machine-parseable logs
• Credential Sanitization: Automatic masking of sensitive fields (passwords, API keys, tokens)
• File Rotation: Automatic log rotation based on file size with configurable backup counts
• Flexible Configuration: CLI flags, environment variables, YAML config files

Automatic Logging

TRCLI now automatically logs all operations using structured logging. Simply configure using environment variables:

# Enable JSON logs on stderr (default)
export TRCLI_LOG_LEVEL=INFO
export TRCLI_LOG_FORMAT=json

# Run any TRCLI command - logging happens automatically
trcli parse_junit --file report.xml --project "My Project" \
  --host https://example.testrail.io --username user --password pass

Direct API Usage (Advanced)

For custom integrations or scripts:

from trcli.cli import Environment
from trcli.logging.config import LoggingConfig

# Initialize logging (reads from env vars)
LoggingConfig.setup_logging()

# Use TRCLI Environment with automatic logging
env = Environment("my_command")
env.logger.info("Operation completed", items=100, duration=1.5)

# Or get a standalone logger
from trcli.logging import get_logger
logger = get_logger("trcli.custom")
logger.info("Custom operation", status="success")

JSON Output:

{"timestamp":"2024-01-20T10:15:30Z","level":"INFO","logger":"trcli.module","message":"Operation completed","items":100,"duration":1.5}

Configuration

Configure logging using environment variables:

# Set log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
export TRCLI_LOG_LEVEL=INFO

# Set output format (json or text)
export TRCLI_LOG_FORMAT=json

# Set output destination (stderr, stdout, or file)
export TRCLI_LOG_OUTPUT=stderr

# For file output, specify path and rotation settings
export TRCLI_LOG_FILE=/var/log/trcli/app.log
export TRCLI_LOG_MAX_BYTES=10485760  # 10MB
export TRCLI_LOG_BACKUP_COUNT=5

# Run TRCLI
trcli parse_junit --file report.xml

Or use a YAML configuration file:

# trcli_config.yml
logging:
  level: INFO
  format: json
  output: file
  file_path: /var/log/trcli/app.log
  max_bytes: 10485760
  backup_count: 5

Then reference it:

trcli -c trcli_config.yml parse_junit --file report.xml

Automatic Credential Sanitization

Credentials are automatically sanitized in logs to prevent security leaks:

logger.info("Auth configured",
    password="secret123",
    api_key="sk_live_abc123",
    token="bearer_xyz"
)

# Output automatically sanitizes:
# {"password":"se***23","api_key":"sk***23","token":"be***yz"}

Protected Fields:

• password, passwd, pwd
• api_key, apikey, key
• token, auth_token, access_token
• secret, credential

CI/CD Integration

Output JSON logs for easy parsing in CI/CD pipelines:

# Output JSON logs for parsing
export TRCLI_LOG_FORMAT=json
trcli parse_junit --file report.xml 2>&1 | tee logs.json

# Parse logs with jq
cat logs.json | jq 'select(.level == "ERROR")'
cat logs.json | jq 'select(.duration_seconds > 30)'
cat logs.json | jq '.run_id' | sort | uniq

File Logging with Rotation

For long-running processes, enable file logging with automatic rotation:

# Via environment variables
export TRCLI_LOG_FILE=/var/log/trcli/app.log
export TRCLI_LOG_MAX_BYTES=10485760  # 10MB
export TRCLI_LOG_BACKUP_COUNT=5

trcli parse_junit --file report.xml

Benefits:

• Long-running processes don't fill disk
• Automatic cleanup of old logs
• Easy log management

Environment Variables Reference

Next Steps

• Enable JSON logging in your CI/CD pipelines
• Forward logs to your existing monitoring or logging platform
• Share feedback or improvements via GitHub
• Contact TestRail Support if you have questions or encounter issues

Logging and observability help ensure your TestRail automation remains reliable, transparent, and production-ready.

What next?

Now that you have centralized your test results on TestRail, not only can you check the results of your automated test runs, along with the error messages for failed tests, but you can also aggregate both your manual and automated testing efforts on reports that show you the full test coverage surrounding your app and even track test automation progress. You can also report a bug directly from the automated test result to an issue tracker of your preference as you would do for your manual test results!

You can look into the TestRail’s Reports and Test Metrics video to learn about how you can leverage TestRail’s reporting capabilities.