نگاشت JUnit به TestRail

فرمت JUnit XML یکی از رایج‌ترین روش‌ها برای frameworkهای test automation و ابزارهای CI است تا نتایج تست را ذخیره و به اشتراک بگذارند. 

ابزار TestRail CLI می‌تواند:

• یک گزارش JUnit XML را بخواند
• محتوای آن را به entityهای TestRail Suite، Section، Case و Result
• تبدیل کند و آن‌ها را با استفاده از API وارد TestRail کند

در این راهنما توضیح داده می‌شود:

1. JUnit XML چگونه به TestRail نگاشت می‌شود
2. تگ‌های <testsuite> و <testcase> چگونه پردازش می‌شوند
3. چطور از custom properties در JUnit برای TestRail استفاده کنید
4. چطور نتایج automation را به statusهای سفارشی نگاشت کنید با <case_results_statuses>

نمونه گزارش JUnit

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="3049" name="tests.LoginTests">
    <properties>
      <property name="setting1" value="True"/>
      <property name="setting2" value="value2"/>
    </properties>
    <testcase classname="tests.LoginTests" name="test_case_1" time="159">
      <skipped type="pytest.skip" message="Please skip">skipped by user</skipped>
    </testcase>
    <testcase classname="tests.LoginTests" name="test_case_2" time="650">
    </testcase>
    <testcase classname="tests.LoginTests" name="test_case_3" time="121">
      <failure type="pytest.failure" message="Fail due to...">failed due to...</failure>
    </testcase>
  </testsuite>
</testsuites>

نگاشت تگ‌های JUnit به TestRail

وقتی TestRail CLI یک گزارش JUnit را parse می‌کند، هر تگ گزارش JUnit طبق جدول زیر به یک entity در TestRail تبدیل می‌شود.

JUnit <testsuite> handling

Elementهایی که تگ <testsuite> دارند، به sectionهای TestRail تبدیل می‌شوند و propertyهای آن‌ها به توضیحات test run در TestRail اضافه می‌شود. در ادامه می‌توانید نمونه‌ای از یک <testsuite> همراه با <property> تگ‌های فرزند را ببینید.

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="3049" name="tests.LoginTests">
    <properties>
      <property name="setting1" value="True"/>
      <property name="setting2" value="value2"/>
    </properties>
    (...)
  </testsuite>
</testsuites>

JUnit <testcase> نحوه پردازش

Elementهایی که <testcase> tag دارند، به test caseهای TestRail و test resultهای مربوطه تبدیل می‌شوند. 

• هر <testcase> به‌عنوان یک test case در TestRail وارد می‌شود همراه با یک test result
• مقدار status بر اساس tagهای فرزند تعیین می‌شود

اگر هیچ tagی وجود نداشته باشد، test result برابر است با Passed ، اما اگر یک <failure> tag وجود داشته باشد، test result برابر است با Failed ، و اگر یک <skipped> tag وجود داشته باشد، result برابر است با Retest. نمونه‌ها را می‌توانید در جدول زیر ببینید.

<testcase classname="tests.LoginTests" name="test_case_1" time="135">
</testcase>

<testcase classname="tests.LoginTests" name="test_case_1" time="135">
  <failure type="errorType" message="Failure message">
    Error (stacktrace)
  </failure>
</testcase>

<testcase classname="tests.LoginTests" name="test_case_1" time="135">
  <skipped type="skipType" message="Skip test">
    Test skipped by user
  </skipped>
</testcase>

داده‌های موجود در attributeها و متن <failure> و <skipped> tagها، با قالبی مانند نمونه زیر، به comment مربوط به test result اضافه می‌شود.

Type: errorType
Message: Failure message
Text: Error (stacktrace)

افزودن داده‌های سفارشی تست از طریق <property>

می‌توانید fieldها، stepها، commentها و attachmentهای اضافی با استفاده از نام‌های خاص property. propertyهای پشتیبانی‌شده و معنی هرکدام در جدول زیر آمده است.

در ادامه، نمونه‌ای از یک report را می‌بینید که همه فیلدهای فهرست‌شده را دارد. برای اطلاعات بیشتر درباره نحوه استفاده از این propertyها، به صفحه نمونه‌های استفاده از TestRail CLI مراجعه کنید.

<testsuites name="test suites root">
  <testsuite failures="0" errors="0" skipped="1" tests="1" time="3049" name="tests.LoginTests">
    <testcase classname="tests.LoginTests" name="test_case_1" time="650">
      <properties>
        <property name="testrail_case_field" value="custom_case_custom_preconds:My preconditions"/>
        <property name="testrail_case_field" value="custom_case_type_id:3"/>
        <property name="testrail_case_field" value="refs:SAMPLE-1,SAMPLE-2"/>
        <property name="testrail_result_field" value="custom_result_version:1.1"/>
        <property name="testrail_result_field" value="custom_result_custom_field:custom_value"/>
        <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"/>
        <property name="testrail_result_comment" value="Finding 1"/>
        <property name="testrail_result_comment" value="Finding 2"/>
        <property name="testrail_attachment" value="path_to/logs.log"/>
        <property name="testrail_attachment" value="path_to/screenshot.jpg"/>
     </properties>
    </testcase>
  </testsuite>
</testsuites>

نگاشت تست‌های خودکار به case IDهای موجود در TestRail

هنگام استفاده از TestRail CLI برای import کردن نتایج JUnit XML، می‌توانید تست‌های خودکار را با استفاده از test_id property به test caseهای موجود در TestRail نگاشت کنید.

به این ترتیب، به‌جای اینکه caseهای جدید به‌صورت خودکار ساخته شوند، تست‌های automation شما به caseهای متناظر در TestRail لینک می‌شوند.

چرا از نگاشت صریح case استفاده کنیم؟

نگاشت صریح زمانی مفید است که:

• تیم شما برای همان test caseها هم پوشش دستی و هم پوشش خودکار نگه می‌دارد
• می‌خواهید نتایج automation، caseهای موجود در TestRail را به‌روزرسانی کنند
• می‌خواهید بین pipelineهای CI/CD و test runهای TestRail گزارش‌دهی یکسانی داشته باشید

این نگاشت با استفاده از <property> tag داخل یک <testcase> element تعریف می‌شود.

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

ویژگی test_id از هر دو حالت تکی و چندتایی برای case IDهای TestRail پشتیبانی می‌کند.

۱. نگاشت به یک test case در TestRail

اگر تست خودکار دقیقاً با یک test case در TestRail مطابقت دارد، از یک case ID تکی استفاده کنید. مثال:

<testcase classname="tests.LoginTests" name="test_valid_login" time="120">
  <properties>
    <property name="test_id" value="C123"/>
  </properties>
</testcase>

در TestRail چه اتفاقی می‌افتد

• نتیجه test خودکار در TestRail آپلود می‌شود test case در TestRail C123
• وضعیت نتیجه (Passed، Failed، Retest) بر اساس ساختار نتیجه test در JUnit تعیین می‌شود

۲. نگاشت یک test خودکار به چند test case در TestRail

یک test خودکار می‌تواند چند test case در TestRail را اعتبارسنجی کند.
برای پشتیبانی از این سناریو، test_id این property یک فهرست case IDهای جداشده با کاما. مثال:

<testcase classname="tests.LoginTests" name="test_login_validation" time="200">
  <properties>
    <property name="test_id" value="C123, C456, C789"/>
  </properties>
</testcase>

در TestRail چه اتفاقی می‌افتد

وقتی چند case ID وارد شود:

• TestRail CLI ایجاد می‌کند نتیجه‌های test جداگانه برای هر case ارجاع‌شده
• هر case (C123 ، C456 ، C789) دریافت می‌کند همان وضعیت نتیجه را
• نتیجه‌ها به‌صورت جداگانه در test run مربوط به TestRail نمایش داده می‌شوند

نمونه خروجی در TestRail:

این روش زمانی مفید است که یک test خودکار واحد چند requirement یا رفتار را بررسی می‌کند که با caseهای مختلف در TestRail نمایش داده شده‌اند.

نمونه گزارش JUnit با نگاشت caseها

در ادامه یک مثال ساده می‌بینید که هر دو روش نگاشت را نشان می‌دهد.

<testsuites name="automation suite">
  <testsuite name="Login Tests">

    <!-- Single case mapping -->
    <testcase classname="tests.LoginTests" name="test_valid_login" time="120">
      <properties>
        <property name="test_id" value="C123"/>
      </properties>
    </testcase>

    <!-- Multiple case mapping -->
    <testcase classname="tests.LoginTests" name="test_login_validation" time="200">
      <properties>
        <property name="test_id" value="C123, C456, C789"/>
      </properties>
    </testcase>

  </testsuite>
</testsuites>

بهترین روش‌ها

• مطمئن شوید همه case IDهای ارجاع‌شده از قبل در TestRail وجود دارند.
• استفاده کنید از IDهای جداشده با کاما، بدون کاراکتر اضافه (مثلاً، C123, C456).
• وقتی یک automation test پوشش می‌دهد، از این قابلیت استفاده کنید چند test case دستی را.

اگر property مربوط به mapping ارائه نشده باشد، TestRail CLI تلاش می‌کند با استفاده از موارد زیر caseها را ایجاد یا پیدا کند: Automation ID تولیدشده از JUnit classname و name attributeها.

نکات کلیدی

• JUnit XML یک فرمت عمومی برای نتیجه‌های automation است.
• ابزار TestRail CLI این موارد را به‌صورت Suites، Sections، Cases و Results وارد TestRail می‌کند.
• case_results_statuses باعث می‌شود وضعیت‌های automation با workflow شما در TestRail هماهنگ باشند.
• از custom properties برای افزودن context، step و attachment بیشتر به resultها استفاده کنید.

• Automated testها می‌توانند به یک یا چند case در TestRail نگاشت شوند

• از test_id property در JUnit <testcase> element استفاده کنید

• برای چند case ID از مقادیر جداشده با کاما استفاده می‌شود

• هر case در TestRail یک result جداگانه دریافت می‌کند

مراحل بعدی

• نگاهی به پروژه نمونه Cypress-saucectl در GitHub برای دیدن مثال‌های عملی بیندازید.
• برای پارامترهای بیشتر، مستندات TestRail CLI را بررسی کنید.
• برای پیشنهاد بهبودها یا طرح سؤال، از GitHub تیم خود یا پشتیبانی TestRail استفاده کنید.