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

فرم گزارش معمولاً به دو بخش تقسیم می شود. بخش اول به اصطلاح گزینه های سفارشی را برای گزارش پیکربندی می کند و این بخش برای هر افزونه گزارش متفاوت به نظر می رسد. بخش دوم گزینه های سیستم (دسترسی، اعلان ها و زمان بندی) را تعریف می کند و برای همه افزونه های گزارش یکسان است. این قسمت نحوه پر کردن فرم گزارش و نحوه استفاده از این گزینه ها برای سفارشی کردن گزارش های تولید شده را توضیح می دهد.

گزینه های فرم #

همه افزونه های گزارش داخلی در TestRail بسیار قابل تنظیم هستند و اغلب می توانید محدوده، طرح و سطح جزئیات را برای گنجاندن در گزارش های تولید شده پیکربندی کنید. یک ایده خوب برای ساختاربندی و گروه بندی گزینه های مختلف استفاده از کنترل برگه است و این معمولاً اولین گام هنگام طراحی یک فرم گزارش جدید است:

<div class="tabs">
  <div class="tab-header">
    <a href="javascript:void(0)" class="tab1 current" rel="1"
      onclick="App.Tabs.activate(this)">
        <?= lang('reports_tpr_form_details') ?></a>
    <a href="javascript:void(0)" class="tab2" rel="2"
      onclick="App.Tabs.activate(this)">
        <?= lang('reports_tpr_form_runs') ?></a>
  </div>
  <div class="tab-body tab-frame">
    <div class="tab tab1">
      <!-- The content of tab 1 goes here -->
    </div>
    <div class="tab tab2 hidden">
      <!-- The content of tab 2 goes here -->
    </div>
  </div>
</div>

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

برای این کار برمی گردیم به گزارش.php و توابع مربوط به فرم را پر کنید. ما شروع می کنیم prepare_form که فرم را آماده می کند و گزینه های ما را ثبت می کند:

public function prepare_form($context, $validation)
{
  // Assign the validation rules for the fields on the form.
  $validation->add_rules(
    array(
      'custom_types_include' => array(
        'type' => 'bool',
        'default' => false
      ),
      'custom_priorities_include' => array(
        'type' => 'bool',
        'default' => false
      )
    )
  );
 
  if (request::is_post())
  {
    return;
  }
 
  // We assign the default values for the form depending on the
  // event. For 'add', we use the default values of this plugin.
  // For 'edit/rerun', we use the previously saved values of
  // the report/report job to initialize the form. Please note
  // that we prefix all fields in the form with 'custom_' and
  // that the storage format omits this prefix (validate_form).
 
  if ($context['event'] == 'add')
  {
    $defaults = array(
      'types_include' => true,
      'priorities_include' => true
    );
  }
  else
  {
    $defaults = $context['custom_options'];
  }
 
  foreach ($defaults as $field => $value)
  {
    $validation->set_default('custom_' . $field, $value);
  }
}

این تابع دو کار را انجام می دهد. اولین گام این است که قوانین اعتبارسنجی را برای گزینه ها با استفاده از تصویب تنظیم کنید $validation شی و دوم این است که مقادیر پیش فرض را برای این گزینه ها تنظیم کنید. توجه داشته باشید که چگونه از آن استفاده می کنیم $context پارامتری برای تصمیم گیری در مورد اینکه آیا ما یک گزارش جدید اضافه می کنیم یا یک گزارش موجود را ویرایش/اجرا مجدد می کنیم و چگونه مدیریت مقادیر پیش فرض بین این دو انتخاب متفاوت است.

سپس می توانیم با پر کردن ادامه دهیم validate_form برای تایید/برگرداندن گزینه ها:

public function validate_form($context, $input, $validation)
{
  // At least one detail entity option must be selected (types or
  // priorities).
  if (!$input['custom_types_include'] &&
    !$input['custom_priorities_include'])
  {
    $validation->add_error(
      lang('reports_tpr_form_details_include_required')
    );
 
    return false;
  }
 
  $values = array();
 
  static $fields = array(
    'types_include',
    'priorities_include'
  );
 
  foreach ($fields as $field)
  {
    $key = 'custom_' . $field;
    $values[$field] = arr::get($input, $key);
  }
 
  return $values;
}

سناریوهای اعتبارسنجی ساده قبلاً توسط قوانین اعتبار سنجی تنظیم شده پوشش داده شده اند prepare_form و validate_form می تواند برای رسیدگی به سناریوهای پیچیده تر استفاده شود. به عنوان مثال، ما در اینجا از این استفاده می کنیم تا بررسی کنیم که حداقل یک موجودیت در فرم (انواع یا اولویت ها) انتخاب شده است. سپس گزینه های گزارش را همانطور که باید برای مرحله رندر ذخیره شوند، برمی گردانیم.

سپس به آن برمی گردیم form.php دوباره می توانید کد مربوطه را به فرم اضافه کنید:

..
<!-- The content of tab 1 goes here -->
<p class="top"><?= lang('reports_tpr_form_details_include') ?></p>
<div class="checkbox form-checkbox" style="margin-left: 15px">
  <label>
    <?= lang('reports_tpr_form_details_include_types') ?>
    <input type="checkbox" id="custom_types_include"
      name="custom_types_include" value="1"
      <?= validation::get_checked('custom_types_include',1) ?> />
  </label>
</div>
<div class="checkbox" style="margin-left: 15px">
  <label>
    <?= lang('reports_tpr_form_details_include_priorities') ?>
    <input type="checkbox" id="custom_priorities_include"
      name="custom_priorities_include" value="1"
      <?= validation::get_checked('custom_priorities_include',1) ?> />
  </label>
</div>
..

کنترل های فرم #

در حالی که ساختن فرم‌های پیچیده حتی با رویکرد گزینه‌های سفارشی امکان‌پذیر است، بسیاری از افزونه‌های گزارش گزینه‌های یکسانی را به اشتراک می‌گذارند و اجرای مکرر آن گزینه‌ها منطقی نیست. خوشبختانه، موتور گزارش‌دهی TestRail دارای ویژگی به نام «کنترل‌های فرم» است که گزینه‌های رایج را پیاده‌سازی می‌کند و از افزونه‌های گزارش داخلی و همچنین سفارشی قابل استفاده مجدد است. کنترل هایی برای انتخاب مجموعه ای از وضعیت ها، کاربران، مجموعه های آزمایشی، اجراهای آزمایشی و موارد دیگر وجود دارد.

این بخش نحوه استفاده از کنترل‌های فرم را برای پیکربندی «حوزه» افزونه گزارش توضیح می‌دهد. در مورد ما، ما به scope به عنوان اجرای تست که بخشی از گزارش‌های تولید شده است اشاره می‌کنیم و از کنترل‌های فرم انتخاب و اجرای حد برای این کار استفاده می‌کنیم. ما به سادگی به گزارش.php و کد زیر را اضافه یا تغییر دهید:

class Tests_property_results_report_plugin extends Report_plugin
{
  private $_controls;
 
  // The controls and options for those controls that are used on
  // the form of this report.
  private static $_control_schema = array(
    'runs_select' => array(
      'namespace' => 'custom_runs',
      'multiple_suites' => true
    ),
    'runs_limit' => array(
      'type' => 'limits_select',
      'namespace' => 'custom_runs',
      'min' => 0,
      'max' => 100,
      'default' => 25
    )
  );
 
  ..
 
  public function __construct()
  {
    parent::__construct();
    $this->_controls = $this->create_controls(
      self::$_control_schema
    );
  }
 
  public function prepare_form($context, $validation)
  {
    // Assign the validation rules for the controls used on the
    // form.
    $this->prepare_controls($this->_controls, $context, 
      $validation);
 
    ..
  }
 
  public function validate_form($context, $input, $validation)
  {
    ..
 
    // We begin with validating the controls used on the form.
    $values = $this->validate_controls(
      $this->_controls,
      $context,
      $input,
      $validation);
 
    if (!$values)
    {
      return false;
    }
 
    ..
  }
 
  public function render_form($context)
  {
    $params = array(
      'controls' => $this->_controls,
      'project' => $context['project']
    );
 
    ..
  }
}

ما اساساً کنترل ها را در سازنده خود بر اساس طرحواره تعریف شده ایجاد می کنیم، کنترل های خود را در آن ثبت می کنیم prepare_form و آنها را تأیید کنید validate_form. ما همچنین مطمئن می شویم که کنترل ها را به نمای فرم منتقل می کنیم. اکنون تنها کاری که باید انجام دهید این است که کد فرانت اند مربوطه را در آن جاسازی کنید form.php:

//The content of tab 2 goes here
$report_obj->render_control(
  $controls,
  'runs_select',
  array(
    'top' => true,
    'project' => $project
  )
)

$report_obj->render_control(
  $controls,
  'runs_limit',
  array(
    'intro' => lang('report_plugins_runs_limit'),
    'limits' => array(5, 10, 25, 50, 100, 0)
  )
)

حالا وقتی به مجموعه های تست & اجرا می شود برگه در فرم گزارش ما، باید چیزی شبیه به زیر را ببینید:

توجه داشته باشید که با افزودن پشتیبانی کنترل به متدهای فرم در گزارش.php، اکنون مقادیر کنترل انتخاب شده به طور خودکار در گزینه های گزارش ذخیره می شوند و از طریق استاندارد در دسترس قرار می گیرند $options پارامتر هنگام ارائه گزارش این در بخش بعدی نشان داده خواهد شد.

گزارش کمکی #

مشابه کنترل‌های فرم، موتور گزارش‌دهی TestRail همچنین دسترسی به پرس‌وجوهای رایج مرتبط با پایگاه داده را برای خواندن داده‌های واقعی از پایگاه داده فراهم می‌کند. این پرس‌وجوها از طریق روش‌های شی موجود در یک به اصطلاح «راهنمای گزارش» در دسترس قرار می‌گیرند. این کمک کننده از طریق قابل دسترسی است $this→_helper در گزارش.php و $report_helper در نماهای گزارش

بسیاری از عملکردهای این کمک کننده برای استفاده در ارتباط با کنترل های فرم طراحی شده اند و این در مثال زیر روشن خواهد شد. اکنون به رندر واقعی گزارش می رویم (run روش) و محدوده گزارش را تنظیم کنید:

public function run($context, $options)
{
  $project = $context['project'];
 
  // Read the test suites first.
  $suites = $this->_helper->get_suites_by_include(
    $project->id,
    $options['runs_suites_ids'],
    $options['runs_suites_include']
  );
 
  $suite_ids = obj::get_ids($suites);
 
  // We then get the actual list of test runs used, depending on
  // the report options.
  if ($suite_ids)
  {
    $runs = $this->_helper->get_runs_by_include(
      $project->id,
      $suite_ids,
      $options['runs_include'],
      $options['runs_ids'],
      $options['runs_filters'],
      null, // Active and completed
      $options['runs_limit'],
      $run_rels,
      $run_count
    );
  }
  else
  {
    $runs = array();
    $run_rels = array();
    $run_count = 0;
  }
 
  $run_ids = obj::get_ids($runs);
 
  ..
}

این از گزینه های کنترل های فرم (بخشی از $options پارامتر) برای خواندن مجموعه های تست مربوطه و اجرا برای گزارش از پایگاه داده. راهنمای گزارش بسیاری از روش‌های اضافی را ارائه می‌کند و توصیه می‌شود برای یک نمای کلی، به کد منبع افزونه‌های گزارش داخلی در app/plugins/reports نگاهی بیندازید.

مراحل بعدی #

در بخش آخر بخوانید و یاد بگیرید که چگونه مستقیماً برای جستجوهای سفارشی به پایگاه داده دسترسی داشته باشید و چگونه داده های خود را ارائه دهید:

• ساخت پلاگین گزارش سفارشی (۳)