GitHub Actions خودکارسازی همه workflowهای توسعه نرمافزار را ساده میکند. با آن میتوانید کد خود را مستقیماً از GitHub بسازید، test کنید و deploy کنید. Workflowها میتوانند با رویدادهای GitHub مثل push، ایجاد issue، انتشار release جدید، یا حتی اجرای دستی workflow شروع شوند.
یکی از کاربردهای رایج GitHub Actions این است که هر بار تغییرات کد ارسال میشود، اپلیکیشن شما بهصورت خودکار build و test شود. برای اینکه testهای خودکار خود را بهتر ببینید و همه test caseها و نتایج test، چه دستی و چه خودکار، را آسانتر مدیریت کنید، میتوانید نتایج testهای خودکار را مستقیماً از GitHub به TestRail بفرستید. در این مقاله بررسی میکنیم که چطور میتوانید از GitHub Actions و TestRail CLI برای انجام ساده این کار استفاده کنید.
در این مثال، از GitHub Actions همراه با Cypress استفاده میکنیم.
اگر میخواهید نمونههای بیشتری ببینید، به Automation Frameworks Integration نگاهی بیندازید؛ بهویژه run-all.yml ، یعنی فایل workflow، و اجرای workflow مربوط به آن.
استفاده از TestRail CLI در فایلهای workflow در GitHub #
فرآیندهای خودکار را میتوان در GitHub با استفاده از فایلهای پیکربندی workflow تنظیم کرد. این فایلها با فرمت YAML هستند و به شما امکان میدهند فرآیندهای خود را بهشکل ساختاریافته تعریف کنید و در هر مرحله از GitHub Actions استفاده کنید تا هم پیکربندی محیط اجرا سادهتر شود و هم هر action موردنیاز اجرا شود.
سادهترین راه ادغام TestRail با GitHub Actions این است که فایلهای workflow خود را طوری تنظیم کنید که TestRail CLI نتایج testهای خودکار را به TestRail ارسال کند. در ادامه نمونهای از یک فایل workflow را میبینید که از TestRail CLI برای ارسال نتایج test به TestRail استفاده میکند.
name: send-results-to-testrail
on: [workflow_dispatch]
jobs:
send-test-results-to-testrail:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Execute automated tests
uses: ...
- name: Python setup
if: always()
uses: actions/setup-python@v3
with:
python-version: '3.x'
- name: TestRail CLI upload results
if: always()
run: |
pip install trcli
trcli -y \
-h https://TESTRAIL_INSTANCE.testrail.io/ \
--project "PROJECT NAME" \
-u USER_EMAIL \
-p PASSWORD \
parse_junit \
--title "Automated Tests from GitHub workflow" \
--run-description ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} \
-f "junit-report.xml"اگر فایل را بخشبهبخش بررسی کنیم، چند نکته مهم میبینیم:
- رویداد trigger
on: [workflow_dispatch]یعنی این workflow فقط زمانی اجرا میشود که بهصورت دستی آن را اجرا کنید. رویدادهای دیگری هم میتوانند یک workflow را trigger کنند، مثل push کردن کد، ایجاد pull request و موارد مشابه. - در
jobsیک مورد به نامexecute-testsداریم؛ یعنی در این workflow فقط یک job وجود دارد. - این
execute-testsjob عامل اجرای خود را باruns-on: ubuntu-latestتعریف میکند و شامل stepهای زیر استstepsکه در بخشهای بعدی آنها را توضیح میدهیم.CheckoutExecute automated testsPython setupTestRail CLI upload results
میتوانید درباره قابلیتهای workflowها در مستندات رسمی GitHub workflows documentation بیشتر بخوانید.
مرحله ۱: Checkout #
این Checkout step از actions/checkout@v3 GitHub Action استفاده میکند که checkout کردن کد repository شما را روی agent انجام میدهد.
- name: Checkout
uses: actions/checkout@v3مرحله ۲: اجرای تستهای خودکار #
مرحله Execute automated tests فقط یک placeholder است. در این مرحله، تستهای خودکاری که در codebase خود دارید اجرا میشوند و گزارش JUnit لازم برای ارسال نتایج به TestRail تولید میشود. این کار را میتوانید با استفاده از یک GitHub Action یا با اضافه کردن اسکریپت اجرای سفارشی خود انجام دهید.
name: Execute Automated tests
uses: ...مرحله ۳: نصب Python روی agent #
مرحله Python setup از actions/setup-python@v3 GitHub Action برای پیکربندی Python روی agent استفاده میکند. از آنجا که TestRail CLI ابزاری است که با Python توسعه داده شده، قبل از نصب و اجرای آن باید Python در محیط نصب شده باشد.
همچنین به if: always() شرط توجه کنید؛ این شرط باعث میشود این مرحله همیشه اجرا شود، چه test run خودکار موفق شده باشد چه نه. دلیلش این است که بهطور پیشفرض، بیشتر test automation frameworkها اگر حتی یک test ناموفق باشد با error code خارج میشوند.
- name: Python setup
if: always()
uses: actions/setup-python@v3
with:
python-version: '3.x'مرحله ۴: نصب TestRail CLI و آپلود نتایج تست #
مرحله TestRail CLI upload results یک shell script سفارشی اجرا میکند تا TestRail CLI را نصب و فراخوانی کند، گزارش JUnit تولیدشده توسط test automation framework شما را parse کند و نتایج را به TestRail بفرستد.
TestRail CLI یک package پایتونی است که در Python Package Index میزبانی میشود (PyPI). بنابراین برای نصب آن، کافی است دستور pip install trcli را اجرا کنیم.
بعد از نصب TestRail CLI، باید چند آرگومان اجباری را مشخص کنید؛ مثل آدرس instance و credentials در TestRail، projectی که میخواهید نتایج در آن گزارش شود، عنوان test run و مسیر گزارش JUnit. آرگومان run description اجباری نیست، اما پیشنهاد میکنیم از آن برای اضافه کردن لینک اجرای GitHub workflow در TestRail استفاده کنید. این لینک را میتوانید با ساختن URL بر اساس متغیرهای داخلی GitHub، مانند snippet زیر، به دست آورید.
برای اطلاعات بیشتر درباره آرگومانها، به مستندات TestRail CLI مراجعه کنید.
- name: TestRail CLI upload results
if: always()
run: |
pip install trcli
trcli -y \
-h https://TESTRAIL_INSTANCE.testrail.io/ \
--project "PROJECT NAME" \
-u USER_EMAIL \
-p PASSWORD \
parse_junit \
--title "Automated Tests from GitHub workflow" \
--run-description ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} \
-f "junit-report.xml"نمونه عملی با Cypress #
در ادامه نمونهای از یک فایل GitHub workflow آمده است که به زبان ساده، تستهای Cypress را اجرا میکند و نتایج تست را مستقیم به TestRail میفرستد.
name: cypress-tests
on: [workflow_dispatch]
jobs:
execute-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Cypress run
id: cypress
uses: cypress-io/github-action@v4
with:
command: npx cypress run --reporter junit --reporter-options mochaFile=reports/TEST-[hash].xml
- name: Python setup
if: always()
uses: actions/setup-python@v3
with:
python-version: '3.x'
- name: TestRail CLI upload results
if: always()
run: |
pip install trcli
trcli -y \
-h https://TESTRAIL_INSTANCE.testrail.io/ \
--project "PROJECT NAME" \
-u USER_EMAIL \
-p PASSWORD \
parse_junit \
--title "Automated Tests from GitHub workflow" \
--run-description ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} \
-f "reports/junit*.xml"اگر فایل را بررسی کنیم، فقط دو تفاوت قابل توجه بین این workflow و GitHub workflow عمومیای که قبلتر مرور کردیم وجود دارد:
- مرحله دوم با
Cypress runجایگزین شده است که ازcypress-io/github-actions@v4GitHub Action استفاده میکند؛ این Action وابستگیهای project در Cypress را نصب میکند و دستورهای مشخصشده درwithپارامتر را اجرا میکند و به این ترتیب یک test run خودکار شروع میشود. - در
TestRail CLI upload results، از نسخه ۱.۶.۰ به بعد در TestRail CLI، مسیر گزارش از wildcard پشتیبانی میکند و میتوانید چند گزارش را بدون دردسر با هم merge کنید. این قابلیت کمک میکند نتایج منابع مختلف را در یک run submission واحد تجمیع کنید. برای اطلاعات بیشتر، مستندات مربوط به یکپارچهسازی با Cypress را ببینید.
ایجاد repository خودتان #
در ادامه، GitHub workflow بالا را با استفاده از sample project در Cypress راهاندازی میکنیم. برای اطلاعات بیشتر درباره آن، مستندات یکپارچهسازی با Cypress را ببینید.
با دنبال کردن مراحل زیر، خیلی سریع یک GitHub workflow خواهید داشت که تستها را اجرا میکند و نتایج را به TestRail گزارش میدهد.
- یک repository جدید در GitHub ایجاد کنید
- فایلها را از نمونه project برای Cypress
- فایل cypress-tests.yml را در مسیر .github/workflows اضافه کنید و محتوای مثال بالا را در آن کپی کنید
- در محتوای فایل، مقادیر TESTRAIL_INSTANCE ، PROJECT NAME ، USER_EMAIL و PASSWORD را با اطلاعات خودتان جایگزین کنید (توصیه میکنیم password را مستقیم در فایل نگذارید و بهجای آن از GitHub secrets استفاده کنید)
- project را در GitHub repository خود آپلود کنید
اجرای workflow #
- به صفحه Actions در repository خود بروید؛ workflow شما باید در فهرست دیده شود
- از آنجا که این workflow از نوع manual dispatch است، برای اجرای آن ابتدا در سمت چپ روی نام workflow کلیک کنید و بعد روی دکمه Run workflow کلیک کنید
- بعد میتوانید وارد جزئیات workflow شوید تا ببینید مشکل از کجا بوده است. لاگهای اجرا بر اساس step جدا شدهاند. در تصویر زیر میبینیم که اجرای Cypress ناموفق بوده است
- با بررسی دقیقتر لاگهای Cypress run میبینیم اجرا درست انجام شده، اما یک test ناموفق بوده است. با اینکه test شکست خورده، Python setup و TestRail CLI upload results همچنان اجرا شدند، چون از
if: always()condition در test step استفاده کردیم تا مطمئن شویم حتی وقتی testها fail میشوند، نتایج به TestRail ارسال میشوند
- به TestRail instance خود بروید و نتایج Test Run را ببینید. دقت کنید که یک لینک برگشت به GitHub workflow دارید تا بتوانید test results را راحتتر debug کنید!
گام بعدی چیست؟ #
حالا که test results خود را در TestRail متمرکز کردهاید، نهتنها میتوانید نتایج automated test runs و پیامهای خطای testهای ناموفق را بررسی کنید، بلکه میتوانید فعالیتهای manual و automated testing را در reportهایی کنار هم بیاورید که test coverage کامل اپلیکیشن شما را نشان میدهند و حتی پیشرفت test automation را دنبال میکنند. همچنین میتوانید مثل نتایج manual test، bug را مستقیم از automated test result در issue tracker دلخواه خود گزارش کنید!
برای آشنایی بیشتر، میتوانید ویدئوی TestRail’s Reports and Test Metrics را ببینید و با قابلیتهای reporting در TestRail آشنا شوید.
