گزارش ها: ساخت یک افزونه گزارش سفارشی (۱/۳)

همانطور که قبلاً در سفارشی گزارش می دهد معرفیحراج، گزارش‌ها به زبان PHP توسعه داده می‌شوند و زمانی که پلاگین گزارش خود را سفارشی می‌کنید یا می‌سازید، باید درک اولیه PHP داشته باشید.

لطفا خودتان را با اصطلاحات مرتبط و ساختار اصلی پلاگین های گزارش را گزارش دهید در صورتی که قبلا این کار را نکرده اید

این آموزش شما را در ایجاد یک نمونه پلاگین گزارش سفارشی کاملاً کارآمد راهنمایی می کند. هدف این افزونه گزارش، تولید گزارش‌هایی است که توزیع نتایج را برای انواع تست‌کیس‌ها و اولویت‌ها برای یک محدوده قابل تنظیم (مثلاً یک نقطه عطف یا طرح/اجرای آزمایش) نمایش می‌دهد. کد منبع کامل نیز در GitHub موجود است:

ایجاد دایرکتوری و فایل های اولیه #

اولین قدم ایجاد دایرکتوری جدید برای افزونه گزارش و فایل های اولیه است.

یک نام خوب برای افزونه های گزارش شامل موجودیت اصلی و همچنین هدف گزارش ها می شود. قرارداد نامگذاری این است که با موجودیت (“آزمون ها”) شروع شود و سپس شرح کوتاهی از آنچه در مورد گزارش ها هستند اضافه شود (به عنوان مثال “property_results”).

سپس با ساختار دایرکتوری زیر شروع می کنیم:

tests_property_results/
tests_property_results/about.json
tests_property_results/i18n/
tests_property_results/i18n/translations/
tests_property_results/i18n/translations/en/reports_tpr.php
tests_property_results/report.php

به یاد بیاورید که about.json فایل توضیحات پلاگین گزارش ما است و آن report.php شامل کلاس پیاده سازی مبتنی بر PHP است. فهرست i18n حاوی فایل ترجمه است.

about.json #

فایل توضیحات ساده است و برای تعریف برچسب (نام)، توضیحات و غیره و همچنین فایل ترجمه استفاده می شود:

{
  "author": "Gurock Software",
  "version": 1,
  "label": "l:reports_tpr_meta_label",
  "summary": "l:reports_tpr_meta_summary",
  "description": "l:reports_tpr_meta_description",
  "group": "l:reports_tpr_meta_group",
  "translations": ["reports_tpr"]
}

Reports_tpr.php #

فایل ترجمه با رشته های اولیه ارجاع شده در فایل توضیحات تنظیم می شود و این نشان می دهد که چگونه افزونه گزارش در نوار کناری ناحیه گزارش ها در TestRail ظاهر می شود:

$lang['reports_tpr_meta_label'] = 'Property Results';
$lang['reports_tpr_meta_group'] = 'Samples';
$lang['reports_tpr_meta_summary'] = 'Demonstrates how to develop \
    custom report plugins.';
$lang['reports_tpr_meta_description'] = 'Demonstrates how to develop \
    custom report plugins and serves as a reference for \
    new report plugins.';

نام فایل ترجمه باید با نام افزونه گزارش مرتبط باشد (tests_property_results → tpr) تا خطر تداخل نام‌گذاری با سایر افزونه‌های گزارش به حداقل برسد.

Report.php #

Report.php شامل پیاده‌سازی واقعی افزونه گزارش است و شامل تمام روش‌های ارائه و اعتبارسنجی گزینه‌های گزارش و همچنین ارائه گزارش‌های واقعی است. یک طرح کلی به شکل زیر است (با نظرات اضافی که معمولا حذف می شوند):

class Tests_property_results_report_plugin extends Report_plugin
{
  public function render_form($context)
  {
    ..
  }
 
  /**
   * Run
   *
   * Expected to generate the static HTML page for the report. Is
   * passed the previously configured report parameters (custom
   * options). Is expected to return an array with the following
   * keys:
   *
   * html:        The HTML content as string (should only be used
   *              for smaller reports or during development).
   * html_file:   The path of the static HTML file as string. This
   *              is an alternative and the recommended way to
   *              return the HTML. This should point to a temporary
   *              file which is automatically deleted by TestRail
   *              after 'run' was executed.
   * resources:   Array of resource files to copy to the output
   *              directories (optional).
   */
  public function run($context, $options)
  {
    ..
  }
  
  ..
}

TestRail انتظار دارد کلاسی با نام دایرکتوری افزونه گزارش و به دنبال آن “_report_plugin” باشد. همچنین باید از کلاس پلاگین گزارش پایه با نام “Report_plugin” استخراج کنید.

زمینه #

به جز سازنده، به هر متد یک پارامتر $context ارسال می‌شود که شامل جزئیاتی در مورد زمینه یا محیطی است که افزونه گزارش در آن اجرا می‌شود. برای مثال، این شامل پروژه فعلی و گزینه‌های مرتبط (مانند طرح‌های فیلد سفارشی) می‌شود.

فرم ها #

TestRail از هر افزونه گزارش یک فرم انتظار دارد و قدم بعدی تنظیم یک فرم خالی بسیار ابتدایی است. برای انجام این کار، می‌توانیم فعلاًprede_form و validate_form را نادیده بگیریم و تمرکز خود را روی render_form قرار دهیم:

public function render_form($context)
{
  $params = array(
    'project' => $context['project']
  );
 
  return array(
    'form' => $this->render_view(
      'form',
      $params,
      true
    )
  );
}

این اساساً یک نمای به نام (به نام “فرم”) ارائه می دهد و نتیجه را به TestRail برمی گرداند. View ها فایل های ساده PHP هستند که وظیفه تولید فایل های HTML ایستا را بر عهده دارند. آنها را می توان پارامترهایی ارسال کرد که سپس در محیط زمان اجرا view در دسترس هستند. نماها باید در دایرکتوری فرعی “views” پلاگین های گزارش قرار داده شوند و فعلاً می توانیم form.php را خالی بگذاریم:

tests_property_results/views/
tests_property_results/views/form.php

می‌توانیم فرم را مستقیماً به عنوان رشته برگردانیم یا از یک نتیجه پیچیده‌تر در قالب یک آرایه استفاده کنیم. ما دومی را برای آمادگی برای تغییرات آتی در این مقاله انتخاب کردیم.

ارائه گزارش ها #

گزارش ها قرار است با “اجرا” ارائه شوند. انتظار می رود این روش HTML ایستا را به همراه فهرستی از منابعی که گزارش به آنها ارجاع می دهد، ارائه و برگرداند. یک پیاده سازی حداقل به صورت زیر به نظر می رسد:

class Tests_property_results_report_plugin extends Report_plugin
{
  // The resources (files) to copy to the output directory when
  // generating a report.
  private static $_resources = array(
    'js/jquery.js',
    'styles/print.css',
    'styles/reset.css',
    'styles/view.css'
  );
 
  ..
 
  public function run($context, $options)
  {
    $project = $context['project'];
 
    // Render the report to a temporary file and return the path
    // to TestRail (including additional resources that need to be
    // copied).
    return array(
      'resources' => self::$_resources,
      'html_file' => $this->render_page(
        'index',
        array(
          'report' => $context['report'],
          'project' => $project
        )
      )
    );
  }
}

این معمولاً پیچیده ترین روش یک افزونه گزارش و مکانی است که همه بیت ها در کنار هم قرار می گیرند. این متد گزینه های متن و گزارش ذکر شده قبلی را از TestRail دریافت می کند و معمولاً کارهای زیر را انجام می دهد:

1. محدوده گزارش را بررسی و تنظیم می کند
2. داده هایی را که می خواهد ارائه دهد محاسبه می کند
3. این داده ها را به یک View ارسال می کند و HTML ایستا را برمی گرداند

در حال حاضر، ما فقط یک نمای حداقلی (به نام “index”) ارائه می دهیم و نتیجه را به TestRail برمی گردانیم (مشابه render_form قبلی). همچنین فهرستی از منابع را برای کپی در فهرست خروجی گزارش برمی گرداند. نمای به صورت زیر است:

$min_width = 960;
 
$header = array(
  'project' => $project,
  'report' => $report,
  'meta' => $report_obj->get_meta(),
  'min_width' => $min_width,
  'css' => array(
    'styles/reset.css' => 'all',
    'styles/view.css' => 'all',
    'styles/print.css' => 'print'
  ),
  'js' => array(
    'js/jquery.js'
  )
);
 
$GI->load->view('report_plugins/layout/header', $header);
?>
 
The report content goes here. 
 
$temp = array();
$temp['report'] = $report;
$temp['meta'] = $report_obj->get_meta();
$temp['show_options'] = true;
$temp['show_report'] = true;
$GI->load->view('report_plugins/layout/footer', $temp);

$GI سوپر شی در TestRail است و در هر نما قابل دسترسی است. روش هایی برای بارگیری نماهای فرعی ارائه می دهد و ما از آن برای استفاده مجدد از نماهای استاندارد TestRail برای سرصفحه ها و پاورقی های گزارش استفاده می کنیم.

حالت را توسعه دهید #

گام بعدی آزمایش پلاگین گزارش ما برای اولین بار خواهد بود. برای انجام این کار، معمولاً به تب Reports در TestRail رفته، افزونه گزارش را انتخاب کرده و دکمه Add Report را در پایین صفحه فشار دهید. سپس باید منتظر بمانید تا کار پس‌زمینه گزارش را ایجاد کند و سپس بتوانید گزارش را مشاهده کنید. در حالی که این گردش کار برای یک کاربر معمولی TestRail خوب است، زمانی که افزونه های گزارش جدید را توسعه، آزمایش و اشکال زدایی می کنید، کمی دشوار است. خوشبختانه TestRail یک حالت توسعه ویژه برای گزارش ها دارد که این فرآیند را بسیار ساده تر می کند.

برای فعال کردن این حالت، لطفاً گزینه زیر را به فایل config.php TestRail اضافه کنید:

define('DEPLOY_DEVELOP_REPORT', true);

پس از فعال شدن، باید دکمه جدید «افزودن و مشاهده گزارش» زیر را در فرم گزارش مشاهده کنید:

این دکمه به TestRail می‌گوید که بلافاصله گزارش را تولید کند و پردازش پس‌زمینه معمول را دور بزند. شما همچنین به طور خودکار به صفحه خاصی هدایت می شوید که پس از در دسترس بودن گزارش، آن را نمایش می دهد. بهترین چیز در مورد حالت توسعه این است که شما می توانید این صفحه را در هر زمان به روز کنید و TestRail سپس گزارش را برای شما بازسازی می کند.

در حال اجراست! #

هنگامی که حالت توسعه را فعال کردید، می توانید یک گزارش جدید اضافه کنید و باید صفحه زیر را ببینید: