مرجع عمومی #
TRCLI یک ابزار command-line برای خودکارسازی کارها در TestRail است؛ مثل ساختن test run، آپلود نتایج، یا ایجاد test case از گزارشهای خارجی.
در این موارد از آن استفاده کنید:
- میخواهید workflowهای QA را از طریق اسکریپتهای محلی یا pipelineهای CI/CD خودکار کنید
- میخواهید بدون نیاز به استفاده از TestRail UI، کارها را سریعتر و بهصورت تکرارپذیر انجام دهید
سادهترین دستور برای نمایش راهنمای گزینهها و commandهای موجود:
trcli --helpکه فهرستی شبیه نمونه زیر را برمیگرداند:
TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli [OPTIONS] COMMAND [ARGS]...
TestRail CLI
Options:
-c, --config Optional path definition for testrail-credentials
file or CF file.
-h, --host Hostname of instance.
--project Name of project the Test Run should be created under.
--project-id Project id. Will be only used in case project name
will be duplicated in TestRail [x>=1]
-u, --username Username.
-p, --password Password.
-k, --key API key used for authenticating with TestRail. This
must be used in conjunction with --username. If
provided, --password is not required.
-v, --verbose Output all API calls and their results.
--verify Verify the data was added correctly.
--insecure Allow insecure requests.
-b, --batch-size Configurable batch size. [default: (50); x>=2]
-t, --timeout Batch timeout duration. [default: (60); x>=0]
-y, --yes answer 'yes' to all prompts around auto-creation
-n, --no answer 'no' to all prompts around auto-creation
-s, --silent Silence stdout
--proxy Proxy address and port (e.g.,
http://proxy.example.com:8080).
--proxy-user Proxy username and password in the format
'username:password'.
--noproxy Comma-separated list of hostnames to bypass the proxy
(e.g., localhost,127.0.0.1).
--parallel-pagination Enable parallel pagination for faster case fetching
(experimental).
--help Show this message and exit.
Commands:
add_run Add a new test run in TestRail
export_gherkin Export BDD test case from TestRail as .feature file
import_gherkin Upload or update Gherkin .feature file in TestRail
labels Manage labels in TestRail
parse_cucumber Parse Cucumber JSON results and upload to TestRail
parse_junit Parse JUnit report and upload results to TestRail
parse_openapi Parse OpenAPI spec and create cases in TestRail
parse_robot Parse Robot Framework report and upload results to...
references Manage references in TestRail
update Update TRCLI to the latest version from PyPI.
گزینههای سراسری #
این گزینهها را میتوانید همراه با هر command در TRCLI استفاده کنید.
| گزینه | توضیح |
|---|---|
-c, --config |
مسیر فایل config (برای مثال، testrail-credentials.json). برای نگهداری اطلاعات ورود مفید است تا این اطلاعات در command line نمایش داده نشوند. |
-h, --host |
URL نمونه TestRail شما ، مانند https://yourcompany.testrail.io. الزامی است. |
--project |
نام project در TestRail. برای ساختن یا دریافت test runها زیر project مشخصشده استفاده میشود. |
--project-id |
ID project ، فقط زمانی استفاده میشود که چند project نام یکسان داشته باشند. |
-u, --username |
TestRail username ورود (معمولاً ایمیل). الزامی است، مگر اینکه از فایل config استفاده کنید. |
-p, --password |
TestRail password. اگر از API key استفاده شود، اختیاری است. |
-k, --key |
API key برای احراز هویت امن. همراه با --username. |
-v, --verbose |
نمایش logهای دقیق ، شامل API callها و responseها. برای debugging مفید است. |
--verify |
بررسی میکند که دادهها، مثل test resultهای آپلودشده، درست اضافه شده باشند. |
--insecure |
اجازه دادن به درخواستهای HTTPS ناامن (نادیده گرفتن SSL validation). با احتیاط استفاده کنید. |
-b, --batch-size |
تعداد آیتمهایی که در هر batch از API پردازش میشوند. پیشفرض: ۵۰. برای آپلودهای بزرگتر، این مقدار را افزایش دهید. |
-t, --timeout |
زمان انتظار (بر حسب ثانیه) بین batchهای API. پیشفرض: ۳۰. برای هماهنگی با API rate limitها تنظیم کنید. |
-y, --yes |
بهطور خودکار به promptها «yes» پاسخ دهید (مثلاً test caseها را خودکار ایجاد کنید). در CI/CD مفید است. |
-n, --no |
بهطور خودکار به promptها «no» پاسخ دهید. از ایجاد خودکار test caseهای ناموجود جلوگیری میکند. |
-s, --silent |
کل خروجی استاندارد (stdout) را پنهان کنید. |
--proxy |
از یک proxy server (مثلاً http://proxy.company.com:8080) استفاده کنید. |
--proxy-user |
مشخصات ورود proxy با قالب username:password . |
--noproxy |
فهرست جداشده با کاما از hostهایی که باید proxy را bypass کنند (مثلاً localhost,127.0.0.1). |
--help |
راهنمای command را نمایش میدهد. |
خلاصه commandها #
| Command | کاربرد |
|---|---|
add_run |
یک test run جدید در TestRail ایجاد میکند. |
labels |
مدیریت labelها در TestRail |
export_gherkin |
Export کردن test caseهای BDD از TestRail بهصورت فایل .feature |
import_gherkin |
آپلود کردن یا بهروزرسانی محتوای Gherkin در فایل .feature در TestRail |
parse_cucumber |
یک گزارش JSON در Cucumber و نتایج را در TestRail آپلود میکند. |
parse_junit |
یک گزارش JUnit را پردازش میکند و نتایج را در TestRail آپلود میکند. |
parse_openapi |
یک مشخصات OpenAPI را پردازش میکند و test case ایجاد میکند. |
parse_robot |
یک گزارش تست Robot Framework را پردازش میکند و نتایج را آپلود میکند. |
references |
مدیریت referenceهای test caseها در TestRail |
update |
TRCLI را از PyPI به آخرین نسخه بهروزرسانی کنید. |
ایجاد یک test run جدید در TestRail #
از دستور trcli add_run زمانی استفاده کنید که میخواهید در TestRail یک test run ایجاد کنید؛ چه برای اجرای دستی، چه قبل از آپلود نتایج خودکار. همچنین میتوانید از آن برای تعریف زمانبندی، اختصاص دادن testerها، یا برچسبگذاری run با referenceها یا requirementها استفاده کنید.
این مورد برای این کاربردها مفید است:
- مدیران QA یا testerهایی که کارها را از قبل برنامهریزی میکنند
- مهندسان Automation که قبل از آپلود نتایج به run ID نیاز دارند
- تیمهایی که test runها را با requirementها، milestoneها یا تاریخهای sprint هماهنگ میکنند
مثال #
trcli add_run \
--title "Release 2.3 Regression" \
--suite-id 7 \
--milestone-id 14 \
--run-start-date "08/01/2025" \
--run-end-date "08/05/2025" \
--run-include-all \
--run-refs REQ-101,REQ-202 \
--run-assigned-to-id 3این دستور یک test run با عنوان مشخص، زیر suite ID ۷ ایجاد میکند؛ آن را به یک milestone وصل میکند، یک بازه زمانی برنامهریزیشده دارد، و همه test caseها را شامل میشود. این run به یک tester مشخص اختصاص داده میشود و دو requirement را بهعنوان reference اضافه میکند.
گزینههای موجود #
TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli add_run [OPTIONS]
Add a new test run in TestRail
Options:
--title Title of Test Run to be created or updated in
TestRail.
--run-id ID of existing test run to update. If not
provided, a new run will be created. [x>=1]
--suite-id Suite ID to submit results to. [x>=1]
--run-description Summary text to be added to the test run.
--milestone-id Milestone ID to which the Test Run should be
associated to. [x>=1]
--run-start-date The expected or scheduled start date of this
test run in MM/DD/YYYY format
--run-end-date The expected or scheduled end date of this test
run in MM/DD/YYYY format
--run-assigned-to-id The ID of the user the test run should be
assigned to. [x>=1]
--clear-run-assigned-to-id Clear the assignee of the test run (only valid
when updating with --run-id).
--run-include-all Use this option to include all test cases in
this test run.
--auto-close-run Use this option to automatically close the
created run.
--run-case-ids Comma separated list of test case IDs to include
in the test run (i.e.: 1,2,3,4).
--run-refs A comma-separated list of
references/requirements (up to 250 characters)
--run-refs-action Action to perform on references: 'add'
(default), 'update' (replace all), or 'delete'
(remove all or specific)
-f, --file Write run data to file.
--help Show this message and exit.
| گزینه | توضیح |
|---|---|
--title |
نام test run ، که در UI TestRail نمایش داده میشود؛ مثلاً «Sprint ۳۴ Regression». |
--run-id |
ID مربوط به test run موجودی که باید بهروزرسانی شود ؛ اگر مشخص نشود، یک run جدید ایجاد میشود. |
--suite-id |
مقدار test suite ID که run باید به آن مرتبط شود. اگر project شما از چند suite استفاده میکند، ضروری است. |
--run-description |
یک summary یا note برای run. برای شفاف کردن scope یا هدفها مفید است. |
--milestone-id |
این run را به یک milestone ID مشخص لینک کنید؛ مثلاً یک release یا sprint. |
--run-start-date |
مورد انتظار یا برنامهریزیشده تاریخ شروع ، با فرمت MM/DD/YYYY . |
--run-end-date |
تاریخ پایان مورد انتظار یا برنامهریزیشده برای این test run. |
--run-assigned-to-id |
این test run را به یک کاربر مشخص بر اساس ID اختصاص دهید (یعنی tester اصلی و مسئول). |
--clear-run-assigned-to-id |
کاربر تخصیصدادهشده به این test run را پاک کنید. توجه: فقط هنگام بهروزرسانی با –run-id معتبر است (فقط برای TR نسخه ۱۰.۲ و بالاتر). |
--run-include-all |
همهٔ test caseهای این suite را در این test run وارد کنید. نمیتوان آن را همراه با --run-case-ids استفاده کرد. |
--auto-close-run |
بهصورت خودکار test run ایجادشده را میبندد. استفاده از آن ساده است؛ کافی است این دستور را به انتهای script اضافه کنید. |
--run-case-ids |
فهرستی جداشده با کاما از IDهای test caseهای مشخص برای وارد کردن (مثلاً 101,102,103). |
--run-refs |
فهرست جداشده با کاما از referenceهای خارجی یا IDهای requirement (مثلاً REQ-101,REQ-202). |
-f, --file |
دادههای تولیدشدهٔ test run را در یک فایل محلی بنویسید، بهجای اینکه آن را ارسال کنید. برای preview یا audit مفید است. |
--help |
اطلاعات راهنمای این دستور را نمایش دهید. |
نکتهها #
- اگر میخواهید test run را به test caseهای مشخص محدود کنید ، از
--run-case-idsاستفاده کنید. - برای کارهای زمانبندیشده، مدیران QA میتوانند تاریخ شروع/پایان را برای شفافیت بیشتر تعیین کنند.
- اگر در حال خودکارسازی آپلود testها هستید ، میتوانید test run را همینجا ایجاد کنید و بعداً از
parse_junitبههمراه--run-idاستفاده کنید.
افزودن label به test caseها #
دستور labels به شما امکان میدهد labelها را در TestRail ایجاد، بهروزرسانی، حذف و مدیریت کنید. labelها برای سازماندهی test caseها، گروهبندی testهای مرتبط و فیلتر کردن آسانتر هنگام report گرفتن کاربرد دارند.
این command از TestRail CLI v1.12.0 به بعد در دسترس است.
مثال #
## assign a label to a case
trcli labels cases add --project-id <PROJECT_ID> --case-id <CASE_ID> --label "Regression"
## delete a lable from a case
trcli labels delete --project-id <PROJECT_ID> --id <LABEL_ID>
## gets details of a specific label
trcli labels get --project-id <PROJECT_ID> --id <LABEL_ID>
## list all the labels from a specific project
trcli labels list --project-id <PROJECT_ID>
## update an existing label
trcli labels update --project-id <PROJECT_ID> --id <LABEL_ID> --name "Updated Label Name"گزینههای موجود #
TestRail CLI v1.12.0
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli labels [OPTIONS] COMMAND [ARGS]...
Manage labels in TestRail
Options:
--help Show this message and exit.
Commands:
add Add a new label in TestRail
cases Manage labels for test cases
delete Delete labels from TestRail
get Get a specific label by ID
list List all labels in the project
update Update an existing label in TestRail
| گزینه | توضیح |
|---|---|
add |
یک label جدید در TestRail اضافه میکند. |
cases |
labelهای test caseها را مدیریت میکند (assign یا unassign). |
delete |
labelها را از TestRail حذف میکند. |
get |
جزئیات یک label مشخص را بر اساس ID دریافت میکند. |
list |
همه labelهای یک project مشخص را فهرست میکند. |
update |
یک label موجود در TestRail را بهروزرسانی میکند. |
چه زمانی از labelها استفاده کنیم #
- سازماندهی – test caseها را بر اساس feature، module یا release cycle گروهبندی کنید.
- فیلتر کردن – گزارشها و test runها را بهسادگی بر اساس label فیلتر کنید.
- اتوماسیون – برای دستهبندی testها در CI/CD pipelineها، labelها را بهصورت خودکار assign کنید.
آپلود نتایج JUnit #
یک گزارش JUnit XML را parse میکند (که در automated testها رایج است) و نتایج را در TestRail آپلود میکند.
از parse_junit برای parse کردن یک گزارش JUnit XML و آپلود test results در TestRail استفاده کنید. این کار معمولاً در CI/CD pipelineها یا بعد از اجرای automated testها انجام میشود.
در این موارد از آن استفاده کنید:
- automated testها را اجرا کردهاید (مثلاً JUnit، TestNG یا Selenium)
- میخواهید نتایج مستقیماً در TestRail آپلود شوند
- میخواهید test caseهای جاافتاده را خودکار ایجاد کنید یا یک test run موجود را بهروزرسانی کنید
property test_id در یک JUnit <testcase> میتواند به یک یا چند TestRail case ID اشاره کند.
وقتی چند case ID (در قالب فهرستی جداشده با کاما) وارد شود، TestRail CLI برای هر case ارجاعشده یک result جداگانه در test run هدف ایجاد میکند.
مثال #
trcli parse_junit \
-f build/test-results/test/TEST-results.xml \
--project "Mobile App" \
--title "Regression Test - Aug 1" \
--suite-id 10 \
--milestone-id 22 \
--case-matcher "name" \
--update-existing-cases yes \
--test-run-ref "PROJ-123,PROJ-456"
--close-runاین دستور resultها را از یک فایل JUnit XML آپلود میکند، یک test run زیر suite مشخصشده میسازد، آن را به یک milestone وصل میکند، test caseها را بر اساس عنوان تطبیق میدهد و سپس run را میبندد.
گزینههای موجود #
TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_junit [OPTIONS]
Parse JUnit report and upload results to TestRail
Options:
-f, --file Filename and path.
--close-run Close the newly created run
--title Title of Test Run to be created or updated in
TestRail.
--case-matcher Mechanism to match cases between the report and
TestRail.
--suite-id Suite ID to submit results to. [x>=1]
--suite-name Suite name to submit results to.
--run-id Run ID for the results they are reporting
(otherwise the tool will attempt to create a new
run). [x>=1]
--plan-id Plan ID with which the Test Run will be
associated. [x>=1]
--config-ids Comma-separated configuration IDs to use along
with Test Plans (i.e.: 34,52).
--milestone-id Milestone ID to which the Test Run should be
associated to. [x>=1]
--section-id Section ID to create new sections with test cases
under (optional). [x>=1]
--run-description Summary text to be added to the test run.
--case-fields List of case fields and values for new test cases
creation. Usage: --case-fields type_id:1 --case-
fields priority_id:3
--result-fields List of result fields and values for test results
creation. Usage: --result-fields
custom_field_a:value1 --result-fields
custom_field_b:3
--allow-ms Allows using milliseconds for elapsed times.
--special-parser Optional special parser option for specialized
JUnit reports.
-a, --assign Comma-separated list of user emails to assign
failed test results to.
--test-run-ref Comma-separated list of reference IDs to append to
the test run (up to 250 characters total).
--json-output Output reference operation results in JSON format.
--update-existing-cases Update existing TestRail cases with values from
JUnit properties (default: no).
--update-strategy Strategy for combining incoming values with
existing case field values, whether to append or
replace (default: append).
--help Show this message and exit.
| گزینه | توضیحات |
|---|---|
-f, --file |
مسیر فایل گزارش JUnit XML. الزامی است. |
--close-run |
بهصورت خودکار test run را میبندد پس از آپلود شدن resultها. |
--title |
عنوان test run که باید ایجاد یا بهروزرسانی شود. این عنوان در رابط کاربری TestRail نمایش داده میشود. |
--case-matcher |
روش تطبیق test caseها بین گزارش JUnit و TestRail؛ برای مثال بر اساس عنوان، ID یا attributeهای سفارشی. |
--suite-id |
ID مربوط به suite که resultها باید در آن ثبت شوند. برای projectهای چند-suite لازم است. |
--suite-name |
جایگزین --suite-id. نام suite که باید به run مرتبط شود. |
--run-id |
ID یک test run موجود برای بهروزرسانی، بهجای ساختن run جدید. |
--plan-id |
test run را به یک Test Plan وصل کنید؛ اگر runها را زیر یک plan بزرگتر سازماندهی میکنید. |
--config-ids |
فهرست جداشده با کاما از configuration IDها برای مرتبط کردن با run؛ مثل سیستمعامل یا مرورگر. |
--milestone-id |
milestone ID که باید run به آن مرتبط شود؛ مثل «Sprint ۱۴» یا «Release ۲.۱». |
--section-id |
بخشی که test caseهای جدید در صورت نیاز، باید زیر آن ساخته شوند. |
--run-description |
یک توضیح یا یادداشت به test run اضافه کنید. برای ارائه context مفید است. |
--case-fields |
مقادیر custom field را برای هر test case جدید تنظیم کنید (برای مثال type و priority). روش استفاده: --case-fields priority_id:3
|
--result-fields |
مقادیر custom field را برای هر test result تنظیم کنید (برای مثال test environment و notes). روش استفاده: --result-fields custom_status:passed
|
--allow-ms |
گزارش میتواند از میلیثانیه در زمانهای سپریشده استفاده کند. |
--special-parser |
از منطق parsing سفارشی برای فرمتهای غیر استاندارد JUnit استفاده کنید. |
-a, --assign |
همه testهای ناموفق در یک test run بهصورت خودکار به کاربر مشخصشده اختصاص داده میشوند. |
--test-run-ref |
فهرستی از reference IDها که با کاما جدا شدهاند و به test run اضافه میشوند (در مجموع تا ۲۵۰ کاراکتر). روش استفاده: --test-run-ref "TCM-77,TCM-77,TCM-78,TCM-79"
|
--json-output |
نتایج عملیات reference را در قالب JSON خروجی میدهد. |
--update-existing-cases |
وقتی “yes” ، parse_junit بهروزرسانیهای پشتیبانیشدهی فیلدهای test case را روی test caseهای موجودِ منطبق اعمال میکند. پیشفرض: NO |
--update-strategy |
مشخص میکند مقادیر ورودی چطور با مقادیر موجودِ آن field ترکیب شوند. مقادیر:
پیشفرض: append |
--help |
راهنمای استفاده از دستور را نمایش میدهد و خارج میشود. |
نگاشت یک test result به چند TestRail case #
یک test case در JUnit را میتوان به چند TestRail case نگاشت؛ برای این کار از test_id property استفاده کنید.
<testcase classname="tests.LoginTests" name="test_login_flow">
<properties>
<property name="test_id" value="C101, C102, C103"/>
</properties>
</testcase>
وقتی نتایج توسط trcli parse_junit پردازش میشوند:
- CLI فهرست case IDهایی را که با کاما جدا شدهاند میخواند
- هر case یک result entry جداگانه دریافت میکند
- همه caseهای نگاشتشده همان result status را دریافت میکنند که از تست خودکار آمده است
با این کار، یک تست خودکار میتواند چند TestRail case را بهروزرسانی کند و در عین حال ردیابی نتیجه برای هر case جدا باقی بماند.
نکات #
- از
--run-idاستفاده کنید اگر قبلاً یک test run را با استفاده ازadd_runساختهاید. - از
--case-matcherبرای لینک کردن نتایج به test caseهای موجود و جلوگیری از ایجاد موارد تکراری استفاده کنید. - از ترکیب
--plan-idبا--config-idsبرای مدیریت test matrixها، مثل ترکیبهای platform/browser، استفاده کنید. -
--result-fieldsمیتواند metadataهایی مثل نسخه build یا defect linkها را ثبت کند. -
-a, --assignخروجیای شبیه به این برمیگرداند:Assigning failed results: 1/1, Done.
ایجاد test case از OpenAPI Spec #
از این دستور برای ایجاد خودکار test case در TestRail بر اساس مشخصات OpenAPI (که قبلاً Swagger نام داشت) استفاده کنید. این روش برای ساخت سریع test coverage برای REST APIها مناسب است.
در این موارد از آن استفاده کنید:
- وقتی یک API جدید راهاندازی میکنید و میخواهید ایجاد test caseها را سریع شروع کنید
- وقتی میخواهید برای endpointها (GET/POST و…) بر اساس یک spec file، test caseهای ساختاریافته داشته باشید
- وقتی میخواهید test coverage را با طراحی API خود هماهنگ کنید
مثال #
trcli parse_openapi \
-f specs/user-api.yaml \
--suite-id 5 \
--case-fields type_id:1 \
--case-fields priority_id:3این دستور فایل user-api.yaml را میخواند، test caseها را در suite ID 5 ایجاد میکند و مقدارهای type و priority را برای هر test case جدید تنظیم میکند.
گزینههای موجود #
TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_openapi [OPTIONS]
Parse OpenAPI spec and create cases in TestRail
Options:
-f, --file Filename and path.
--suite-id Suite ID to create the tests in (if project is multi-suite).
[x>=1]
--case-fields List of case fields and values for new test cases creation.
Usage: --case-fields type_id:1 --case-fields priority_id:3
--help Show this message and exit.
| گزینه | توضیحات |
|---|---|
-f, --file |
مسیر فایل OpenAPI با فرمت YAML یا JSON (مثلاً api-spec.yaml). الزامی است. |
--suite-id |
Suite ID جایی که test caseها باید در آن ایجاد شوند. برای projectهای multi-suite الزامی است. |
--case-fields |
یک یا چند مقدار custom field برای اعمال روی هر test case. از این قالب استفاده کنید: field_id:value. برای تنظیم چند فیلد، میتوانید این گزینه را تکرار کنید. |
--help |
روش استفاده از دستور را نشان میدهد و خارج میشود. |
نکات #
- از
--case-fieldsبرای برچسبگذاری test caseها با test type، وضعیت automation یا priority استفاده کنید. - اگر project شما فقط از یک suite استفاده میکند، میتوانید از
--suite-idصرفنظر کنید. - test caseهای ایجادشده از custom fieldهای TestRail و تنظیمات case template شما پیروی میکنند.
آپلود نتایج Robot Framework #
از این دستور برای آپلود نتایج از یک اجرای تستهای Robot Framework (معمولاً یک output.xml فایل) در TestRail.
در این موارد از آن استفاده کنید:
- از Robot Framework برای test automation استفاده میکنید
- میخواهید نتایج بهصورت خودکار در TestRail ثبت شوند
- میخواهید test caseها بهصورت خودکار ساخته شوند یا نتایج به test runها/planهای موجود لینک شوند
مثال #
trcli parse_robot \
-f output.xml \
--project "Hardware QA" \
--suite-name "Peripheral Tests" \
--title "Regression - Aug 1" \
--milestone-id 12 \
--close-run \
--case-matcher titleاین دستور نتایج تست را از output.xml آپلود میکند، یک test run در suite با نام «Peripheral Tests» میسازد، آن را به یک milestone لینک میکند، caseها را بر اساس عنوان تطبیق میدهد و در پایان run را میبندد.
گزینههای موجود #
TestRail CLI v1.1X.X
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli parse_robot [OPTIONS]
Parse Robot Framework report and upload results to TestRail
Options:
-f, --file Filename and path.
--close-run Close the newly created run
--title Title of Test Run to be created or updated in TestRail.
--case-matcher Mechanism to match cases between the report and
TestRail.
--suite-id Suite ID to submit results to. [x>=1]
--suite-name Suite name to submit results to.
--run-id Run ID for the results they are reporting (otherwise the
tool will attempt to create a new run). [x>=1]
--plan-id Plan ID with which the Test Run will be associated.
[x>=1]
--config-ids Comma-separated configuration IDs to use along with Test
Plans (i.e.: 34,52).
--milestone-id Milestone ID to which the Test Run should be associated
to. [x>=1]
--section-id Section ID to create new sections with test cases under
(optional). [x>=1]
--run-description Summary text to be added to the test run.
--case-fields List of case fields and values for new test cases
creation. Usage: --case-fields type_id:1 --case-fields
priority_id:3
--result-fields List of result fields and values for test results
creation. Usage: --result-fields custom_field_a:value1
--result-fields custom_field_b:3
--allow-ms Allows using milliseconds for elapsed times.
--help Show this message and exit.
| گزینه | توضیحات |
|---|---|
-f, --file |
مسیر فایل نتایج XML مربوط به Robot Framework (معمولاً output.xml). الزامی است. |
--close-run |
بهصورت خودکار test run را ببندد بعد از آپلود نتایج. |
--title |
عنوان سفارشی برای test run (در TestRail نمایش داده میشود). |
--case-matcher |
مشخص میکند چطور test caseها تطبیق داده شوند در TestRail (مثلاً بر اساس عنوان یا ID). |
--suite-id |
ID سوئیتی که نتایج باید به آن ارسال شوند. برای projectهای چندسوئیتی. |
--suite-name |
نام suite. جایگزینی برای --suite-id. |
--run-id |
ID یک test run موجود برای بهروزرسانی. اگر وارد نشود، یک run جدید ساخته میشود. |
--plan-id |
run را به یک Test Plan وصل کنید (اختیاری). |
--config-ids |
فهرست جداشده با کاما از IDهای configuration (مثلاً environmentهایی مثل Chrome/Linux). |
--milestone-id |
test run را به یک milestone ID وصل کنید؛ مثلا sprint یا release. |
--section-id |
test caseهای جدید را زیر یک section ID مشخص ایجاد کنید؛ این کار به ساختاردهی کمک میکند. |
--run-description |
یک summary یا note به test run اضافه کنید. |
--case-fields |
با ، مقادیر فیلدهای test caseهای جدید را تنظیم کنید ؛ مثل type یا priority (مثلا type_id:1). |
--result-fields |
با ، مقادیر فیلدهای test result را تنظیم کنید ؛ مثل custom status، duration یا notes. |
--allow-ms |
اجازه میدهد durationها بر حسب میلیثانیه گزارش شوند؛ برای زمانسنجی دقیق مفید است. |
--help |
راهنمای command را نمایش میدهد و خارج میشود. |
نکات #
- از
--case-matcherبرای جلوگیری از ایجاد test caseهای تکراری استفاده کنید. - از
--plan-idهمراه با--config-idsهنگام integration با Test Plans و Configurations استفاده کنید. - از
--run-idبرای بهروزرسانی یک run که قبلا باadd_runایجاد شده است، استفاده کنید.
مدیریت References #
با references میتوانید referenceهای requirement خارجی مرتبط با test caseهای TestRail را مستقیم از command line مدیریت کنید.
این قابلیت زمانی مفید است که لازم باشد شناسههای requirement، مثل ticketهای Jira یا specهای requirement، را در چند test case بهصورت bulk لینک یا بهروزرسانی کنید؛ بدون اینکه مجبور باشید هر test case را در TestRail UI باز کنید.
میتوانید از trcli references برای این کارها استفاده کنید:
- لینکهای Jira story (
REQ-123،STORY-456) را به test caseهای موجود اضافه کنید. - ارجاعهای قدیمی را بهصورت انبوه حذف کنید.
- وقتی مشخصات محصول تغییر میکند، تگهای requirement قدیمی را با تگهای جدید جایگزین کنید.
این قابلیت بهویژه برای تیمهایی مفید است که TestRail را با ابزارهای خارجی پیگیری requirement یکپارچه میکنند یا traceability را در چند project مربوط به QA حفظ میکنند.
پیشنیازها #
قبل از اجرای commandهای مربوط به reference:
- باید TestRail CLI را نصب و پیکربندی کرده باشید و API credentials معتبر داشته باشید.
- باید دسترسی ویرایش به project و test caseهای TestRail داشته باشید.
- باید Test Case IDها و مقادیر reference موردنظر برای مدیریت را بدانید.
نمای کلی commandها #
TestRail CLI v1.xx.x
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli references cases [OPTIONS] COMMAND [ARGS]...
Manage references for test cases
Options:
--help Show this message and exit.
Commands:
add Add references to test cases
delete Delete all or specific references from test cases
update Update references on test cases by replacing existing ones| Command | توضیحات |
|---|---|
add |
یک یا چند reference را به test caseهای مشخص اضافه کنید. |
delete |
referenceهای مشخص یا همه referenceها را از test caseها حذف کنید. |
update |
referenceهای موجود در test caseها را با referenceهای جدید جایگزین کنید. |
۱. افزودن reference به test caseها #
یک یا چند requirement reference را به test caseهای مشخصشده اضافه میکند.
trcli references cases add --case-ids <CASE_IDS> --refs <REFERENCES>سینتکس Mac (zsh/bash) و Windows (PowerShell) یکسان است.
مثال #
# Add requirement IDs REQ-101 and REQ-102 to test cases 5 and 6
trcli references cases add --case-ids 5,6 --refs REQ-101,REQ-102پارامترها #
TestRail CLI v1.xx.x1
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli references cases add [OPTIONS]
Add references to test cases
Options:
--case-ids Comma-separated list of test case IDs (e.g., 1,2,3).
[required]
--refs Comma-separated list of references to add (e.g., REQ-1,REQ-2).
[required]
--help Show this message and exit.| گزینه | الزامی | توضیحات |
|---|---|---|
--case-ids |
بله | فهرست Test Case IDها، جداشده با کاما (مثلاً، 1,2,3). |
--refs |
بله | فهرست referenceهایی که باید اضافه شوند، جداشده با کاما (مثلاً، REQ-1,REQ-2). |
۲. حذف reference از test caseها #
referenceهای مشخص را از test caseها حذف میکند، یا اگر referenceی مشخص نشده باشد، همه referenceها را حذف میکند.
Command #
trcli references cases delete --case-ids <CASE_IDS> [--refs <REFERENCES>] [--yes]مثال #
# Delete references REQ-101 and REQ-102 from test cases 5 and 6
trcli references cases delete --case-ids 5,6 --refs REQ-101,REQ-102
# Delete all references from test cases 5 and 6 (confirmation required)
trcli references cases delete --case-ids 5,6⚠️ هشدار: بدون --refs ، همه referenceهای test caseهای مشخصشده حذف میشوند.
از --yes برای رد کردن پیام تأیید در اسکریپتهای خودکار استفاده کنید.
پارامترها #
TestRail CLI v1.xx.x
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli references cases delete [OPTIONS]
Delete all or specific references from test cases
Options:
--case-ids Comma-separated list of test case IDs (e.g., 1,2,3).
[required]
--refs Comma-separated list of specific references to delete. If not
provided, all references will be deleted.
--yes Confirm the action without prompting.
--help Show this message and exit.| گزینه | الزامی | توضیح |
|---|---|---|
--case-ids |
بله | فهرست IDهای test case که با کاما جدا شدهاند (برای مثال، 1,2,3). |
--refs |
خیر | فهرست referenceهای مشخصی که باید حذف شوند، جداشده با کاما. اگر وارد نشود، همه referenceها حذف میشوند. |
--yes |
خیر | حذف را بهصورت خودکار تأیید میکند (برای اسکریپتهای CI/CD مفید است). |
۳. بهروزرسانی referenceها در test caseها #
توضیحات #
همه referenceهای موجود در test caseهای مشخصشده را با referenceهای جدیدی که وارد کردهاید جایگزین میکند.
trcli references cases update --case-ids <CASE_IDS> --refs <REFERENCES>
مثال #
# Replace all references on test cases 5 and 6 with REQ-200 and REQ-201
trcli references cases update --case-ids 5,6 --refs REQ-200,REQ-201
💡 نکته: وقتی IDهای requirement بازآرایی یا تغییر نام داده میشوند، از این دستور برای بهروزرسانی کنترلشده استفاده کنید.
پارامترها #
TestRail CLI v1.xx.x
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli references cases update [OPTIONS]
Update references on test cases by replacing existing ones
Options:
--case-ids Comma-separated list of test case IDs (e.g., 1,2,3).
[required]
--refs Comma-separated list of references to replace existing ones
(e.g., REQ-1,REQ-2). [required]
--help Show this message and exit.| گزینه | الزامی | توضیح |
|---|---|---|
--case-ids |
بله | فهرست IDهای test case که با کاما جدا شدهاند (برای مثال، 1,2,3). |
--refs |
بله | فهرست referenceهای جدید، جداشده با کاما، برای جایگزینی referenceهای موجود. |
🎓 مهارتهای تست خود را با TestRail Academyارتقا دهید!
دورههای رایگان و خودآموز را ببینید تا از TestRail بیشترین استفاده را ببرید.
👉 همین حالا یادگیری را شروع کنید
