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

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

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

این آموزش شما را مرحله‌به‌مرحله با ساخت یک نمونه report plugin سفارشی و کاملاً قابل اجرا آشنا می‌کند. هدف این report plugin تولید گزارش‌هایی است که توزیع نتایج را بر اساس نوع test case و اولویت، برای یک محدوده قابل تنظیم نمایش می‌دهند؛ برای مثال یک milestone یا test plan/run. کد منبع کامل نیز در GitHub در دسترس است:

ایجاد directory و فایل‌های اولیه #

اولین قدم، ایجاد directory جدید برای report plugin و فایل‌های اولیه آن است.

نام مناسب برای report plugin باید هم موجودیت اصلی و هم هدف گزارش‌ها را نشان دهد. قاعده نام‌گذاری این است که نام را با موجودیت شروع کنید («tests») و سپس توضیح کوتاهی درباره موضوع گزارش‌ها اضافه کنید؛ برای مثال «property_results».

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

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 plugin ماست و report.php شامل کلاس پیاده‌سازی مبتنی بر PHP است. directory با نام i18n فایل ترجمه را در خود دارد.

about.json #

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

{
  "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 #

فایل ترجمه با رشته‌های اولیه‌ای تنظیم می‌شود که در فایل توضیحات به آن‌ها ارجاع داده شده است. این فایل مشخص می‌کند report plugin در sidebar بخش Reports در 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.';

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

Report.php #

Report.php پیاده‌سازی اصلی report plugin را در خود دارد و شامل همه methodهایی است که گزینه‌های گزارش را نمایش و اعتبارسنجی می‌کنند و خود گزارش‌ها را رندر می‌کنند. یک ساختار معمول به شکل زیر است؛ همراه با چند comment اضافی که معمولاً حذف می‌شوند:

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 انتظار دارد کلاسی داشته باشید که نام آن از نام directory مربوط به report plugin، به‌اضافه «_report_plugin» ساخته شده باشد. همچنین باید این کلاس را از کلاس پایه report plugin با نام «Report_plugin» مشتق کنید.

Context #

به‌جز constructor، به هر method یک پارامتر $context داده می‌شود که جزئیاتی درباره context یا محیط اجرای report plugin دارد. برای مثال، این اطلاعات شامل project فعلی و گزینه‌های مرتبط با آن، مانند custom field schemeها، می‌شود.

Forms #

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

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

این کد در اصل یک view به نام «form» را رندر می‌کند و نتیجه را به TestRail برمی‌گرداند. viewها فایل‌های ساده PHP هستند که مسئول تولید HTML ثابت‌اند. می‌توان به آن‌ها پارامتر داد و این پارامترها در محیط اجرای view در دسترس خواهند بود. viewها باید داخل زیرشاخه «views» مربوط به report pluginها قرار بگیرند و فعلاً می‌توانیم form.php را خالی بگذاریم:

tests_property_results/views/
tests_property_results/views/form.php

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

رندر کردن گزارش‌ها #

گزارش‌ها باید با «run» رندر شوند. انتظار می‌رود این method، HTML ثابت را همراه با فهرستی از resourceهایی که گزارش به آن‌ها ارجاع می‌دهد رندر کند و برگرداند. یک پیاده‌سازی حداقلی به شکل زیر است:

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
        )
      )
    );
  }
}

این معمولاً پیچیده‌ترین method در یک report plugin است؛ همان جایی که همه بخش‌ها کنار هم قرار می‌گیرند. این method، context و گزینه‌های گزارشی را که قبلاً توضیح دادیم از TestRail دریافت می‌کند و معمولاً کارهای زیر را انجام می‌دهد:

1. محدوده گزارش را بررسی و تنظیم می‌کند
2. داده‌هایی را که می‌خواهد نمایش دهد محاسبه می‌کند
3. این داده‌ها را به یک view می‌فرستد و HTML ثابت را برمی‌گرداند

فعلاً فقط یک view ساده به نام «index» را render می‌کنیم و نتیجه را به TestRail برمی‌گردانیم؛ مشابه کاری که قبلاً با render_form انجام دادیم. این بخش همچنین فهرستی از resourceهایی را برمی‌گرداند که باید در پوشه خروجی گزارش کپی شوند. این view به شکل زیر است:

$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 شیء اصلی یا super object در TestRail است و در همه viewها در دسترس قرار دارد. این شیء methodهایی برای بارگذاری sub-viewها فراهم می‌کند و ما از آن استفاده می‌کنیم تا viewهای استاندارد TestRail برای header و footer گزارش را دوباره به‌کار ببریم.

حالت develop #

مرحله بعد این است که report plugin خودمان را برای اولین بار تست کنیم. برای این کار معمولاً در TestRail به تب Reports می‌روید، report plugin را انتخاب می‌کنید و دکمه Add Report را در پایین صفحه می‌زنید. بعد باید صبر کنید تا task پس‌زمینه گزارش را بسازد و سپس بتوانید گزارش را ببینید. این workflow برای یک کاربر عادی TestRail مناسب است، اما وقتی در حال توسعه، تست و debug کردن report pluginهای جدید هستید، کمی دست‌وپاگیر می‌شود. خوشبختانه TestRail برای گزارش‌ها یک حالت develop مخصوص دارد که این فرایند را بسیار ساده‌تر می‌کند.

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

define('DEPLOY_DEVELOP_REPORT', true);

بعد از فعال‌سازی، باید دکمه جدید «Add and View Report» را در فرم گزارش ببینید:

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

اجرای گزارش #

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