یکپارچه‌سازی با JUnit۵

JUnit5 یکی از محبوب‌ترین فریم‌ورک‌های unit testing در اکوسیستم Java است و با کتابخانه‌های مناسب، می‌توان از آن برای سطوح دیگر تست، مثل integration test یا حتی system test همراه با تعاملات UI هم استفاده کرد. در این آموزش بررسی می‌کنیم که چطور نتایج تولیدشده از یک test run خودکار JUnit5 را با استفاده از TestRail CLI. در TestRail ثبت و متمرکز کنیم. با این کار می‌توانید نتایج تست‌های خودکار را در یک جا نگه دارید و از قابلیت‌های تحلیلی و گزارش‌دهی TestRail استفاده کنید.

نمای کلی #

در این آموزش از یک sample project استفاده می‌کنیم تا مراحل راه‌اندازی یک project تست خودکار JUnit5 سازگار با TestRail CLI و آپلود نتایج تست تولیدشده را قدم‌به‌قدم دنبال کنید.

پس از مطالعه این آموزش، می‌توانید:

• تست‌ها را از یک project ساده JUnit5 اجرا کنید
• TestRail CLI را نصب کنید
• نمونه TestRail خود را پیکربندی کنید
• CLI را اجرا کنید
• test caseها و نتایج تست خود را در TestRail ببینید

پیش‌نیازها #

برای نصب و اجرای یک project تست Java با JUnit5، کافی است Java SE Development Kit را نصب کنید. برای sample project این آموزش، باید Maven را هم نصب داشته باشید؛ Maven برای مدیریت dependencyها و اجرای مراحل project استفاده می‌شود.

برای نصب و اجرای TestRail CLI که نتایج تست را به TestRail وارد می‌کند، به Python هم نیاز دارید.

پیش‌نیاز	توضیح
Java SE Development Kit 11	نسخه مناسب سیستم‌عامل خود را دانلود کنید و مراحل نصب را طبق راهنمای installer پیش ببرید. برای مطمئن شدن از نصب موفق، دستور java --version و javac --version را از command line اجرا کنید؛ باید نسخه نصب‌شده نمایش داده شود.
Maven3	نسخه مناسب سیستم‌عامل خود را دانلود کنید و فایل را در محل دلخواه خود از حالت فشرده خارج کنید. مسیر پوشه bin را به متغیر محیطی PATH اضافه کنید. برای مطمئن شدن از نصب موفق، دستور mvn --version را از command line اجرا کنید؛ باید نسخه نمایش داده شود.
Python 3.10.4	نسخه مناسب سیستم‌عامل خود را دانلود کنید و مراحل نصب را طبق راهنمای installer پیش ببرید. برای مطمئن شدن از نصب موفق، دستورهای python --version و pip --version را از command line اجرا کنید؛ باید نسخه هرکدام نمایش داده شود.

نصب sample project #

بیایید با دریافت کد sample project و نصب dependencyهای لازم شروع کنیم.

1. کلون یا دانلود کنید: sample project
2. command prompt را در پوشه root پروژه باز کنید و دستور زیر را اجرا کنید

$ mvn clean compile

نیازمندی	توضیح
(dependency) junit-jupiter-engine	چارچوب اتوماسیون تست که یک TestEngine برای اجرای تست‌های مبتنی بر Jupiter روی پلتفرم فراهم می‌کند
(dependency) junit-jupiter-params	افزونه‌ای برای امکان نوشتن تست‌های پارامتری
(dependency) testrail-junit-extensions	افزونه‌ای برای تنظیم propertyهای سفارشی در گزارش، مثلا برای اضافه کردن attachment یا هر metadata دیگر
(plugin) maven-surefire-plugin	پلاگینی که تست‌ها را اجرا می‌کند و گزارش‌هایی با سبک JUnit تولید می‌کند
(plugin) maven-site-plugin	پلاگینی برای اجرای goal سایت در Maven

بررسی پروژه نمونه #

پروژه نمونه را با IDE دلخواهتان باز کنید و فایل‌های test را بررسی کنید. ما کد تست‌های خودکار را ساده نگه داشته‌ایم تا تمرکز این آموزش روی نحوه وارد کردن نتایج اجرا بماند. همان‌طور که در مثال زیر می‌بینید، این تست‌ها فقط چند اعتبارسنجی ساده ریاضی هستند.

package com.idera.testrail.tests;

import com.testrail.junit.customjunitxml.TestRailTestReporter;
import com.testrail.junit.customjunitxml.TestRailTestReporterParameterResolver;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;

class SumTests {

    @Test
    @DisplayName("Add Two Numbers")
    void AddTwoNumbers() {
        assertEquals(3, 1+2, "1 + 2 should equal 3");
    }

    @Test
    @DisplayName("Add Two Numbers With Decimals")
    void AddTwoNumbersWithDecimals(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_attachment", "sample_reports/testrail.jpg");
        assertEquals(3, 1.5+1.4, "1.5+1.4 should equal 3");
    }

    @Nested
    class AddMoreNumbersTests {

        @Test
        @DisplayName("Add Three Numbers")
        void AddThreeNumbers() {
            assertEquals(3, 1+1+1, "1+1+1 should equal 3");
        }
    }
}

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

با استفاده از testrail-junit-extensions می‌توانید در کد خود propertyهایی به گزارش JUnit اضافه کنید. این کار به شما اجازه می‌دهد مثلا testrail_attachment  را به‌عنوان propertyهایی شامل مسیر فایل‌هایی تنظیم کنید که می‌خواهید هنگام upload گزارش از طریق TestRail CLI، به test result شما در TestRail پیوست شوند.

برای استفاده از قابلیت‌هایی که test execution listener مربوط به testrail-junit-extensions فراهم می‌کند، ابتدا باید آن را register کنید. این کار در فایل org.junit.platform.launcher.TestExecutionListener ، با تنظیم namespace مربوط به listener ت testrail-junit-extensions در قطعه‌کد زیر انجام می‌شود. این فایل از قبل در پروژه تنظیم شده است، بنابراین لازم نیست نگران آن باشید.

com.testrail.junit.customjunitxml.EnhancedLegacyXmlReportGeneratingListener

سپس در test classهای خود، کافی است آن‌ها را با annotation موجود در قطعه‌کد زیر extend کنید و TestRailTestReporter را به‌عنوان argument به test methodهای خود اضافه کنید. تنظیم propertyها به‌سادگی استفاده از setProperty() با key و value دلخواه است. در قطعه‌کد زیر نمونه‌ای را می‌بینید که یک attachment را تنظیم می‌کند تا همراه با test result به TestRail ارسال شود.

@ExtendWith(TestRailTestReporterParameterResolver.class)
class SumTests {
    @Test
    @DisplayName("Add Two Numbers With Decimals")
    void AddTwoNumbersWithDecimals(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_attachment", "sample_reports/testrail.jpg");
        assertEquals(3, 1.5+1.4, "1.5+1.4 should equal 3");
    }
}

اجرای پروژه نمونه #

در همان command prompt، دستور زیر را اجرا کنید تا تست‌های JUnit5 در پروژه اجرا شوند و نتایج با فرمت JUnit XML ذخیره شوند.

$ mvn clean compile test

اگر دستور Maven درست اجرا شده باشد، باید بتوانید test resultهای خود را در پوشه target ببینید. این پوشه باید یک فایل XML با نام TEST-junit-jupiter.xml داشته باشد. در مرحله بعد، TestRail CLI این فایل را parse می‌کند تا test run ساخته شود و test resultهای شما در TestRail آپلود شوند.

<?xml version="1.0" encoding="UTF-8"?>
<testsuite xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://maven.apache.org/surefire/maven-surefire-plugin/xsd/surefire-test-report-3.0.xsd" version="3.0" name="com.idera.testrail.tests.SumTests$AddMoreNumbersTests" time="0.002" tests="3" errors="0" skipped="0" failures="1">
  <properties>
    <property name="sun.desktop" value="windows"/>
    <property name="awt.toolkit" value="sun.awt.windows.WToolkit"/>
    <property name="java.specification.version" value="11"/>
  </properties>
  <testcase name="AddTwoNumbersWithDecimals" classname="com.idera.testrail.tests.SumTests" time="0.003">
    <properties>
      <property name="test_summary" value="Add Two Numbers With Decimals"/>
      <property name="testrail_attachment" value="sample_reports/testrail.jpg"/>
    </properties>
    <failure message="1.5+1.4 should equal 3 ==&gt; expected: &lt;3.0&gt; but was: &lt;2.9&gt;" type="org.opentest4j.AssertionFailedError">
      <![CDATA[org.opentest4j.AssertionFailedError: 1.5+1.4 should equal 3 ==> expected: <3.0> but was: <2.9>
      at org.junit.jupiter.api.AssertionUtils.fail(AssertionUtils.java:55)
      at org.junit.jupiter.api.AssertionUtils.failNotEqual(AssertionUtils.java:62)
      at org.junit.jupiter.api.AssertEquals.assertEquals(AssertEquals.java:70)
      at org.junit.jupiter.api.Assertions.assertEquals(Assertions.java:925)
      at com.idera.testrail.tests.SumTests.AddTwoNumbersWithDecimals(SumTests.java:20)
      (...)
      ]]>
    </failure>
  </testcase>
  <testcase name="AddTwoNumbers" classname="com.idera.testrail.tests.SumTests" time="0.002"/>
  <testcase name="AddThreeNumbers" classname="com.idera.testrail.tests.SumTests$AddMoreNumbersTests" time="0.001"/>
</testsuite>

وارد کردن نتایج به TestRail #

بعد از اجرای تست‌ها و تولید فایل‌های گزارش JUnit، می‌توانید test resultهای خود، و حتی test caseها، را به‌راحتی به TestRail وارد کنید. با این کار test runهای خودکار شما در TestRail قابل مشاهده می‌شوند و می‌توانید تصویر کلی‌تری از نحوه تست کردن app خود در همان TestRail ببینید.

نصب TestRail CLI #

اگر Python از قبل روی دستگاه شما نصب باشد، نصب TestRail CLI فقط کافی است دستور زیر را در command line اجرا کنید.

$ pip install trcli

پیکربندی TestRail #

در مرحله بعد، باید TestRail instance خود را طبق دستورالعمل‌های زیر پیکربندی کنید.

1. فعال کنید TestRail API با رفتن به Admin > Site Settings ، روی API تب کلیک کنید و گزینه Enable API را فعال کنید.
2. یک Custom Field ایجاد کنید تا کد test caseهای خودکار شما به caseهای واقعی در TestRail نگاشت شود. برای این کار به Admin > Customizations بروید و روی Add Field کلیک کنید. بعد از ورود به صفحه ایجاد فیلد، این custom field باید دو شرط زیر را داشته باشد:
   • فیلد System Name باید برابر باشد با automation_id
   • فیلد Type باید برابر باشد با Text

ارسال نتایج به TestRail #

بعد از نصب TestRail CLI و تکمیل پیکربندی TestRail instance، می‌توانید نتایج test خود را به‌سادگی با یک دستور تک‌خطی مانند نمونه زیر upload کنید.

$ trcli -y \
>  -h https://INSERT-INSTANCE-NAME.testrail.io \
>  --project "My Project" \
>  --username INSERT-EMAIL \
>  --password INSERT-PASSWORD \
>  parse_junit \
>  --title "JUnit5 Automated Test Run" \
>  -f "./target/TEST-junit-jupiter.xml"

توجه داشته باشید اگر محل پیش‌فرض report file را تغییر داده‌اید، نام فایل بعد از گزینه ‎-f‎ باید با مسیر همان فایل هماهنگ باشد. سایر گزینه‌ها هم باید بر اساس TestRail instance و project شما تنظیم شوند. برای بررسی گزینه‌های دیگر command line می‌توانید به TestRail CLI README.md در repository پروژه، مقاله مستندات TRCLI، یا راهنمای داخلی CLI از طریق دستورهای زیر مراجعه کنید.

$ trcli --help
$ trcli parse_junit --help

نمایش نتایج در TestRail #

حالا اگر به صفحه Test Cases در project خود در TestRail بروید، می‌بینید که TestRail CLI به‌صورت خودکار test caseهایی را که در گزارش نتایج test شما وجود داشتند ایجاد کرده است. همچنین می‌بینید که با ترکیب classname و name attributeهای هر test در گزارش JUnit، یک Automation ID منحصربه‌فرد اضافه شده است. این Automation ID برای نگاشت testهای موجود در کدبیس automation شما به test caseهای TestRail استفاده می‌شود. یعنی هر بار که TestRail CLI را اجرا می‌کنید، ابتدا تلاش می‌کند یک test case موجود در TestRail را پیدا و match کند و فقط وقتی test caseای با آن Automation ID وجود نداشته باشد، یک مورد جدید ایجاد می‌کند.

در صفحه Test Runs & Results می‌توانیم ببینیم که یک test run با نام JUnit5 Automated Test Run ایجاد شد. با باز کردن آن می‌توانیم جزئیات هر نتیجه‌ی تست خودکار را دقیق‌تر بررسی کنیم و در سطح کلی بفهمیم چرا یک test fail شده است؛ چون پیام خطایی که فریم‌ورک اتوماسیون تست ارائه می‌کند هم در نتیجه‌ی تست ثبت می‌شود، همان‌طور که در تصویر زیر می‌بینید.

مرحله‌ی بعد چیست؟ #

حالا که نتایج تست‌های خود را در TestRail متمرکز کرده‌اید، علاوه بر بررسی نتایج test runهای خودکار و پیام خطای تست‌های failشده، می‌توانید تلاش‌های تست دستی و خودکار خود را در گزارش‌هایی ترکیب کنید که پوشش کامل تست برای اپلیکیشن شما را نشان می‌دهند و حتی پیشرفت test automation را دنبال می‌کنند. همچنین می‌توانید درست مثل نتایج تست دستی، یک bug را مستقیماً از نتیجه‌ی تست خودکار به issue tracker دلخواهتان گزارش کنید.

برای آشنایی با نحوه‌ی استفاده از قابلیت‌های گزارش‌دهی TestRail، می‌توانید ویدیوی گزارش‌ها و معیارهای تست در TestRail را ببینید.