カスタム レポート プラグインの作成 (1/3)

カスタム レポート:はじめにで述べたように 、レポートは PHP で開発されているため、独自のレポート プラグインをカスタマイズまたは作成する場合、PHP についての基本的な知識が必要です。

レポート関連の用語およびレポートプラグインの基本構造をまだよく理解していない場合は、先にそちらを参照してください。

このチュートリアルでは、完全に機能するサンプル カスタム レポート プラグインを作成する方法を詳しく説明します。このレポート プラグインの目的は、設定されたスコープ (マイルストーンやテスト計画/ランなど) でのテスト ケースのタイプおよび優先順位ごとの結果分布を表示するレポートを生成することです。完全なソースコードは GitHub でも入手できます。

ディレクトリと初期ファイルの作成

最初に、レポート プラグイン用の新しいディレクトリと初期ファイルを作成します。

レポート プラグインの名前には、レポートの目的や主要なエンティティを含めるのが適切です。命名規則として、エンティティ (たとえば “tests”) を先頭に置き、レポートの内容を表す簡単な説明を追加します (“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 の Reports エリアのサイドバーにレポート プラグインがどのように表示されるかを定義します。

$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” という名前のレポート プラグインの基底クラスから派生する必要があります。

コンテキスト

コンストラクターを除いて、report.php の各メソッドには、レポートプラグインが実行されているコンテキストまたは環境に関する詳細を含む $context パラメーターが渡されます。たとえば、これには現在のプロジェクトおよび関連オプション (カスタム フィールドのスキームなど) が含まれます。

フォーム

TestRail では、すべてのレポート プラグインにフォームが必要です。次のステップでは、非常に基本的な空のフォームを設定します。ここでは、report.php の 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
    )
  );
}

render_form は、「フォーム」と呼ばれるビューをレンダリングし、その結果を TestRail に返します。ビューは、静的 HTML ファイルの生成を担当する単純な PHP ファイルです。ビューにはパラメーターを渡すことができ、渡されたパラメーターはビューのランタイム環境で利用できます。ビューはレポートプラグインの “views” サブディレクトリに置く必要があります。今回は form.php は空のままにしておきます。

tests_property_results/views/
tests_property_results/views/form.php

フォームを文字列として直接返すことも、配列の形でより複雑な結果を使用することもできます。ここでは、将来の変更に備えて後者を選択します。

レポートのレンダリング

レポートは “run” によってレンダリングされます。このメソッドは、静的 HTMLをレンダリングしてレポートが参照するリソースのリストと共に返すことが期待されています。report.php の 最小限の実装は次のようになります。

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. 1. レポートのスコープを確認してセット アップします
   2. レンダリング対象のデータを計算します
   3. データをビューに渡して静的 HTML を返します

今回は、render_form と同様に、最低限のビュー (“index”) をレンダリングし、その結果を TestRail に返します。また、レポート出力ディレクトリにコピーするリソースのリストも返します。ビュー (index.php) は次のようになります。

$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 の標準ビューを表示します。

開発モード

次に、レポート プラグインのテストを開始します。それには、通常、TestRail の [レポート] タブに移動し、レポート プラグインを選択してページ下部の [レポートの追加] ボタンをクリックします。その後、バックグラウンド タスクがレポートを生成してレポートを表示できるようになるまで待ちます。このワークフローは通常の TestRail ユーザーには問題ありませんが、新しいレポート プラグインを開発、テスト、デバッグするときには少し面倒です。幸いなことに、TestRail にはこのプロセスを容易にする、特別なレポート開発モードがあります。

このモードを有効にするには、TestRail の config.php ファイルに次のオプションを追加します。

define('DEPLOY_DEVELOP_REPORT', true);

開発モードを有効にすると、レポート フォームに次のように [レポートの追加と表示] ボタンが表示されます。

このボタンをクリックすると、TestRail は通常のバックグラウンド処理を回避してただちにレポートを生成します。レポートが利用可能になると、レポートを表示する特別なページに自動的にリダイレクトされます。開発モードの最も便利な点は、いつでもこのページを更新して、レポートを再生成できることです。

実行

開発モードを有効にしたら、新しいレポートを追加できます。次のページが表示されます。

次のステップ

次のパートで、レポート フォームへの入力方法と、これらのオプションを使用してレポートの生成をカスタマイズする方法について学びます。

• • カスタム レポート プラグインの作成 (2)