وب‌هوک‌ها

با Webhooks می‌توانید بر اساس رویدادهایی که در TestRail اتفاق می‌افتد، اطلاعات را به‌صورت real-time به برنامه‌های دیگر بفرستید.

در درخواست‌های معمول API، برای دریافت اطلاعات جدید باید مرتب داده‌ها را poll کنید. اما webhooks وقتی رویدادهای مشخصی در TestRail رخ می‌دهد، مثل وقتی تیم شما test case جدید اضافه می‌کند، test run جدید می‌سازد یا نتیجه test جدیدی را آپلود می‌کند، notification و payload را به سیستم‌ها یا برنامه‌های خارجی ارسال می‌کند. با این کار می‌توانید TestRail را با هر برنامه‌ای که API دارد integrate کنید، فرایندهای مهم چرخه تست را سریع‌تر پیش ببرید و دید بهتری از پیشرفت فعالیت‌های تست برای کل تیم ایجاد کنید.

نحوه اضافه کردن webhook #

برای اضافه کردن webhook دو روش وجود دارد: به‌صورت global، که برای همه projectهای TestRail instance شما trigger می‌شود، یا فقط برای projectهای مشخص.

برای راه‌اندازی webhook در همه projectها، به مسیر Admin > > Integration بروید.

تب Webhooks را انتخاب کنید. از اینجا می‌توانید webhook جدید اضافه کنید یا webhookهای موجود را ویرایش کنید.

برای راه‌اندازی webhook جدید، روی Add Webhook کلیک کنید. پنجره زیر باز می‌شود و در آن می‌توانید نام، Payload URL، method، content type و اطلاعات کلیدی مثل headers و payload را مشخص کنید.

• برای webhook یک نام توصیفی انتخاب کنید.
• یک Payload URL اضافه کنید: این URL مقصدی است که محتوای webhook بعد از trigger شدن به آن ارسال می‌شود.
• Method: یکی از گزینه‌های POST، GET، PUT، PATCH یا DELETE را انتخاب کنید.
• یک Content Type انتخاب کنید. گزینه‌های موجود عبارت‌اند از:
  • application/json
  • application/x-www-form-urlencoded
  • application/xml
  • text/xml
  • text/plain
• هر header اضافی را که Headers برای webhook لازم دارید، اضافه کنید. همه webhookهای TestRail چند header پیش‌فرض دارند که خاکستری نمایش داده می‌شوند؛ همچنین می‌توانید headerهای سفارشی اضافه کنید که با رنگ مشکی نمایش داده می‌شوند.
• یک Payload به webhook اضافه کنید. فیلد Payload انعطاف‌پذیر طراحی شده است تا بتوانید با استفاده از console تقریباً هر نوع payload دلخواهی را بسازید یا ارسال کنید. (برای اطلاعات بیشتر، بخش Payloads را در ادامه ببینید.)

• در صورت نیاز، می‌توانید برای webhook یک Secret برای احراز هویت تنظیم کنید. این مقدار در headers مربوط به webhook قرار می‌گیرد.
• در بخش Events ، با علامت زدن کادر سمت چپ هر گزینه، رویدادهایی را مشخص کنید که می‌خواهید webhook را اجرا کنند
  • می‌توانید چند رویداد را انتخاب کنید تا همان webhook را اجرا کنند
• در بخش Projects ، کادر مربوط به هر projectی را که می‌خواهید رویدادهای انتخاب‌شده در آن این webhook را اجرا کنند، علامت بزنید.

• در پایان، با علامت زدن (یا برداشتن علامت) کادر Active می‌توانید webhook را فعال یا غیرفعال کنید.
• وقتی آماده بودید، روی Save Settings کلیک کنید.

بعد از پیکربندی webhook، می‌توانید تنظیمات آن را با دکمه Test در سمت راست بالای پنجرهٔ Add Webhook آزمایش کنید. برای آشنایی بیشتر با تست تنظیمات webhook، اینجا را ببینید.

افزودن webhookها به projectهای مشخص #

همچنین می‌توانید از طریق صفحهٔ Edit Project ، webhookها را به projectهای مشخص اضافه کنید. به بخش Admin بروید، روی Projects در منوی نوار کناری سمت راست کلیک کنید، سپس روی آیکون مداد کلیک کنید تا به صفحهٔ Edit Project بروید. یا اگر از قبل در صفحهٔ Project Overview یک project مشخص هستید، روی Edit در گوشهٔ بالا سمت راست کلیک کنید. در صفحهٔ Edit Projects روی تب Webhooks کلیک کنید تا webhook مربوط به همان project را اضافه یا ویرایش کنید.

 

آزمایش و بررسی webhookها #

وقتی webhook جدیدی اضافه می‌کنید، بهتر است پیش از ذخیره‌کردن آن را تست کنید تا ابتدا request، payload و response را بررسی کنید. می‌توانید webhookها را هنگام پیکربندی اولیه در صفحهٔ Add Webhooks تست کنید، یا بعداً به یک webhook موجود برگردید و آن را آزمایش کنید. همچنین می‌توانید درخواست‌های قبلی ارسال‌شده توسط webhookهایی را که در تنظیمات Webhooks راه‌اندازی کرده‌اید بررسی کنید.

برای تست webhookی که قبلاً ساخته‌اید یا برای بررسی فعالیت‌های قبلی، دوباره به Integration در بخش « Admin»، سپس به تب « Webhooks » برگردید. بخش Testing را در سمت راست صفحه پیدا کنید. 

اینجا می‌توانید لاگ ارسال‌های اخیر و تاریخ آن‌ها را ببینید. روی یکی از ارسال‌های اخیر کلیک کنید تا اطلاعاتی را که در headerها و payload وب‌هوک شما آمده و مربوط به رویدادی است که آن ارسال را ایجاد کرده است، در تب « Request » بررسی کنید.

در تب « Response »، می‌توانید status code پاسخی را که TestRail از اپلیکیشن خارجی شما، یعنی دریافت‌کننده وب‌هوک، گرفته است همراه با headerها و payload پاسخ ببینید.

رویدادهای وب‌هوک #

وقتی در TestRail یک وب‌هوک تنظیم می‌کنید، می‌توانید رویدادهای مشخصی را انتخاب کنید تا وب‌هوک را فعال کنند. اینجا فهرست رویدادهایی آمده است که در حال حاضر می‌توانید برای فعال کردن وب‌هوک‌ها انتخاب کنید.

رویداد	توضیح
Test Plan ایجاد شد	اگر این رویداد را انتخاب کنید، هر بار که یک Test Plan جدید در projectهای انتخاب‌شده ایجاد شود، وب‌هوک فعال می‌شود.
Test Plan به‌روزرسانی شد	اگر این رویداد را انتخاب کنید، هر بار که Test Plan در projectهای انتخاب‌شده به‌روزرسانی شود، وب‌هوک فعال می‌شود.
ورودی Test Plan ایجاد شد	اگر این رویداد را انتخاب کنید، هر بار که یک ورودی Test Plan در projectهای انتخاب‌شده ایجاد شود، وب‌هوک فعال می‌شود.
ورودی Test Plan به‌روزرسانی شد	اگر این رویداد را انتخاب کنید، هر بار که یک ورودی Test Plan در projectهای انتخاب‌شده به‌روزرسانی شود، وب‌هوک فعال می‌شود.
Test Run ایجاد شد	اگر این رویداد را انتخاب کنید، هر بار که یک Test Run در projectهای انتخاب‌شده ایجاد شود، وب‌هوک فعال می‌شود.
Test Run به‌روزرسانی شد	اگر این رویداد را انتخاب کنید، هر بار که یک Test Run در projectهای انتخاب‌شده به‌روزرسانی شود، وب‌هوک فعال می‌شود.
Test Case ایجاد شد	اگر این رویداد را انتخاب کنید، هر بار که یک Test Case در projectهای انتخاب‌شده ایجاد شود، وب‌هوک فعال می‌شود.
Test Case به‌روزرسانی شد	اگر این رویداد را انتخاب کنید، هر بار که یک Test Case در projectهای انتخاب‌شده به‌روزرسانی شود، وب‌هوک فعال می‌شود.
Test Result ایجاد شد	اگر این رویداد را انتخاب کنید، هر بار که یک Test Result در projectهای انتخاب‌شده ایجاد شود، وب‌هوک فعال می‌شود.
Report ایجاد شد	اگر این رویداد را انتخاب کنید، هر بار که یک Report در projectهای انتخاب‌شده ایجاد شود، وب‌هوک فعال می‌شود.
Cross-Project Report ایجاد شد	اگر این رویداد را انتخاب کنید، هر بار که یک Cross-Project Report در projectهای انتخاب‌شده ایجاد شود، وب‌هوک فعال می‌شود؛ این گزینه فقط برای « پلن‌های لایسنس Enterprise » در دسترس است.
همه	اگر این گزینه را فعال کنید، هر بار که هرکدام از سناریوهای قبلی رخ دهد، webhook اجرا می‌شود.

می‌توانید برای افزودن زمینه و داده‌های بیشتر به webhook، چند متغیر به payload اضافه کنید. فهرست کامل را در ادامه ببینید.

Payloadها #

فیلد payload در کنسول webhook به شما امکان می‌دهد تقریباً هر نوع payload دلخواهی را بسازید و ارسال کنید. این نمونه‌ای از ساختار payload در قالب JSON است و نشان می‌دهد برای Slack چه کارهایی می‌توانید انجام دهید.

{
  "text": "%event_creator% created a new test case:",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*%event_creator% created a new test case:*"
      }
    },
    {
      "type": "divider"
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*<%url%|%name%>* \n Priority: %case_priority% \n Type: %case_type%"
      }
    }
  ]
}

وقتی webhook اجرا شود، نتیجه در Slack به‌صورت پیامی مشابه این نمایش داده می‌شود.

متغیرهای payload #

برای تکمیل payloadها متغیرهای مختلفی در دسترس است. متغیرهایی که در حال حاضر می‌توانید در payloadهای webhook استفاده کنید عبارت‌اند از:

متغیر	نوع	توضیحات
%assigned_to%	متن	برای نام کاربری استفاده می‌شود که entity به او اختصاص داده شده است.
%case_priority%	متن	هنگام اجرای payload مربوط به رویداد test case، برای وضعیت فیلد اولویت test case استفاده می‌شود؛ برای مثال «High»، «Medium» یا «Low».
%case_type%	متن	اگر مشخص شده باشد، برای نوع test caseای استفاده می‌شود که payload رویداد برای آن اجرا شده است؛ مانند «Functional»، «Smoke»، «Regression» و موارد مشابه.
%completed_on%	timestamp	برای timestamp تکمیل milestone، plan یا run استفاده می‌شود؛ یعنی زمانی که به‌عنوان «closed» علامت‌گذاری شده است.
%config%	متن	برای نام config مربوط به entity استفاده می‌شود. فقط برای ورودی‌های test plan کاربرد دارد.
%custom_x%	object/array	وقتی رویداد مربوط به test case اجرا می‌شود، برای برگرداندن همه فیلدهای سفارشی test case که نامشان با «custom_» شروع می‌شود استفاده می‌شود؛ یعنی «x» را با نام فیلد سفارشی جایگزین کنید. برای مثال، اگر فیلد سفارشی‌ای با نام «Version number» ساخته باشید، متغیر باید به‌شکل %custom_version_number% باشد.
%description%	متن	برای توضیحات entityای استفاده می‌شود که رویداد آن باعث اجرای payload وب‌هوک می‌شود؛ برای مثال توضیحات milestone یا توضیحات test run.
%due_on%	timestamp	برای تاریخی استفاده می‌شود که انتظار می‌رود یک milestone در آن تکمیل شود. فقط برای milestoneها کاربرد دارد.
%entity_created%	timestamp	برای زمانی استفاده می‌شود که entity مربوط به رویداد ایجاد شده است.
%entity_creator%	متن	برای نام کاربری استفاده می‌شود که entity مربوط به رویداد را ایجاد کرده است؛ برای مثال نام کاربری که test case را در ابتدا ساخته است.
%estimate%	عدد صحیح	برای فیلد estimate در یک test case استفاده می‌شود، زمانی که payload وب‌هوک مربوط به رویداد یک test case ارسال می‌شود.
%event_created%	timestamp	برای مشخص کردن زمانی استفاده می‌شود که رویداد وب‌هوک رخ داده است.
%event_creator%	متن	برای نام کاربری استفاده می‌شود که رویداد وب‌هوک را ایجاد و trigger کرده است.
%event_type%	متن	برای نوع رویدادی استفاده می‌شود که payload وب‌هوک را trigger کرده است؛ مثلاً «Plan created»، «Case updated»، «Report created» و موارد مشابه.
%id%	عدد صحیح	برای ID موجودیتی استفاده می‌شود که رویداد مربوط به آن، payload وب‌هوک را trigger می‌کند؛ مثلاً «۱۱۷» در label شناسه case یعنی «C117»، یا «۴۲» در label شناسه run یعنی «R42».
%is_deleted%	boolean	برای مشخص کردن این‌که case، run، plan یا milestone به‌عنوان حذف‌شده علامت‌گذاری شده است یا نه استفاده می‌شود.
%milestone_id%	عدد صحیح	اگر موجودیت به milestoneای مرتبط باشد، برای ID منحصربه‌فرد آن milestone استفاده می‌شود.
%more_info%	متن	برای API endpointی استفاده می‌شود که می‌توان آن را فراخوانی کرد تا اطلاعات بیشتری درباره موجودیتی که رویداد برای آن trigger شده است به دست آورد؛ مثلاً «/api/v2/get_runs/۳».
%name%	متن	برای نام یا عنوان موجودیتی استفاده می‌شود که رویداد مربوط به آن، payload وب‌هوک را trigger می‌کند.
%project_id%	عدد صحیح	برای project در TestRail استفاده می‌شود که این موجودیت به آن مربوط است.
%project_ids%	فهرستی از اعداد صحیح	اگر گزینه «Cross-Project Report created» انتخاب شده باشد، این مقدارها همان projectهای انتخاب‌شده در report هستند؛ در دسترس برای پلن‌های لایسنس Enterprise فقط.
%refs%	متن	برای هر اطلاعاتی استفاده می‌شود که در فیلد references موجودیت وب‌هوک ذخیره شده است؛ مثلاً «TR-۷۱, TR-۷۲».
%section_id%	عدد صحیح	برای شناسایی section مرتبط با یک test case استفاده می‌شود.
%stats%	object/array	برای مجموعه کامل معیارهای نتایج تست مربوط به plan، test run یا milestone استفاده می‌شود (passed_count، blocked_count، untested_count، retest_count، failed_count، custom_status_n_count).
%suite_id%	عدد صحیح	برای شناسایی test suite مرتبط با اشتراک موجودیت webhook استفاده می‌شود.
%template_name%	متن	برای template مربوط به test case استفاده می‌شود؛ همان templateای که هنگام فعال شدن payload وب‌هوک برای یک رویداد test case به‌کار می‌رود (مانند «Test Case Steps» یا «Exploratory Session»).
%url%	متن	برای URL نمونه‌ای استفاده می‌شود که از طریق آن می‌توان موجودیت را در TestRail مشاهده کرد (مثلاً: «https://allboard.testrail.com/index.php?/milestones/view/۶۱»).
%secret%	متن	برای token واردشده در فیلد Secret وب‌هوک استفاده می‌شود، اگر چنین tokenای وجود داشته باشد.

می‌توانید متغیرها را به فیلد payload اضافه کنید تا هنگام فعال شدن webhook، با داده‌های متناظر TestRail پر شوند؛ مانند تصویر زیر.

نصب on-premise (TestRail Server) #

نصب نسخه TestRail Server در TestRail ۷.۵ شامل چند مرحله اضافی و اختیاری است که مستقیماً به قابلیت‌های جدید webhooks مربوط می‌شود. هنگام نصب یا ارتقا، یک مرحله اضافی نمایش داده می‌شود که در آن می‌توانید یک سرور message queue از نوع RabbitMQ را برای مدیریت payloadهای خروجی webhook پیکربندی کنید.

اگر تصمیم دارید برای این منظور از message queue استفاده کنید، هنگام نصب یا ارتقای TestRail Server باید موارد زیر را اضافه کنید:

• نام سرور RabbitMQ
• شماره پورت RabbitMQ (به‌طور پیش‌فرض ۵۶۷۲)
• username و password مربوط به RabbitMQ
• و در صورت نیاز، certificate و private key مربوط به RabbitMQ

تنظیمات message queue را می‌توانید در مسیر زیر هم پیدا کنید و آن‌ها را اضافه یا به‌روزرسانی کنید: Admin > Site Settings console.