یکپارچه‌سازی با Azure Pipelines

Azure Pipelines پلتفرم مدیریت و هماهنگ‌سازی CI/CD در مجموعه ابزار Microsoft Azure DevOps است که به شما امکان می‌دهد build، تست و deploy را به‌صورت پیوسته روی هر platform و cloud انجام دهید. می‌توانید hardware و VMها را با agentهای cloud-hosted مایکروسافت مدیریت کنید یا agentهای self-hosted خودتان را راه‌اندازی کنید. همچنین از pipelineهای CI/CD برای همه platformها و ابزارهای اصلی پشتیبانی می‌کند و به شما اجازه می‌دهد با Azure Repos Git، GitHub، Bitbucket و ابزارهای دیگر یکپارچه شوید.

به‌عنوان بخشی از pipeline، تیم‌ها معمولاً تست‌های خودکارشان را اجرا می‌کنند. برای اینکه دید بهتری روی تست‌های خودکار داشته باشید و بتوانید همه test caseها و نتایج تست، چه دستی و چه خودکار، را راحت‌تر مدیریت کنید، می‌توانید نتایج تست‌های خودکار را مستقیم از Azure Pipelines به TestRail ارسال کنید. در این مقاله بررسی می‌کنیم چگونه می‌توانید از TestRail CLI در راه‌اندازی Azure Pipelines خود استفاده کنید تا این کار را به‌سادگی انجام دهید. 

پیش‌نیازها #

اگر می‌خواهید از self-hosted agent استفاده کنید، چه چون می‌خواهید executorهای خودتان را مدیریت کنید و چه چون اشتراک cloud-hosted executor ندارید، می‌توانید scriptهای لازم برای ساخت و اجرای یک Docker agent با Python ۳.۱۰.۱۲ ازپیش‌نصب‌شده را برای اجرای TestRail CLI از repository نمونه‌های integration اتوماسیون TestRail دریافت کنید. 

برای build و اجرا، کافی است <AZURE_URL> placeholder را با URL مربوط به instance خود جایگزین کنید (مثلاً: https://dev.azure.com/yourorganization) و <TOKEN> placeholder را با Azure Personal Access Token خود جایگزین کنید، سپس دستورهای زیر را در terminal و از همان folder اجرا کنید.

docker build -t azureagent:latest .
docker run -e AZP_URL="<AZURE_URL>" -e AZP_TOKEN="<TOKEN>" -e AZP_AGENT_NAME="SelfHostedLinux" azureagent:latest

استفاده از TestRail CLI در Azure Pipelines #

برای ایجاد pipeline، می‌توانید فایل azure-pipelines.yml را به ریشه هر repository سازگار اضافه کنید. این فایل به شما امکان می‌دهد processهای خود را با استفاده از syntax مربوط به YML به‌صورت ساختاریافته تعریف کنید. برای ساخت pipeline، می‌توانید چند نوع step تعریف کنید؛ برای مثال taskهایی برای آماده‌سازی environment، و همچنین scriptهایی که در آن‌ها می‌توانید commandهای shell را برای هر هدفی بنویسید.

ساده‌ترین راه برای یکپارچه‌سازی TestRail با Azure Pipelines این است که TestRail CLI را برای ارسال نتایج تست‌های خودکار به TestRail، در یکی از stepهای فایل azure-pipelines.yml خود پیکربندی کنید. در ادامه نمونه‌ای از یک Azure Pipeline را می‌بینید که از Playwright به‌عنوان framework اتوماسیون تست و از TestRail CLI برای ارسال نتایج تست به TestRail استفاده می‌کند.

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '16.x'
  displayName: 'Install Node.js'
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.10.12'
  displayName: 'Setup Python'

- script: |
    npm install
    npx playwright install-deps
    npx playwright install
    npx playwright test
  displayName: 'Run Playwright tests'
  continueOnError: true
- script: |
    pip install trcli
    trcli -y \
      -h "https://INSTANCE-NAME.testrail.io" \
      --project "PROJECT-NAME" \
      -u "USERNAME" \
      -p "PASSWORD" \
      parse_junit \
      -f "test-results/junit-report.xml" \
      --title "Playwright automated tests" \
      --run-description "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
  displayName: 'Upload results with TestRail CLI'

trigger:
- main

pool: Default

steps:
- task: NodeTool@0
  inputs:
    versionSpec: '16.x'
  displayName: 'Install Node.js'
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.10.12'
    disableDownloadFromRegistry: true
  displayName: 'Setup Python'

- script: |
    npm install
    npx playwright install-deps
    npx playwright install
    npx playwright test
  displayName: 'Run Playwright tests'
  continueOnError: true
- script: |
    pip install trcli
    trcli -y \
      -h "https://INSTANCE-NAME.testrail.io" \
      --project "PROJECT-NAME" \
      -u "USERNAME" \
      -p "PASSWORD" \
      parse_junit \
      -f "test-results/junit-report.xml" \
      --title "Playwright automated tests" \
      --run-description "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
  displayName: 'Upload results with TestRail CLI'

اگر فایل را بخش‌به‌بخش بررسی کنیم، موارد زیر را می‌بینیم:

• کلید trigger که طوری تنظیم شده است که با هر push به main در رویکرد CI، job را شروع کند
• بخش pool که agent محل اجرای stepها را مشخص می‌کند و بسته به اینکه بخواهید از agent میزبانی‌شده در cloud استفاده کنید یا agent self-hosted، متفاوت است.
• بخش steps شامل دو task برای آماده‌سازی محیط، و دو script برای اجرای testها و آپلود کردن نتایج است
  1. task: NodeTool@0 
  2. task: UsePythonVersion@0
  3. script (Run Playwright tests)
  4. script (Upload results with TestRail CLI)

برای اطلاعات بیشتر درباره پیکربندی pipeline، به مستندات رسمی Azure Pipelines مراجعه کنید.

مرحله ۱: نصب Node.js #

با استفاده از NodeTool@0 task می‌توانیم Node را به‌راحتی روی agent نصب کنیم؛ این کار برای اجرای testهای Playwright لازم است.

- task: NodeTool@0
  inputs:
    versionSpec: '16.x'
  displayName: 'Install Node.js'

مرحله ۲: راه‌اندازی Python #

این UsePythonVersion@0 task، Python را راه‌اندازی می‌کند که برای نصب و اجرای TestRail CLI لازم است. بسته به اینکه job را روی agent میزبانی‌شده در cloud اجرا می‌کنید یا روی agent self-hosted، باید این task را به شکل متفاوتی پیکربندی کنید.

برای agentهای میزبانی‌شده در cloud ، کافی است versionSpec را اضافه کنید تا خود task نسخه درخواستی را دانلود کرده و روی agent نصب کند.

برای agentهای self-hosted ، این task نمی‌تواند Python را دانلود و نصب کند؛ بنابراین Python باید از قبل روی agent پیکربندی شده باشد و باید disableDownloadFromRegistry: true را به تنظیمات ورودی اضافه کنید. توجه داشته باشید اگر برای راه‌اندازی agent self-hosted از کد ارائه‌شده در این آموزش استفاده کنید، Python ۳.۱۰.۱۲ از قبل روی agent نصب است و لازم نیست خودتان جداگانه آن را نصب کنید.

- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.10.12'
  displayName: 'Setup Python'

مرحله ۳: اجرای testهای Playwright #

این Run Playwright tests step شامل یک shell script است که project مربوط به Playwright را همراه با همه وابستگی‌های سیستمی لازم نصب می‌کند و testهای project را اجرا می‌کند. توجه داشته باشید project طوری پیکربندی شده است که یک گزارش JUnit در test-results/ folder تولید کند.

پارامتر continueOnError استفاده می‌شود تا pipeline حتی در صورت fail شدن testها، step بعدی را هم اجرا کند و نتایج test بتوانند در TestRail آپلود شوند.

- script: |
    npm install
    npx playwright install-deps
    npx playwright install
    npx playwright test
  displayName: 'Run Playwright tests'
  continueOnError: true

مرحله ۴: آپلود نتایج با TestRail CLI #

این Upload results with TestRail CLI step یک shell script را اجرا می‌کند تا TestRail CLI را نصب و فراخوانی کند، گزارش JUnit تولیدشده توسط Playwright را parse کند و نتایج را به TestRail بفرستد.

TestRail CLI یک package پایتون است که در Python Package Index میزبانی می‌شود (PyPI)؛ بنابراین برای نصب آن، کافی است دستور pip install trcli را اجرا کنیم.

بعد از نصب TestRail CLI، چند argument اجباری وجود دارد؛ مثل آدرس و credentials نمونه TestRail شما، projectی که می‌خواهید نتایج را در آن گزارش کنید، عنوان test run، و مسیر گزارش JUnit. آرگومان --run-description اجباری نیست، اما توصیه می‌کنیم از آن استفاده کنید تا از TestRail لینکی به اجرای job در Azure Pipelines اضافه شود. کد نمونه شامل مجموعه‌ای از predefined pipeline variableهاست که لینک اجرای job شما را خروجی می‌دهند.

- script: |
    pip install trcli
    trcli -y \
      -h "https://INSTANCE-NAME.testrail.io" \
      --project "PROJECT_NAME" \
      -u "USERNAME" \
      -p "PASSWORD" \
      parse_junit \
      -f "test-results/junit-report.xml" \
      --title "Playwright automated tests" \
      --run-description "$(System.TeamFoundationCollectionUri)$(System.TeamProject)/_build/results?buildId=$(Build.BuildId)"
  displayName: 'Upload results with TestRail CLI'

برای اطلاعات بیشتر درباره argumentها، مستندات TestRail CLI مستندات.

نمونه‌ی عملی با Playwright #

برای استفاده از Azure Pipelines، باید یک حساب فعال در Azure DevOps داشته باشید. کد شما می‌تواند در Azure Repos داخل instance شما در Azure DevOps میزبانی شود، یا از ابزار کنترل نسخه‌ی خارجی مثل GitHub یا Bitbucket استفاده کنید. در این مثال از Azure Repos استفاده می‌کنیم.

ایجاد repository خودتان #

می‌خواهیم Azure pipeline را با استفاده از پروژه‌ی نمونه‌ی Playwright راه‌اندازی کنیم؛ برای اطلاعات بیشتر می‌توانید مستندات ما درباره‌ی یکپارچه‌سازی با Playwright را ببینید.

با دنبال کردن مراحل زیر، می‌توانید به‌سرعت یک نمونه‌ی عملی از Azure pipeline راه‌اندازی کنید که یک پروژه‌ی automated tests را اجرا می‌کند و نتایج را به TestRail می‌فرستد.

1. یک project جدید در Azure DevOps ایجاد کنید

   
    

2. به بخش Repos بروید و یک repository جدید با فایل‌های موجود در پروژه‌ی نمونه‌ی Playwright

   
    

3. به بخش Pipelines بروید و روی Create Pipeline

   

    

4. نوع repository موردنظرتان را انتخاب کنید؛ در این مثال Azure Repos Git

   

    

5. repositoryای را که همین حالا ایجاد کرده‌اید انتخاب کنید

   
    

6. برای شروع، یکی از templateهای pipeline را انتخاب کنید

   
    

7. template را با فایل YML ارائه‌شده در بالا جایگزین کنید (فراموش نکنید placeholderهای INSTANCE-NAME ، PROJECT-NAME ، USERNAME و PASSWORD را جایگزین کنید؛ توصیه می‌کنیم password را مستقیم وارد نکنید و به‌جای آن از Azure secret variables استفاده کنید)

   
    

8. روی Save and run  کلیک کنید و commit را ادامه دهید تا azure-pipelines.yml فایل در repository شما ایجاد شود

   
    

9. از آنجا که trigger این pipeline با push به شاخه master فعال می‌شود، اجرای آن بلافاصله در صف قرار می‌گیرد.

   
    

10. با کلیک روی job می‌توانید execution logs آن را ببینید. در انتهای لاگ‌ها، لاگ‌های TestRail CLI نمایش داده می‌شود که لینکی به test run ایجاد می‌کند؛ همان جایی که نتایج testهای Playwright گزارش شده‌اند.

    
     

11. با کلیک روی این لینک، به TestRail هدایت می‌شوید. در آنجا می‌توانید نتایج test و اطلاعات debug را ببینید، همچنین لینکی برای بازگشت به اجرای job در اختیار دارید تا ردیابی و جابه‌جایی بین بخش‌ها ساده‌تر باشد.

    
     

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

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

برای آشنایی بیشتر، می‌توانید ویدیوی TestRail’s Reports and Test Metrics را ببینید و یاد بگیرید چطور از قابلیت‌های گزارش‌دهی TestRail استفاده کنید.