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

TestRail CLI دارای چندین ویژگی برای پشتیبانی از متنوع ترین نیازها در مدیریت آپلود خودکار نتایج تست شما و غنی سازی این نتایج با داده های بیشتر است.

غنی سازی نتایج آزمون با استفاده از CLI #

هنگام ارسال نتایج آزمون، TestRail امکان افزودن انواع مختلف داده ها در فیلدهای مختلف را فراهم می کند. به عنوان مثال، ممکن است بخواهید یک اسکرین شات را به عنوان پیوست آپلود کنید، یک نظر متنی به نتیجه خود اضافه کنید یا از فیلدهای نتیجه سفارشی برای ذخیره داده ها به روشی ساختارمندتر استفاده کنید. با استفاده از TestRail CLI، می توانید همه این کارها را به روش های مختلف انجام دهید. گزینه های زیر را که می توانید با استفاده از CLI فراخوانی کنید، ببینید:

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

 به عنوان مثال، برای افزودن همان مقدار برای یک فیلد از همه نتایج، می توانید مقدار را مستقیماً در خط فرمان با استفاده از --result-fields استدلال یک یا چند بار (به زیر مراجعه کنید):

$ 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"

غنی سازی نتایج آزمون در پروژه های اتوماسیون #

اگر نیاز به اضافه کردن مقادیر مختلف برای هر نتیجه دارید، می‌توانید با افزودن ویژگی‌ها به گزارش JUnit در هر تست‌کیس نیز به آن دست پیدا کنید. با استفاده از این تکنیک، نه تنها می توانید نتایج خود را با داده های فیلدها غنی کنید، بلکه نظرات و پیوست ها را نیز اضافه کنید.

ارجاع به یک پروژه نمونه با استفاده از جاوا و JUnit ۵ که اجرا می کند پروژه افزونه های TestRail JUnit برای افزودن برنامه‌نویسی نظرات نتیجه آزمایش و ویژگی‌های قابل تنظیم هنگام ادغام نتایج تست در TestRail. 

• پیوست ها
  • نام: برابر یا پیشوند با 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");
    }
}

• نظرات

  • نام: برابر یا پیشوند با testrail_result_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");
      }
  }

توجه داشته باشید: برای ارسال موفقیت آمیز مراحل نتیجه، الگوی تست‌کیس مورد نظر باید دارای این باشد step_results میدان فعال به‌طور پیش‌فرض، فقط الگوی «تست‌کیس (مراحل)» شامل این فیلد نتایج می‌شود، اما سایر الگوها را می‌توان طوری سفارشی کرد که «تست‌کیس (مراحل)» را نیز شامل شود. اطلاعات بیشتر در مورد الگوهای 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>

غنی سازی ایجاد تست‌کیس #

اگر از رویکرد کد اول با ایجاد خودکار تست‌کیس استفاده می‌کنید، می‌توانید تست‌کیس‌ها خود را با داده‌های مربوط به هر زمینه غنی کنید. هنگام ارسال نتایج آزمون، TestRail امکان افزودن انواع مختلف داده ها در فیلدهای مختلف را فراهم می کند. به عنوان مثال، ممکن است بخواهید یک اسکرین شات را به عنوان پیوست آپلود کنید، یک نظر متنی به نتیجه خود اضافه کنید یا از فیلدهای نتیجه سفارشی برای ذخیره داده ها به روشی ساختارمندتر استفاده کنید. با استفاده از TestRail CLI، می توانید همه این کارها را به روش های مختلف انجام دهید.

برای افزودن همان مقدار برای یک فیلد از همه تست‌کیس‌ها، می‌توانید با استفاده از عبارت، مقدار را مستقیماً در خط فرمان ارسال کنید --case-fields استدلال یک یا چند بار

$ 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"

اگر نیاز به اضافه کردن مقادیر مختلف برای هر تست‌کیس دارید، می‌توانید با افزودن ویژگی‌ها به گزارش JUnit در هر تست‌کیس، با استفاده از قرارداد زیر، به آن دست پیدا کنید:

• فیلدهای تست‌کیس
  • نام: برابر یا پیشوند با 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>

نگهداری تست‌کیس‌ها جدید در یک بخش #

اگر از رویکرد کد اول با ایجاد خودکار تست‌کیس استفاده می‌کنید، ممکن است بخواهید این موارد از سایر تست‌کیس‌ها در مخزن تست‌کیس‌ها جدا شوند. برای نگه داشتن تمام تست‌کیس‌ها جدید خود در یک بخش، می توانید از آن استفاده کنید --section-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" \
>    --section-id "213" \
>    -f "results.xml"

افزودن یک آزمایش آزمایشی تحت یک نقطه عطف #

Milestones یک راه عالی برای سازماندهی تلاش های آزمایشی شما است. می‌توانید از آنها برای جمع‌آوری برنامه‌های آزمایشی یا برنامه‌هایی با هدف مشترک استفاده کنید. اگر می‌خواهید آزمایش‌های خودکار شما تحت یک نقطه عطف ایجاد شود، می‌توانید آن را قبول کنید --milestone-id آرگومان و TestRail CLI اجرای تست را تحت نقطه عطف مشخص شده ایجاد می کند.

$ 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"

اکنون باید اجرای تست جدید را در نقطه عطف مشخص شده مشاهده کنید. این یکی از راه‌های پیگیری نتایج آزمون خودکار خود در یک مکان است.

اضافه کردن یک اجرای تست تحت یک طرح آزمایشی #

برنامه‌های آزمایشی همچنین برنامه‌های آزمایشی را با یک هدف مشترک جمع‌آوری می‌کنند، و به علاوه این امکان را به شما می‌دهد که پیکربندی‌های اجرایی خاصی را مشخص کنید. به عنوان مثال، می‌توانید مجموعه آزمایش‌های مشابهی را با استفاده از مرورگرهای مختلف اجرا کنید و آن اطلاعات را در برنامه آزمایشی خود نشان دهید. اگر می‌خواهید اجرای تست خودکار شما تحت یک طرح آزمایشی ایجاد شود، می‌توانید آن را قبول کنید --plan-id آرگومان و TestRail CLI اجرای تست را تحت برنامه آزمایشی مشخص شده ایجاد می کند. اگرچه اختیاری است، علاوه بر آن، اگر می‌خواهید اجرای تست را با پیکربندی خاصی مرتبط کنید، می‌توانید --config-ids آرگومان با لیست شناسه های پیکربندی جدا شده با کاما.

$ 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"

اکنون باید اجرای تست جدید را تحت برنامه آزمایشی مشخص شده مشاهده کنید. این روش دیگری برای پیگیری نتایج تست خودکار خود در یک مکان است.

در حال به روز رسانی نتایج تست در اجرای تست موجود #

تصور کنید قبلاً TestRail CLI را اجرا کرده‌اید و نتایج تست خودکار خود را روی TestRail دارید، اما برخی از تست‌ها شکست خوردند و می‌خواهید آن‌ها را دوباره اجرا کنید و آزمایش موجود را با نتایج جدید به‌روزرسانی کنید. به منظور انجام این کار، شما فقط باید عبور کنید --run-id آرگومان و TestRail CLI اجرای تست را با آن شناسه به روز می کند.

$ 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"

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

به روز رسانی نتایج آزمون بر اساس نتایج آزمون سفارشی #

اکنون می‌توانید با نگاشت وضعیت‌های پیش‌فرض نتایج تست (به‌عنوان مثال، تأیید شده، ناموفق، رد شده) آنها را با نگاشت آنها به شناسه‌های وضعیت سفارشی خود در TestRail لغو کنید – همه اینها از طریق یک به‌روزرسانی ساده config.yaml.

چرا این مهم است:

• پشتیبانی از گردش کار انعطاف‌پذیر: نتایج آزمون را با طبقه‌بندی وضعیت منحصربه‌فرد تیم شما همراستا می‌کند (به‌عنوان مثال «Automation Passed»، «Error in Execution»)
• کار دستی را کاهش می دهد: نیاز به به روز رسانی دستی وضعیت ها پس از آپلود نتایج را از بین می برد
• ادغام اتوماسیون آسانتر: رویکرد پیکربندی محور، ادغام با خطوط لوله CI/CD و ابزارهای اتوماسیون را آسانتر می کند.
• سازگار با عقب: به طور یکپارچه با جریان های کاری موجود که از وضعیت های پیش فرض استفاده می کنند کار می کند

نمونه نقشه برداری:

• تصویب شد → “Automation Passed” (ID: ۷)
• ناموفق → “اتوماسیون ناموفق” (ID: ۸)
• رد شد → «مرحله رد شد» (ID: ۳)
• خطا → “خطا در اجرا” (ID: ۴)

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

نحوه پیاده سازی:

ابتدا باید تست‌کیس‌ها نتایج سفارشی را در نمونه خود ایجاد کنید و سپس شناسه هر وضعیت را به نتیجه ای که از اجرا برگردانده می شود نگاشت کنید.

بعد از اینکه تعریف روی TestRail تنظیم شد، فقط باید آن را پاس کنید --case_result_statuses آرگومان و شناسه هر نوع نتیجه و سپس هنگام تجزیه اطلاعات نقشه برداری می شود.

$ 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"

#

به روز رسانی فیلدهای سفارشی در تست‌کیس‌ها موجود #

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

• شناسه های اتوماسیون پس از بازسازی مجدد به روز شد
• پیش شرط های جدید در طول آزمایش کشف شد
• تغییر انواع اتوماسیون (به عنوان مثال، از دستی به خودکار)

شما می خواهید این فیلدهای سفارشی را در تست‌کیس‌ها موجود بدون ایجاد موارد تکراری به روز کنید. برای انجام این کار، باید JUnit xml خود را با فیلدهای سفارشی به روز شده به روز کنید، سپس 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"

بستن اجرای تست #

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

$ 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"

می توانید اجرای تست خود را در قسمت Completed Test runs پیدا کنید.

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

برای TestRail نسخه ۵.۵ و بالاتر، می توان نتایج آزمون را بر حسب میلی ثانیه ارسال کرد (یعنی: ۰.۰۰۱ ثانیه). رفتار پیش‌فرض TestRail CLI زمان را به ثانیه گرد می‌کند تا برای هر نسخه TestRail کار کند. اگر یکی از نسخه هایی را اجرا می کنید که از میلی ثانیه پشتیبانی می کند و می خواهید زمان سپری شده را در نتیجه خود با استفاده از میلی ثانیه ببینید، می توانید --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"

در نتایج تست خود، اکنون باید میدان سپری شده را با استفاده از میلی ثانیه ببینید.

با استفاده از فایل های پیکربندی برای ذخیره تنظیمات جایگزین #

به سرعت و به راحتی نتایج را به نمونه ها یا پروژه های مختلف ارسال کنید، از اعتبارنامه های مختلف یا سایر پارامترهای از پیش تعیین شده در دستورات خود با استفاده از یک فایل پیکربندی جایگزین استفاده کنید. فایل پیکربندی با فرمت YAML با نام نوشته می شود config.ymlو در همان دایرکتوری فایل اجرایی TRCLI ذخیره می شود، مگر اینکه طور دیگری مشخص شده باشد. از متغیرهای محیطی نیز می توان استفاده کرد. اگر یک فایل پیکربندی در دستور ارجاع داده شود، تمام پارامترهای داخل فایل پیکربندی، متغیرهای محیط را لغو می‌کنند. هر پارامتری که در دستور مشخص شده باشد، فایل پیکربندی را لغو می کند.

مثال زیر استفاده از یک فایل پیکربندی جایگزین را نشان می دهد که اعتبار کاربران را ذخیره می کند:

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"

ایجاد اجرای تست جدید #

هنگامی که یک اجرای تست باید قبل از استفاده از یکی از دستورات تجزیه ایجاد شود، از آن استفاده کنید add_run فرمان به عنوان مثال، اگر تست‌ها بر روی گره‌های آزمایشی مستقل و موازی اجرا شوند، همه گره‌ها باید نتایج خود را در یک اجرای تست گزارش کنند. ابتدا از add_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.