Extent Reports

目次:

1. 概要
2. プラグインのインストール
3. 使用方法
3.1 Reportスクリプト
3.2 Setスクリプト
3.3 Flushスクリプト
4. Klov連携
5. ExtentX連携
5.1 ExtentXのセットアップ
5.2 ExtentXのカスタマイズ
6. 変更履歴

1. 概要

Extent Reportsプラグインは、Extentライブラリと連携し、T-Plan Robotオートメーションから包括的なHTMLレポートを生成します。

また、このプラグインは以下のようにExtentX/Klovレポートサーバーにも対応しています。

• プラグインバージョン0.4にはExtent v3.1.5が同梱されており、Klovレポートサーバーv0.1.1に対応しています。

• プラグインバージョン0.3はExtent v2.41.0をベースとしており、現在は廃止されたExtentX 0.2サーバーに対応しています。

• 廃止されたExtentX v1にはまったく対応していません。

Extentライブラリは、プラグインリリースに同梱されたBSDライセンスの下で公開されています。このプラグインはソースコードとともに公開されており、サードパーティ製レポートフレームワークとの連携の参考例として機能します。T-Plan Ltd.のお客様は、自社のソリューションで自由に再利用いただけます。ソースコードはプラグインアーカイブ内に同梱されています。

ご質問やご提案がありましたらT-Plan supportまでご連絡ください。T-Planが提供するその他のプラグインの一覧はこちらをご覧ください。

2. プラグインのインストール

このプラグインにはT-Plan Robot 4.0以降が必要です。プラグインをインストールするには、以下の場所からダウンロードしてください。

• バージョン0.4:

  https://downloads.t-plan.com/releases/robot/plugins/extent-plugin_v0.4.zip

  
  

  • Extent 3.1.5およびKlov 0.1.1レポートサーバーに対応

• バージョン0.3:

  https://downloads.t-plan.com/releases/robot/plugins/extent-plugin_v0.3.zip

  • ExtentX 0.2レポートサーバーに対応(廃止済み)

バージョンごとの違いの詳細についてはChange Logを参照してください。Extentライブラリを更新する必要がある場合は、プラグインフォルダおよびextent-plugin.jarを除くすべてのJARファイルとlib/サブフォルダ内のファイルを新しいものに置き換えてください。JARファイルの名前は、プラグインがこれら2つのフォルダにあるすべての.jarファイルを読み込むため、問題になりません。

オプション1:

重要: Java 9では動的JARロードのサポートが失われたため、Java 9以降を実行している場合はこのオプションを使用する必要があります。

1. ファイルをハードドライブ上の任意の場所に展開します。

2. フォルダおよびlib/サブフォルダ内のすべてのJARファイルを、Robot起動コマンドのクラスパスに追加します。詳細はRobotのリリースノートを参照してください。

3. Robotを起動または再起動します。テストスクリプトがRobotに公開されます。TPRスクリプトでRunコマンドを作成すると、プロパティウィンドウにプラグインスクリプトが一覧表示されます。

オプション2(JAVA 8以下):

1. ファイルをRobotインストールディレクトリ配下のplugins/ディレクトリに展開します。これにより、Robotは起動時にクラスをロードします。プラグインの古いバージョンが残っている場合は、必ず削除してください。
   

2. Robotを起動または再起動します。テストスクリプトがRobotに公開されます。TPRスクリプトでRunコマンドを作成すると、プロパティウィンドウにプラグインスクリプトが一覧表示されます。

オプション2(JAVA 8以下):

1. ファイルをハードドライブ上の任意の場所に展開します。

2. TPRスクリプトでこのプラグインを使用する場合は、各テストスクリプトの先頭に以下のコマンドを記述してください。
   Include "<location>/extent-plugin.jar"

3. Javaテストスクリプトでこのプラグインを使用する場合は、プラグインアーカイブ内のすべてのJARファイルをJavaのクラスパスに配置してください。

4. ポータブルRobotプロジェクトを作成するには、アーカイブをプロジェクトフォルダに展開し、_PROJECT_DIR変数を使用してスクリプトから参照します。
   Include "{_PROJECT_DIR}/extent-plugin.jar"
   または、呼び出し元スクリプトからの相対パスを使用することもできます。
   Include "../extent-plugin.jar"

プラグインをアンインストールするには、ファイルを削除し、Include参照を取り除くだけです。

3. 使用方法

このプラグインには、3つのJavaテストスクリプトが含まれています。

プラグインスクリプトは、TPRテストスクリプトからRunコマンドを使用して呼び出します。コマンドはCommand Wizardツールを使用すると簡単に作成できます。既存のRunコマンドを編集するには、右クリックしてコンテキストメニューからPropertiesを選択します。

以下の図は、Robotテストスクリプトで作成されたパラメータやアーティファクトがExtentレポートにどのように反映されるかを示しています。

TPRスクリプトの例:

// Load the plugin saved to the project dir
Include "../extent-plugin.jar"

// Start the Extent report
Run "com.tplan.extent.Report" desc="Extent reports demo" file="extentreport.html" name="Demo Test"

// Set the author, category, target system and Robot version
Run "com.tplan.extent.Set" author="John Doe" category="Regression" param="System" value="Windows 7 64-bit"
Run "com.tplan.extent.Set" param="Robot" value="{_PRODUCT_VERSION_LONG}"

// Start also the Robot report to show how it gets linked
Report "results.xml"

// Produce some reportable objects
// Screenshot
Screenshot "myscreen.png" desc="Test screenshot"

// Record one PASS and one FAIL test step
Step "Successful test step" pass
Step "Unsuccessful test step" fail

// Exit with the code of 0 which means the overall PASS result
Exit 0

結果として得られるExtentレポート:

システム情報パラメータはテスト詳細内にあります:

3.1 Reportスクリプト

説明

Reportスクリプトは、RobotのReportコマンドと同様の機能を提供します。主な機能:

• 正確なデータを取得するには、レポートをテストスクリプトの先頭で開始する必要があります。後半や末尾で開始した場合もすべてのアーティファクトは記録されますが、実行時間と結果のタイムスタンプが不正確になります。これはExtent APIの制限です。

• 絶対ファイルパスを指定しない限り、レポートはスクリプトのレポートディレクトリ、すなわち_REPORT_DIR変数で指定されたパスに保存されます。詳細はレポートパスに関するドキュメントを参照してください。別のReportコマンド呼び出しにより、同じフォルダにRobotレポートを同時に作成することもできます。

• このプラグインは並列テスト、つまり並列実行される2つのスクリプトが同じレポートに書き込む場合には対応していません。この例に従うことで、将来的に並列レポートに対応するよう更新できる可能性があります。

• レポートはスクリプトの終了時に対象ファイルへ書き込まれます。スクリプトの実行中に任意のタイミングで保存するにはFlushを呼び出してください。

レポートには、以下のRobotアーティファクトが記録されます。

• Screenshotコマンドで作成されたスクリーンショット、

• Stepで作成されたテストステップ、

• Warningで作成された警告、

• T-PlanフレームワークがRobotの実行ログに書き込むログ、およびLogコマンドの呼び出し(任意、デフォルトでは無効)。

Extentはデフォルトで、失敗したステップが1つでもあるとテストを失敗として扱います。しかし、このプラグインはRobotのモデルに従い、テストスクリプトの終了コードからPASS/FAIL結果を導出します。

構文(TPRスクリプト)

Run com.tplan.extent.Report [file=<HTML_file_path>] [name=<name>] [desc=<description>] [logs=<true|false>] [project=<project_name>] [extentx=<address[:port]>] [kolv=<address[:port]>]

構文(Javaスクリプト)

run ("com.tplan.extent.Report", "file", "<HTML_file_path>", [, "name", "<name>"] [, "desc", "<description>"] [, "logs", "true|false"] [, "project", "<project_name>"] [, "extentx", "<address[:port]>"] [, "klov", "<address[:port]>"] );

※ 赤色は必須パラメータを示します

オプション

file=<HTML_file_path>

- Extentレポートの保存先となるHTMLファイルへのパスです。相対パスまたはファイル名のみの場合、呼び出し元のRobotスクリプトの現在のレポートディレクトリを基準に解決されます。

name=<name>

- テストスクリプト名です。

desc=<description>

- テストスクリプトの説明です。

logs=<true|false>

- trueを指定すると、Robotの実行ログに書き込まれるログも記録します。これらはRobotおよびLogコマンドの呼び出しによって作成されます。デフォルト値はfalseです(ログを記録しません)。

extentx=<address[:port]>

- ExtentXまたはKlovレポートサーバーのバックエンドとなるMongoデータベースをホストするマシンの任意のアドレス(既知のネットワークホスト名またはIPアドレス)です。例:「192.168.100.3」や「mymachine.mynetwork.com」。Mongo DBがデフォルトポートの27017で動作している限り、ポートを指定する必要はありません。有効なアドレスを指定すると、スクリプトはローカルHTMLレポートを作成するとともに、そのコピーをDBにアップロードしてExtentXまたはKlovレポートサーバーで閲覧できるようにします。後者の場合はklovパラメータも指定する必要があります。詳細はKlov IntegrationまたはExtentX Integrationの章を参照してください。v0.3以降でサポートされています。

klov=<address[:port]>

- Klovレポートサーバーをホストするマシンの任意のアドレス(既知のネットワークホスト名またはIPアドレス)です。例:「192.168.100.3」や「mymachine.mynetwork.com」。Klovがデフォルトの HTTPポート80で動作している限り、ポートを指定する必要はありません。extentxパラメータにもMongoDBのアドレスを指定する必要があります。詳細はKlov Integrationの章を参照してください。v0.4以降でサポートされています。

project=<project_name>

- 任意のプロジェクト名です。レポートには表示されませんが、ExtentXダッシュボードでの分類に使用できます。詳細はKlovまたはExtentX Integrationの章を参照してください。v0.3以降でサポートされています。

戻り値

このコマンドは常に0(ゼロ)を返します。

使用例

- スクリプトのレポートフォルダでExtentレポートを開始します:

Run "com.tplan.extent.Report" file="extent.html" name="MyApplication test" desc="This test opens MyApplication and tests its functionality."

- Extentレポートを開始し、Klovレポートサーバーにアップロードします。ここでは、KlovとMongoDBの両方がローカルマシンのデフォルトポートにインストールされていることを前提としています:

Run "com.tplan.extent.Report" file="extent.html" name="MyApplication test" project="MyApplication" extentx="localhost" klov="localhost"

- Extentレポートを開始し、Mongo DBバックエンドがマシンmymongo.mynetwork.com で動作しているExtentXダッシュボードにアップロードします:

Run "com.tplan.extent.Report" file="extent.html" name="MyApplication test" project="MyApplication" extentx="mymongo.mynetwork.com"

- スクリプトのレポートフォルダに、ExtentレポートとRobot XMLレポートの両方を作成します:

Run "com.tplan.extent.Report" file="extent.html" name="MyApplication test" desc="This test opens MyApplication and tests its functionality."
Report "results.xml" desc="This test opens MyApplication and tests its functionality."

3.2 Setスクリプト

説明

Setスクリプトは、以前に開始したExtentレポートに、以下のような属性を設定します:

• テスト作成者名(例:「John Doe」)。

• テストカテゴリ(例:「Regression」、「Black box」など)。

• パラメータと値のペアの形式によるシステム情報(例:「System」、「Windows 7 x64」など)。

• レポートの外観をカスタマイズできるレポート設定ファイル(XML)。例を参照してください。

複数の値(複数の作成者、システム情報エントリ、カテゴリ)を設定するには、スクリプトを繰り返し呼び出してください。パラメータが指定されていない場合、または実行中のExtentレポートがない状態でスクリプトが呼び出された場合は、何も行いません。

構文(TPRスクリプト)

Run com.tplan.extent.Set [author=<author_name>] [category=<category>] [param=<sysinfo_param>] [value=<sysinfo_value>]

構文(Javaスクリプト)

run ("com.tplan.extent.Set" [, "author", "<author_name>"] [, "category", "<category>"] [, "param", "<sysinfo_param>"] [, "value", "<sysinfo_value>"] );

※ 赤色は必須パラメータを示します

オプション

author=<author_name>

- テスト作成者名です(例:「John Doe」)。

category=<category>

- カテゴリ名です(例:「Regression」や「Black box」)。

param=<sysinfo_param>

- システム情報パラメータ名です(例:「System」)。

value=<sysinfo_value>

- システム情報パラメータの値です(例:「Windows 7 x64」)。

config=<configuration_file>

- Extent設定ファイル(.xml)です。これは廃止されており、旧バージョンのExtent 2.41.0でのみサポートされています。

戻り値

このコマンドは常に0(ゼロ)を返します。

使用例

- スクリプトのレポートフォルダでExtentレポートを開始し、作成者、カテゴリ、システムタイプを設定します:

Run "com.tplan.extent.Report" file="extent.html"
Run "com.tplan.extent.Set" author="John Doe" category="Regression" param="System" value="Windows 7 x64"

- 複数の作成者を設定します:

Run "com.tplan.extent.Set" author="John Doe"
Run "com.tplan.extent.Set" author="Jane Doe"

3.3 Flushスクリプト

説明

オプション

Reportを通じて開始されたExtentレポートは、パフォーマンス上の理由から、テストスクリプトの終了後にフラッシュ(ファイルに保存)されます。スクリプトの実行中に任意のタイミングで実行中のレポートをフラッシュするには、Flushを使用してください。

実行中のExtentレポートがない状態でスクリプトが呼び出された場合は、何も行いません。

構文(TPRスクリプト)

Run com.tplan.extent.Flush

構文(Javaスクリプト)

run("com.tplan.extent.Flush");

※ 赤色は必須パラメータを示します

オプションはありません。

戻り値

このコマンドは常に0(ゼロ)を返します。

使用例

- Extentレポートを開始し、すぐにフラッシュしてレポートファイルを利用可能にします:

Run "com.tplan.extent.Report" file="extent.html" name="MyApplication test" desc="This test opens MyApplication and tests its functionality."
Run "com.tplan.extent.Flush"

4. Klov連携

Klovは、複数のExtentレポートを基にテストダッシュボードを提供するレポートサーバーです。基本的なテストレポートの統計と分析機能を備えています。デモについてはKlovサイトを参照してください。

• Klovサイトの手順に従って、サーバーをインストールおよび起動してください。

• 起動して動作したら、extentx(Mongo DBのホストとポート)およびklov(Klovサーバーのホストとポート)パラメータを正しく指定してReportスクリプトを呼び出します。Extentレポートは、ローカルのHTMLファイルに保存されると同時にKlovサーバーにもアップロードされます。

注: Klovレポートサーバーでは、レポートのスクリーンショットのアップロードと表示に失敗します。詳細はバグ#45: Problems attaching screenshots to the logを参照してください。この問題は、ローカルのHTMLファイルに保存されたExtentレポートには影響しません。

5. ExtentX連携

重要: ExtentXはKlovにより廃止されました。以下の情報は後方参照のためにのみ提供しています。

ExtentXは、Klovによって廃止された旧製品です。

プラグインv0.3以降は、以下の機能を備えたExtentX v0.2と連携します:

• ExtentX v0.2に対応しています。バージョン0.2.1は、本ドキュメントの執筆時点(2016年8月)で不安定だったExtent v3.0.0を必要とするため、サポートしていません。ExtentX 0.2.1以降との連携にご関心がある場合は、最新状況についてT-Plan supportまでお問い合わせください。

• このプラグインは、Reportスクリプトの「extentx」および「project」パラメータを通じてExtentXと連携します:

• Mongo DBのアドレスを指定すると、プラグインはローカルレポートとそのコピーの両方をExtentXダッシュボードに作成します。

• ExtentX 0.2の制限により、外部リソースはサーバーにアップロードされません。これには、Extent HTMLレポートにリンクされたスクリーンショット、ログ、その他の外部ファイルが含まれます。これはExtentX v0.2.1で対応される予定とされていますが、2016年8月時点では正式にはリリースされていません。

5.1 ExtentXのセットアップ

本ドキュメントには、Windows 10 Home 64-bit にExtentXサーバー(ダッシュボード)をインストールする手順が記載されています。32-bit Windowsにインストールする場合は、32-bit版のインストーラーをダウンロードしてください。手順は基本的に、ExtentXサイトで公開されているMongoDB & NodeJS on same hostのシナリオに従っていますが、より詳細であり、インストール中に発生したいくつかの問題にも対応しています。その他のシステム、またはMongoDBとExtentXを別々のマシンで実行するシナリオについては、公式インストール手順を参照してください。

1. 64-bit MSIインストーラーを使用してNodeJSをインストールします。

2. Windows Server 2008 R2 64-bit以降(SSLサポート付き)用インストーラーを使用してMongoDBをインストールします。

3. デフォルトのDBデータフォルダを作成し、コマンドプロンプトからMongoDBを起動します(MongoDBのドキュメントに基づく手順)

md \data\db
"C:\Program Files\MongoDB\Server\3.2\bin\mongod.exe"

コマンドプロンプトは開いたままにしておいてください。出力は次のような内容になるはずです:

2016-08-26T10:36:37.496+0200 I NETWORK [initandlisten] waiting for connections on port 27017

ヒント: MongoDBをシステムサービスとして設定する方法については、製品ドキュメントを参照してください。

4. ExtentX 0.2-alphaをダウンロードします。0.3 pre-AlphaはExtent 0.3を必要とし、当社のRobot用Extent Reportsプラグインv0.3はExtent 0.2.41をベースとしているため、ダウンロードしないでください。

5. ファイルを展開し、コマンドプロンプトを開いて、package.jsonファイルが含まれる「extentx」フォルダに移動します:

npm install
node_modules\.bin\sails lift

コマンドプロンプトは開いたままにしておいてください。出力は次のような内容になるはずです:

info: To see your app, visit http://localhost:1337
info: To shut down Sails, press <CTRL> + C at any time.

6. Webブラウザでhttp://localhost:1337/を開きます。空のExtentXダッシュボードが表示されるはずです。別のマシンからダッシュボードを表示するには、「localhost」を、ExtentXがインストールされているマシンのホスト名またはIPアドレスに置き換えてください。

7. ダッシュボードを終了するには、Extentアプリのコマンドプロンプトで Ctrl+C を押し、必要に応じてデータベースも同様に終了します。両方のコンポーネントを再度起動するには、ExtentXのホームフォルダに移動して以下を実行します:

コマンドプロンプト#1: "C:\Program Files\MongoDB\Server\3.2\bin\mongod.exe"

コマンドプロンプト#2: node_modules\.bin\sails lift

5.2 ExtentXのカスタマイズ

この章では、自社のリンクやグラフィックを表示するようにExtentXのソースコードを変更する手順を説明します。この製品はBSDライセンスの下でライセンスされているため、法的な考慮事項はほとんどありません。

この手順は、ExtentX 0.2-alphaのソースコードの調査に基づいています。ファイルはJavaScriptコードとHTML要素が混在しており、任意のプレーンテキストエディタ(メモ帳、JEditなど)で簡単に編集できます。変更を適用するには、ExtentXアプリケーションを再起動する(「sails lift」)だけです。

5. 変更履歴

バージョン0.4(2018年6月5日リリース)

• Extent 3.1.5に対応

• Reportスクリプトの「extentx」、「klov」、「project」パラメータを通じたKlov 0.1.1レポートサーバーとの連携。

バージョン0.3(2016年8月26日リリース)

• Reportスクリプトの「extentx」、「project」パラメータを通じたExtentXダッシュボードとの連携。

• 本ドキュメントにExtentXの説明、セットアップおよびカスタマイズ手順を追加。

バージョン0.2(2016年8月1日リリース)

• 画像(スクリーンショット)へのリンクを絶対パスから相対パスに変更し、Webルート(Jenkins)配下でも画像が正しく表示されるようにしました。

• CLIモードで実行する場合(-n/--nodisplayオプション使用時)、プラグインはレポートファイルの場所をコンソールログに出力します(デフォルトのXML/HTMLレポートジェネレーターと同様)。

バージョン0.1(2016年6月16日リリース)

• 初版。