نمونه‌های استفاده

TestRail CLI چندین قابلیت دارد تا هنگام مدیریت آپلود خودکار نتایج test و تکمیل این نتایج با داده‌های بیشتر، نیازهای مختلف شما را پوشش دهد.

تکمیل نتایج test با استفاده از CLI #

هنگام ارسال نتایج test، TestRail به شما امکان می‌دهد انواع مختلف داده را در فیلدهای مختلف اضافه کنید. برای مثال، می‌توانید یک screenshot را به‌عنوان attachment آپلود کنید، یک comment متنی به نتیجه اضافه کنید، یا از custom result fieldها برای ذخیره داده‌ها به‌شکلی ساختاریافته‌تر استفاده کنید. با TestRail CLI می‌توانید همه این کارها را به روش‌های مختلف انجام دهید. گزینه‌هایی را که می‌توانید با CLI استفاده کنید در ادامه ببینید:

• فیلدهای نتیجه
  • نام: برابر با یا دارای پیشوند --result-fields
  • مقدار: با استفاده از الگو field_name:field_value 

 برای نمونه، برای اضافه کردن یک مقدار یکسان به یک فیلد در همه نتایج، می‌توانید مقدار را مستقیماً در command line و با استفاده از --result-fields argument، یک یا چند بار وارد کنید (نمونه را در ادامه ببینید):

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --result-fields "version:1.2" \
>    --result-fields "custom_environment:qa02" \
>    -f "results.xml"

تکمیل نتایج test در projectهای automation #

اگر لازم است برای هر نتیجه مقدار متفاوتی اضافه کنید، می‌توانید این کار را با افزودن propertyها به گزارش JUnit زیر هر test case انجام دهید. با این روش، علاوه بر تکمیل نتایج با داده‌های فیلدها، می‌توانید comment و attachment هم اضافه کنید.

به یک sample project با Java و JUnit ۵ مراجعه کنید که پروژه TestRail JUnit Extensions را پیاده‌سازی می‌کند تا هنگام integration نتایج test در TestRail، commentهای نتیجه test و attributeهای قابل تنظیم را به‌صورت برنامه‌نویسی اضافه کند. 

• Attachmentها
  • نام: برابر با یا دارای پیشوند testrail_attachment
  • مقدار: مسیر فایلی که باید آپلود شود

@ExtendWith(TestRailTestReporterParameterResolver.class)
class SumTests {
    @Test
    @DisplayName("Add Two Numbers With Decimals")
    void AddTwoNumbersWithIntegers(TestRailTestReporter customReporter) {
        // Sets the "testrail_attachment" property on the report with a path to a file to be uploaded with the test result
        customReporter.setProperty("test", "sample_reports/testrail.jpg");
        assertEquals(3, 2+1, "2+1 should equal 3");
    }
}

• Commentها

  • نام: برابر با یا دارای پیشوند testrail_result_comment
  • مقدار: متنی که باید به فیلد comment اضافه شود

  @ExtendWith(TestRailTestReporterParameterResolver.class)
  class SumTests {
      @Test
      @DisplayName("Add Two Integers")
      void AddTwoNumbersWithIntegers(TestRailTestReporter customReporter) {
          // Sets the "testrail_attachment" property on the report with a path to a file to be uploaded with the test result
          customReporter.setProperty("testrail_result_comment", "positive case integer addition scenario");
          
  assertEquals(3, 2+1, "2+1 should equal 3");
      }
  }

نکته: برای اینکه Result Steps با موفقیت ارسال شوند، template مربوط به test case مقصد باید فیلد step_results را فعال داشته باشد. به‌طور پیش‌فرض، فقط template «Test Case (Steps)» این Results Field را دارد، اما templateهای دیگر را هم می‌توان سفارشی کرد تا «Test Case (Steps)» را شامل شوند. اطلاعات بیشتر درباره templateهای test case را می‌توانید اینجا بخوانید.

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="0.05" name="tests.LoginTests">
    <properties><property name="setting1" value="True"/></properties>
    <testcase classname="tests.LoginTests" name="test_case_2" time="650">
     <properties>
         <property name="testrail_attachment" value="path_to/logs.log"/>
         <property name="testrail_attachment" value="path_to/screenshot.jpg"/>
         <property name="testrail_result_field" value="version:1.2"/>
         <property name="testrail_result_field" value="custom_environment:qa02"/>
         <property name="testrail_result_comment" value="Finding 1"/>
         <property name="testrail_result_comment" value="Finding 2"/>
         <property name="testrail_result_step" value="passed: Insert login credentials"/>
         <property name="testrail_result_step" value="failed: Click submit"/>
         <property name="testrail_result_step" value="untested: User should be logged in"/>
     </properties>
    </testcase>
  </testsuite>
</testsuites>

تکمیل فرایند ایجاد test case #

اگر از رویکرد code-first همراه با ایجاد خودکار test case استفاده می‌کنید، می‌توانید test caseهای خود را هم با داده‌های مربوط به هر فیلد تکمیل کنید. هنگام ارسال نتایج test، TestRail به شما امکان می‌دهد انواع مختلف داده را در فیلدهای مختلف اضافه کنید. برای مثال، می‌توانید یک screenshot را به‌عنوان attachment آپلود کنید، یک comment متنی به نتیجه اضافه کنید، یا از custom result fieldها برای ذخیره داده‌ها به‌شکلی ساختاریافته‌تر استفاده کنید. با TestRail CLI می‌توانید همه این کارها را به روش‌های مختلف انجام دهید.

برای اضافه کردن یک مقدار یکسان به یک فیلد در همه test caseها، می‌توانید مقدار را مستقیماً در command line و با استفاده از --case-fields argument، یک یا چند بار وارد کنید.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --result-fields "version:1.2" \
>    --result-fields "custom_environment:qa02" \
>    -f "results.xml"

اگر لازم است برای هر test case مقدار متفاوتی اضافه کنید، می‌توانید این کار را با افزودن propertyها به گزارش JUnit زیر هر test case و با استفاده از قرارداد زیر انجام دهید:

• فیلدهای test case
  • نام: برابر با یا دارای پیشوند testrail_case_field
  • مقدار: با استفاده از الگو field_name:field_value

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="0.05" name="tests.LoginTests">
    <properties><property name="setting1" value="True"/></properties>
    <testcase classname="tests.LoginTests" name="test_case_2" time="650">
     <properties>
         <property name="testrail_case_field" value="refs:STORY-1"/>
         <property name="testrail_case_field" value="custom_preconds:My preconditions"/>
     </properties>
    </testcase>
  </testsuite>
</testsuites>

نگه داشتن test caseهای جدید در یک section #

اگر از رویکرد code-first همراه با ایجاد خودکار test case استفاده می‌کنید، شاید بخواهید این test caseها از سایر test caseهای موجود در repository جدا باشند. برای اینکه همه test caseهای جدیدتان در یک section قرار بگیرند، می‌توانید از --section-id argument استفاده کنید. با این کار، همه suiteهای خودکار و test caseهای شما زیر section مشخص‌شده ایجاد می‌شوند.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --section-id "213" \
>    -f "results.xml"

اضافه کردن test run زیر یک milestone #

Milestoneها راه خوبی برای سازمان‌دهی فعالیت‌های test هستند. می‌توانید از آن‌ها برای کنار هم گذاشتن test runها یا planهایی با هدف مشترک استفاده کنید. اگر می‌خواهید test runهای خودکار شما زیر یک milestone ایجاد شوند، می‌توانید --milestone-id argument را ارسال کنید تا TestRail CLI test run را زیر milestone مشخص‌شده ایجاد کند.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --milestone-id "57" \
>    -f "results.xml"

اکنون باید test run جدید را زیر milestone مشخص‌شده ببینید. این یکی از روش‌های نگهداری و پیگیری نتایج تست‌های خودکار در یک محل است.

افزودن test run زیر یک test plan #

Test planها همچنین test runهایی را که هدف مشترکی دارند تجمیع می‌کنند و علاوه بر آن به شما اجازه می‌دهند برخی تنظیمات اجرایی را مشخص کنید. برای مثال، می‌توانید یک مجموعه تست یکسان را با مرورگرهای مختلف اجرا کنید و این اطلاعات را در test plan خود ببینید. اگر می‌خواهید test runهای خودکار شما زیر یک test plan ایجاد شوند، می‌توانید --plan-id را به‌عنوان argument ارسال کنید تا TestRail CLI،‏ test run را زیر test plan مشخص‌شده ایجاد کند. همچنین، اگر بخواهید test run را به یک configuration مشخص مرتبط کنید، می‌توانید به‌صورت اختیاری --config-ids را با فهرستی از configuration IDها که با کاما از هم جدا شده‌اند، به‌عنوان argument ارسال کنید.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --plan-id "57" \
>    --config-ids "25,34" \
>    -f "results.xml"

اکنون باید test run جدید را زیر test plan مشخص‌شده ببینید. این هم روش دیگری برای نگهداری و پیگیری نتایج تست‌های خودکار در یک محل است.

به‌روزرسانی نتایج تست در یک test run موجود #

فرض کنید قبلاً TestRail CLI را اجرا کرده‌اید و نتایج تست‌های خودکار شما در TestRail ثبت شده‌اند، اما بعضی از تست‌ها failed شده‌اند و می‌خواهید آن‌ها را دوباره اجرا کنید و test run موجود را با نتایج جدید به‌روزرسانی کنید. برای این کار، کافی است --run-id را به‌عنوان argument ارسال کنید تا TestRail CLI،‏ test run دارای آن ID را به‌روزرسانی کند.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --run-id "32" \
>    -f "results.xml"

اکنون باید نتیجه تست جدید را در پنل جزئیات تست ببینید. این یکی از روش‌های پیگیری نتایج تست‌های خودکار زیر همان test run است.

به‌روزرسانی نتایج تست بر اساس وضعیت‌های سفارشی #

اکنون می‌توانید وضعیت‌های پیش‌فرض نتیجه تست، مثل Passed، Failed و Skipped را با نگاشت آن‌ها به custom status IDهای خودتان در TestRail override کنید؛ همه این کار فقط با یک به‌روزرسانی ساده در config.yaml انجام می‌شود.

چرا این موضوع مهم است:

• پشتیبانی از workflow منعطف: نتایج تست را با طبقه‌بندی وضعیت‌های اختصاصی تیم شما همسو می‌کند؛ برای مثال «Automation Passed» یا «Error in Execution».
• کاهش کار دستی: نیاز به به‌روزرسانی دستی statusها بعد از upload شدن نتایج را از بین می‌برد.
• یکپارچه‌سازی آسان‌تر با automation: رویکرد مبتنی بر config، اتصال به pipelineهای CI/CD و ابزارهای automation را ساده‌تر می‌کند.
• سازگاری با نسخه‌ها و workflowهای قبلی: با workflowهای موجود که از statusهای پیش‌فرض استفاده می‌کنند، بدون مشکل کار می‌کند.

نمونه mappingها:

• Passed → «Automation Passed» (ID: 7)
• Failed → «Automation Failed» (ID: 8)
• Skipped → «Step Skipped» (ID: 3)
• Error → «Error in Execution» (ID: 4)

این به‌روزرسانی برای تیم‌هایی که محیط‌های تست پیچیده یا خودکار را در TestRail مدیریت می‌کنند، کنترل و یکپارچگی بیشتری فراهم می‌کند.

روش پیاده‌سازی:

ابتدا باید custom result statusها را در instance خود ایجاد کنید و سپس ID هر status را به نتیجه‌ای که از اجرا برمی‌گردد، map کنید.

بعد از اینکه تعریف‌ها در TestRail تنظیم شدند، فقط باید --case_result_statuses را به‌عنوان argument همراه با ID هر نوع نتیجه ارسال کنید تا هنگام parse شدن اطلاعات، mapping انجام شود.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --case_result_statuses:
                  passed: 7     # e.g., Automation Passed
                  failure: 8    # e.g., Automation Failed
                  error: 4      # Optional: for exceptions
                  skipped: 3    # Optional: for skipped tests\
>    -f "results.xml"

#

به‌روزرسانی custom fieldها در test caseهای موجود #

فرض کنید قبلاً از روی نتایج JUnit خود در TestRail test case ایجاد کرده‌اید، اما حالا automation تست خود را با موارد زیر بهبود داده‌اید:

• Automation IDهای به‌روزرسانی‌شده بعد از refactoring
• Preconditionهای جدیدی که هنگام تست شناسایی شده‌اند
• تغییر نوع automation، برای مثال از manual به automated

می‌خواهید این custom fieldها را در test caseهای موجود به‌روزرسانی کنید، بدون اینکه مورد تکراری ساخته شود. برای این کار، باید فایل JUnit XML خود را با custom fieldهای به‌روزشده تغییر دهید و سپس TRCLI را با --update-existing-cases yes

$ trcli -y \
     -h "https://INSERT-INSTANCE-NAME.testrail.io" \
     --project "TRCLI Test" \
     --username "user@domain.com" \
     --password "passwordORapikey" \
     parse_junit \
     --title "Updated Authentication Tests" \
     --update-existing-cases yes \
     -f "results_updated.xml"

بستن test run #

اگر می‌خواهید test run تازه ایجادشده را بلافاصله close کنید، کافی است --close-run را به‌عنوان argument ارسال کنید تا TestRail CLI بعد از اضافه شدن همه نتایج، این کار را انجام دهد. این گزینه زمانی مفید است که نمی‌خواهید بعد از پایان run، امکان تغییر نتایج وجود داشته باشد.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --close-run \
>    -f "results.xml"

می‌توانید test run خود را در بخش Completed test runs پیدا کنید.

زمان سپری‌شده نتایج بر حسب میلی‌ثانیه #

برای نسخه‌های ۵.۵ و بالاتر TestRail ، می‌توانید زمان سپری‌شده نتایج test را بر حسب میلی‌ثانیه ارسال کنید؛ برای مثال ۰.۰۰۱ ثانیه. رفتار پیش‌فرض TestRail CLI این است که زمان را به ثانیه گرد کند تا با همه نسخه‌های TestRail سازگار باشد. اگر از نسخه‌ای استفاده می‌کنید که از میلی‌ثانیه پشتیبانی می‌کند و می‌خواهید زمان سپری‌شده در result با دقت میلی‌ثانیه نمایش داده شود، می‌توانید آرگومان --allow-ms را وارد کنید.

$ trcli -y \
>    -h "https://INSERT-INSTANCE-NAME.testrail.io" \
>    --project "TRCLI Test" \
>    --username "user@domain.com" \
>    --password "passwordORapikey" \
>    parse_junit \
>    --title "Automated Tests Run" \
>    --allow-ms \
>    -f "results.xml"

اکنون در نتایج test باید فیلد elapsed را با مقدار میلی‌ثانیه ببینید.

استفاده از config fileها برای ذخیره پیکربندی‌های جایگزین #

با استفاده از یک config file جایگزین، می‌توانید resultها را سریع و ساده به instanceها یا projectهای مختلف ارسال کنید، از credentials متفاوت استفاده کنید، یا پارامترهای ازپیش‌تنظیم‌شده دیگری را در commandهای خود به کار ببرید. فایل پیکربندی با فرمت YAML نوشته می‌شود و نام آن config.yml است و، مگر اینکه مسیر دیگری مشخص کرده باشید، در همان directory فایل اجرایی TRCLI ذخیره می‌شود. از environment variableها هم می‌توان استفاده کرد. اگر در command به یک config file ارجاع داده شود، همه پارامترهای داخل config file بر environment variableها اولویت دارند. هر پارامتری که مستقیما در command مشخص شود، بر config file اولویت خواهد داشت.

مثال زیر استفاده از یک config file جایگزین را نشان می‌دهد که credentials کاربر را ذخیره می‌کند:

host: https://INSERT-INSTANCE-NAME.testrail.io 
project: TRCLI Test
username: username@domain.com 
password: passwordORapikey
title: Automated Tests Run

$ trcli -y \
>    --config alternate_config.yaml \
>    parse_junit \
>    -f "results.xml"

ایجاد test run جدید #

وقتی لازم است قبل از استفاده از یکی از commandهای parse یک test run ایجاد شود، از add_run command استفاده کنید. برای مثال، اگر testها روی test nodeهای مستقل و موازی اجرا شوند، همه nodeها باید resultهای خود را در همان test run گزارش کنند. ابتدا از add_run command برای ایجاد یک run جدید استفاده کنید؛ سپس عنوان و ID آن run را به هر یک از test nodeها بدهید تا همه resultها در همان test run آپلود شوند.

$ trcli add_run --help
TestRail CLI v1.9.12
Copyright 2025 Gurock Software GmbH - www.gurock.com
Usage: trcli add_run [OPTIONS]

Options:
  -title               Title of Test Run to be created or updated in
                       TestRail.
  --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-assigned-to-id The ID of the user the test run should be assigned
                       to. [x>=1]
  --run-include-all    Use this option to include all test cases in this test run.
  --case-ids           Comma separated list of test case IDs to include in
                       the test run.
  --run-refs           A comma-separated list of references/requirements
  -f, --file           Write run title and id to file.
  --help               Show this message and exit.