شروع کار با TestRail CLI

TestRail CLI یک ابزار command-line متن‌باز است که آپلود نتایج اتوماسیون تست را در projectهای TestRail شما آسان می‌کند؛ بدون اینکه لازم باشد کدی بنویسید یا با API سروکار داشته باشید.

از آن برای خودکارسازی workflow گزارش‌گیری خود استفاده کنید؛ با آپلود نتایج از frameworkهای محبوبی مثل JUnit ، TestNG ، NUnit ، Cypress ، Playwright و موارد دیگر.

اکنون می‌توانید نتایج performance testing ، از جمله نتایج JMeter را هم با همان workflowهای مبتنی بر CLI یکپارچه کنید. این روش برای load testing، بررسی latency یا stress test در CI/CD pipeline شما مناسب است.

CLI از هر دو رویکرد code-first و specification-first در تست پشتیبانی می‌کند:

• در setup code-first ، تست‌ها را در کد تعریف و اجرا می‌کنید و سپس نتایج را با TestRail sync می‌کنید.
• در setup specification-first ، پیش از اجرا test caseها را در TestRail map می‌کنید و نتایج را به test IDهای موجود لینک می‌کنید.

TestRail CLI به‌عنوان یک project متن‌باز، با بازخورد جامعه کاربری بهتر می‌شود. می‌توانید مشکلات را گزارش کنید، پیشنهادهای بهبود بدهید و حتی featureهای جدید را از طریق GitHub پیشنهاد کنید. مشارکت‌های شما به شکل‌گیری آینده این ابزار کمک می‌کند.

چرا از TestRail CLI استفاده کنیم؟

گزارش‌دهی اتوماسیون تست را ساده‌تر کنید:

• نیازی نیست درگیر یادگیری API شوید – فقط مسیر فایل گزارش XML تست را بدهید و آن را آپلود کنید.
• وابسته به زبان برنامه‌نویسی نیست – با هر فریم‌ورکی که خروجی XML با قالب JUnit-style تولید کند، کار می‌کند.
• مناسب برای CI/CD – به‌راحتی می‌توانید آن را برای استفاده در pipelineها اسکریپت کنید.
• متن‌باز – روی GitHub میزبانی می‌شود؛ می‌توانید در آن مشارکت کنید یا آن را سفارشی کنید.

فریم‌ورک‌های پشتیبانی‌شده

می‌توانید از CLI تقریباً با هر فریم‌ورک اتوماسیون تستی استفاده کنید که بتواند گزارش‌هایی با قالب JUnit-style خروجی بگیرد، از جمله:

• Cypress.io
• Playwright
• JUnit
• TestNG
• NUnit
• Pytest
• Robot Framework
• JMeter

✅ اگر فریم‌ورک شما از خروجی XML با قالب JUnit-style پشتیبانی می‌کند، با TestRail CLI کار می‌کند.

با پردازش و آپلود مستقیم نتایج تست با قالب JUnit-style در TestRail از طریق command line، یا با اجرای CLI به‌عنوان بخشی از یک build pipeline خودکار در Jenkins، GitLab CI، GitHub Actions یا ابزارهای CI دیگر، می‌توانید به‌جای درگیر شدن با API callها و جزئیات فنی مربوط به آپلود نتایج تست، روی نوشتن کد تست تمرکز کنید.

برای دیدن نمونه projectهای اتوماسیون تست با فریم‌ورک‌های مختلف، می‌توانید به project یکپارچه‌سازی فریم‌ورک‌های اتوماسیون در GitHub هم مراجعه کنید.

مثال: آپلود نتایج تست در TestRail

این یک workflow ساده برای آپلود نتایج یک test run در Playwright یا JUnit به TestRail است.

trcli --url <TESTRAIL_URL> \
      --project <PROJECT_NAME> \
      --suite <SUITE_NAME> \
      --milestone <MILESTONE_NAME> \
      --run-name "Automated Test Run - $(date +%Y-%m-%d)" \
      --results <PATH_TO_XML_REPORT>

<TESTRAIL_URL> – URL مربوط به TestRail instance شما

<PROJECT_NAME> – نام project شما در TestRail

<SUITE_NAME> – test suite مقصد برای آپلود نتایج

<MILESTONE_NAME> – milestone اختیاری در TestRail

<PATH_TO_XML_REPORT> – مسیر فایل نتایج XML با قالب JUnit-style

پیش‌نیازها

TestRail CLI برای آپلود نتایج تست‌ها، محدود به زبان برنامه‌نویسی خاصی نیست؛ اما خود ابزار با Python توسعه یافته و از طریق Python Package Index عمومی (PyPI) قابل نصب است. 

قبل از نصب CLI، مطمئن شوید که:

• Python ۳.۱۰.۴ یا نسخه‌های جدیدتر روی سیستم شما نصب شده باشد.
• pip (package manager پایتون) از طریق ترمینال در دسترس باشد.
• یک حساب TestRail با دسترسی administrator یا API داشته باشید.

فعال‌سازی TestRail API

• به مسیر زیر بروید: Administration > Site Settings > API
• گزینه زیر را تیک بزنید: Enable API

نصب Python ۳.۱۰+

Python ۳.۱۰.۴ را از سایت زیر دانلود کنید: python.org

در زمان نصب، مطمئن شوید که pip همراه نصب شود.

python --version
pip --version

اگر این دستورها شماره نسخه را نشان دادند، می‌توانید نصب TestRail CLI را شروع کنید. در غیر این صورت، دستورالعمل‌های راه‌اندازی زیر را دنبال کنید: 

در Windows

1. Python را از وب‌سایت رسمی دانلود کنید.
2. در زمان نصب:
   • گزینه «Add Python to PATH» را انتخاب کنید.
   • مطمئن شوید pip انتخاب شده باشد.
3. ترمینال را دوباره باز کنید و دستور زیر را اجرا کنید:

python --version
pip --version

در macOS

۱- Homebrew را نصب کنید (اگر قبلاً نصب نشده است):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

۲- با استفاده از Homebrew، Python را نصب کنید:

brew install python@3.10

۳- نصب را تأیید کنید:

python3 --version
pip3 --version

sudo apt update
sudo apt install python3.10 python3-pip

python3 --version
pip3 --version

$ pip install trcli

trcli

TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Supported and loaded modules:
    - parse_junit: JUnit XML Files (& Similar)
    - parse_robot: Robot Framework XML Files
    - parse_openapi: OpenAPI YML Files
    - add_run: Create a new test run