فهرست مستندات

مرجع دستورات CLI

به‌روزرسانی ۱۷ تیر ۱۴۰۵ ۲۲ دقیقه مطالعه TestRail

فهرست مطالب

TestRail_CLI (Navy Logo).png

مرجع عمومی

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` → referenceها را فقط به test case اضافه می‌کند `replacee → replace the references of the test cases entirely` پیش‌فرض: 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 بیشترین استفاده را ببرید.

👉 همین حالا یادگیری را شروع کنید

مرجع عمومی

گزینه‌های سراسری

خلاصه commandها

ایجاد یک test run جدید در TestRail

مثال

گزینه‌های موجود

نکته‌ها

افزودن label به test caseها

مثال

گزینه‌های موجود

چه زمانی از labelها استفاده کنیم

آپلود نتایج JUnit

مثال

گزینه‌های موجود

نگاشت یک test result به چند TestRail case

نکات

ایجاد test case از OpenAPI Spec

مثال

گزینه‌های موجود

نکات

آپلود نتایج Robot Framework

مثال

گزینه‌های موجود

نکات

مدیریت References

پیش‌نیازها

نمای کلی commandها

۱. افزودن reference به test caseها

مثال

پارامترها

۲. حذف reference از test caseها

Command

مثال

پارامترها

۳. به‌روزرسانی referenceها در test caseها

توضیحات

مثال

پارامترها

از کجا کمک بگیرید

TestRail را همین حالا در محیط دمو ببینید.