カスタムレポート：はじめに

TestRail 3.0 でレポート エリアが追加され、レポートの生成、スケジューリング、共有、および電子メール送信をサポートするようになりました。TestRail には多くの強力な汎用レポートテンプレートが組み込まれていますが、カスタムレポートを作成し、データを異なる角度から視覚化したり、ビルトインレポートではカバーされない方法でデータを集計して表示することもできます。

このドキュメントでは、カスタムレポートの基本的な構造、TestRail への統合方法、およびベストプラクティスについて説明します。このドキュメントは、PHP および Web 開発 (HTML、CSS および JavaScript) の基本的な知識を前提としていることに注意してください。カスタムレポートを実装するには、上記のすべてのテクノロジーに関する知識が必要です。

用語

TestRail は、さまざまなレポート関連エンティティを区別するために次の用語を使用しています。

レポート

レポートは HTML ベースのドキュメントと関連ファイルで生成されます。通常、レポートはデータを視覚化したグラフと統計を表示します。レポートはプライベートにすることも、特定のプロジェクト内のすべてのユーザー間で共有することもできます。

レポートジョブ

レポートは設定した間隔で生成できます。レポートジョブはスケジュールを定義し、すべての関連設定を保存します。レポートジョブは、TestRail の UI ではスケジュールレポートとも呼ばれます。

レポートフォーマット

レポートは TestRail 内 (インライン) または TestRail の外部 (スタンドアロン) で表示できます。レポートが生成されると、TestRail はそれを後処理し、さまざまな「レポートフォーマット」で保存します。

レポートプラグイン

レポートプラグインは、参照可能なレポートを実際に生成する処理を実装します。レポートプラグインは自己完結型で再利用可能な PHP ファイルと HTML アセット (スタイルシート、JavaScript ファイル、および画像) で構成されます。レポートプラグインは、特定の問題 (テストケースの結果カバレッジを表示するなど) を実装または解決します。プラグインは、レポートオプションを渡すことで設定できます。

レポートフォーム

レポートの作成または編集は、レポートフォームで行います。レポートフォームは 2 つのセクションに分かれています。最初のセクションでは、レポートのいわゆるカスタムオプションを設定します。このセクションは、レポートプラグインごとに異なります。2 番目のセクションはシステムオプション (アクセス、通知、スケジュール) を定義するもので、すべてのレポートプラグインで同じです。

はじめに

アプリケーションの初期化時に TestRail がレポートプラグインを探すディレクトリは 2 つあります。最初のディレクトリは、TestRail 組み込みのデフォルトプラグインも保存される場所です。TestRail を更新するとこれらのファイルが上書きされるため、このディレクトリのプラグインスクリプトを追加または変更しないでください。

<TestRail>/app/plugins/reports

変更または新規追加されたプラグインスクリプトは、常にカスタムレポートプラグインのディレクトリに配置する必要があります。

<TestRail>/custom/reports

TestRail のレポートプラグインを使い始める最も簡単な方法は、次の GitHub リポジトリを使うことです。このテンプレートを参考として使用できますが、新しいレポートプラグイン用に空のディレクトリから始めて、テンプレートファイルを 1 つずつ作成/コピーすることをお勧めします。

$ git clone https://github.com/gurock/testrail-custom.git
$ ls testrail-custom/reports/template
about.json
i18n/
images/
js/
report.php
styles/
views/

プラグイン構造

サンプルテンプレートを見るとわかるように、レポートプラグインは単純なディレクトリであり、プラグインの実際の PHP モジュール (report.php)、説明ファイル (about.json)、HTML アセットを含むいくつかのサブディレクトリ (images、js、styles) などのほか、言語ファイルおよびビュー (レポートのレンダリングに使用される) が含まれています。次のセクションでは、詳しく説明します。

about.json

このファイルにはレポートプラグインの説明と、ラベル (名前)、説明、作成者などレポートプラグインのメタデータを記します。JSON 形式を使用しており、次のようになります。

{
  "author": "Gurock Software",
  "version": 1,
  "label": "l:reports_tmpl_meta_label",
  "summary": "l:reports_tmpl_meta_summary",
  "description": "l:reports_tmpl_meta_description",
  "group": "l:reports_tmpl_meta_group",
  "translations": ["reports_tmpl"]
}

TestRail は完全に翻訳可能です。これにはレポートも含まれます。レポートを翻訳するには、レポートプラグインが初期化されるときに TestRail によって自動的にロードされる 1 つ以上の「翻訳」ファイルを含めます。

label と group は、TestRail のレポート概要ページのサイドバーにレポートプラグインを表示する方法を定義します。summary フィールドと description フィールドには、それぞれ、レポートプラグインの処理ついての概要と説明を定義します。

慣例により、 ‘l：’ で始まる文字列は翻訳ファイルからの文字列として解釈されます (下記を参照)。

i18n/

このディレクトリには、レポートプラグインの翻訳ファイルがあります。about.json で指定したファイル、例えば reports_tmpl.php などが含まれている必要があります。このファイルの完全な相対パスは次のようになります。

i18n/translations/en/reports_tmpl.php

パスは、TestRail のユーザーインターフェイスの翻訳と同じ規則に従います。ファイルの内容は、翻訳された文字列です。

$lang['reports_tmpl_meta_label'] = 'Template';
$lang['reports_tmpl_meta_group'] = 'Template Group';
$lang['reports_tmpl_meta_summary'] = 'Demonstrates how to develop custom report plugins.';
$lang['reports_tmpl_meta_description'] = 'Demonstrates how to develop custom report plugins and serves as a skeleton for new report plugins.';

report.php

このファイルには、レポートプラグインの PHP ベースの実装が含まれています。TestRail は、レポートプラグインディレクトリ名の後ろに “_report_plugin” が付いた名前のクラスを期待します。

class Template_report_plugin extends Report_plugin
{
}
 
..

このクラスは、レポートフォームおよびオプションの表示と検証を行い、実際のレポートを生成するためのいくつかのメソッドを実装することが期待されています。

views/

このディレクトリには、レポートのレンダリング処理に使用されるレポートプラグインのビューが含まれています。ビューは、レポートプラグインによってロードされ、実際の HTML ドキュメントを生成する標準的な PHP ファイルです。

独自のプラグインを構築する

カスタムレポートの作成方法や、レポートプラグインの内部的な仕組みおよび構造について詳しく知るには、以下を参照してください。

カスタム レポート：はじめに

用語