プラグインフレームワーク

1. はじめに

リリース7までは、Robotプラグインの概念は非常にシンプルでした。プラグインとは、コンパイル済みのJavaコードであり、通常は単一のJARファイルの形をとっていました。少なくとも1つのJavaクラスがRobotプラグインインターフェースを拡張し、新機能やスクリプト拡張機能を提供する仕組みでした。これらを以後「フィーチャープラグイン」と呼びます。作成方法についてはこちらのドキュメントをご覧ください。

フィーチャープラグインは手動でインストールする必要がありました。ユーザーはJARファイルをダウンロードし、Robotインストールフォルダ内のplugins/フォルダにドロップするよう指示されていました。このフォルダは起動時にスキャンされ、そこで見つかったすべてのプラグインが有効化されました。プラグインはPluginsウィンドウで確認できます。

この方法はそれなりに妥当ですが、いくつかの制約があります。インストーラーもアンインストーラーもありません。依存関係、プラットフォーム要件、Robotの最小バージョンをチェックする仕組みもありません。プラグインのバージョン管理もありません。ユーザーは自分でプラグインを管理し、更新に気を配る必要があります。そして何より、この仕組みはコンパイル済みのJavaコードを前提として設計されていますが、実際にはほとんどのプラグインが他のファイルを必要とするか、そもそもJavaコードを含まないことさえあります。

Robotリリース7でChromiumおよびJDKプラグインが導入されたことで、プラグインはRobotのリリースと同等の扱いになりました。プラグインはUpdate & Upgradeウィンドウからダウンロード、インストール、アンインストールできます。バージョン、依存関係、プラットフォーム要件のチェック機能が備わっており、プラグインにはフィーチャープラグインを含め、あらゆるものを含めることができます。混同を避けるため、この新しい形式をインストール可能プラグインと呼ぶことにします。

フィーチャープラグインと同様に、インストール可能プラグインのフレームワークも汎用的かつ公開されています。次の章では、このフレームワークを活用してRobotの拡張機能を作成し、組織内、あるいはサードパーティの顧客にも透過的に配布する方法について説明します。

2. プラグインの例

プラグインフレームワークの原理を説明するため、簡単なプラグインを作成します。ここでは、Feature Plugin Frameworkドキュメントの付録に記載されている2つのフィーチャープラグインの例と、Java Scriptsドキュメントの第6章で説明されているJavaテストスクリプトの例を使用します。次の3つのクラスを用意します。

• com.tplan.robot.scripting.commands.impl.ConsoleMessageCommandクラスは、「Msg」という新しいTPRスクリプト言語コマンドを提供します

• pluginexamples.GuiPluginExampleクラスは、Robotの「Tools」メニューとツールバーに、「Hello」という新しいメニュー項目とツールバーボタンをインストールします。

• scripts.Verifyクラスは、テストスクリプトからファイルの存在を確認できるJavaテストスクリプトです。

このコードは事前にコンパイル済みで、3つのクラスをJARファイルとして提供しています。こちらからダウンロードできます。

動作を確認するには、ダウンロードしたアーカイブからJARファイルを展開し、Robotインストール先のplugins/ディレクトリに配置します。次にRobotを起動または再起動し、以下を確認してください。

• ツールバーには「Hello」 ボタンがあります。また、「Tools」メニューにも対応するメニュー項目があります。選択すると簡単なメッセージウィンドウが開きます。

• TPRテストスクリプトで「Msg」コマンドを使用すると、コンソールにメッセージを出力できます。コマンドを実行した後、メッセージを確認するにはHelp→Log Viewerウィンドウを使用してください。

• scripts.Verifyスクリプトは、Runスクリプトクラスセレクター(右側の「...」ボタン)から選択できます。
  

JARファイルを作成することで、3つの機能を持つフィーチャープラグインを実質的に作成したことになります。次に、同じ機能を持つインストール可能プラグインを作成します。

3. プラグインの構造

インストール可能プラグインのアーカイブは、Robotインストールディレクトリに展開する単純なZIPファイルです。Linux/UnixおよびMac OS Xのプラグインではファイルのパーミッションを維持する必要がある場合があり、その場合ZIPには必要なファイルをすべて含む単一のTARファイルが格納されます。

アーカイブには、ディレクトリ構造を含む実際のプラグインファイルとプラグインディスクリプタが含まれます。これはプラグインを記述する必須のJSONファイルで、plugins/ディレクトリに配置し、<pluginId>.jsonという名前を付ける必要があります。ここで<pluginId>は、プラグインを識別する一意のId(名前)です。

まずプラグインファイルから始めましょう。新しい空のディレクトリを作成し、そこに移動します。次にplugins/という名前のサブディレクトリを作成し、そこにJARファイルをコピーします。

Unknown Attachment

次に、プラグインディスクリプタを作成します。

3.1 プラグインディスクリプタ

ディスクリプタを作成する前に、プラグインの一意の識別子(Id)を選択する必要があります。ファイル名として使用できる文字であれば、どの文字でも使用できます。名前や会社名などのプレフィックスを付けるなどして、一意になる文字列を使用することをお勧めします。この例では、次のIdを使用します。

• tplan-plugin-examples

Idは重要な役割を果たします。ディスクリプタファイルはこのIdにちなんで名付ける必要があります。Robotがこのプラグインがインストールされているかを確認する必要がある場合、plugins/tplan-plugin-examples.jsonディスクリプタファイルを探します。また、Robotがプラグインの新しいバージョンが利用可能かどうかを確認する際にもこのIdが使用されます。

1つのプラグインについて複数のOS版を作成する場合は、それぞれ異なるIdを使用してください。このプラグインでMS WindowsとMac OS用に別々のバージョンが必要な場合、tplan-plugin-examples-winとtplan-plugin-examples-macを使用することになります。

Robot 7以降には、プラグインディスクリプタを生成するためのコマンドラインサポートが含まれています。プラグインファイルが格納されたフォルダを第1引数に、生成先のJSONファイルを第2引数に指定します。Robotインストールフォルダに移動し、以下を実行してください。

JSONファイルは次のようになります。

{
  "uniqueId": "tplan-plugin-examples",
  "version": "<Version>",
  "names": {
    "en": "<English Name>"
  },
  "descriptions": {
    "en": "<English Description>"
  },
  "messagesBeforeInstall": {
    "en": "<Optional English Message To Display Before Install>"
  },
  "messagesAfterInstall": {
    "en": "<Optional English Message To Display After Install>"
  },
  "messagesBeforeUpdate": {
    "en": "<Optional English Message To Display Before Update>"
  },
  "messagesBeforeDelete": {
    "en": "<Optional English Message To Display Before Delete>"
  },
  "vendorName": "T-Plan Ltd",
  "vendorHomePage": "http://www.t-plan.com",
  "minimumRobotVersion": "7.0",
  "supportContact": "http://www.t-plan.com/support.html",
  "date": "2022-10-04",
  "mainPath": "",
  "startupRunnable": "",
  "restartRequired": false,
  "windows": true,
  "mac": true,
  "linux": true,
  "architectures": [
    "amd64"
  ],
  "keywords": "",
  "group": "<GroupCode>",
  "canUpdate": true,
  "canDelete": true,
  "testClasses": "",
  "helpLink": "",
  "files": {
    "plugins/plugin-examples.jar": "2f3793f1",
    "plugins/plugin-examples.json": "f2958fd"
  }
}

プラグインの機能に合わせて、いくつかの属性値を更新する必要があります。UTF-8に対応したテキストエディタを使用してください。

プラグインディスクリプタには、ファイルとそのチェックサムの一覧が含まれることに注意してください。ディスクリプタ自体を除くプラグイン内のファイルを変更した場合は、ディスクリプタを再作成するか、files属性を更新後の一覧で更新する必要があります。

この例のプラグインで必要な最小限の変更は以下のとおりです。

• "version": "1.0" - プラグインのバージョンは仕様を満たす必要があります。

• "restartRequired": true - このプラグインはplugin-examples.jarファイルの読み込みにJavaが必要であり、Robotの再起動が必要です。

• "architectures": [] - すべてのアーキテクチャで動作することを示すため、現在のアーキテクチャを削除します。

また、名前、説明、グループ、インストール前に表示するメッセージなど、プラグインの見栄えを良くするための任意フィールドもいくつか更新します。これらは後ほど例のアーカイブで確認できます。

3.2 プラグインアーカイブ

プラグインアーカイブを作成するには、プラグインディレクトリを単一のZIPファイルに圧縮するだけです。Linux/UnixまたはMac OSでファイルのパーミッションを維持する必要がある場合は、任意の名前で単一のTARファイルを作成してからZIPに圧縮してください。この例のプラグインは次のようになります。

このファイルはこちらからダウンロードできます。動作を確認するには、ファイルからインストールします。

1. Tools→Update & Upgradeウィンドウを開きます

2. File/URL Updateボタンを選択します

3. フィールドにファイルパスを入力し、OKを選択します。

インストールが完了しRobotを再起動したら、プラグインで提供される3つの機能が表示されることを確認してください。

4. リリースディスクリプタ

すでにご覧いただいたとおり、プラグインアーカイブとRobotのリリースはUpdate & Upgradeウィンドウを通じて配布されます。ここに表示されるデータは「リリースディスクリプタ」から読み込まれます。これは既知のアドレスにあるHTTPサーバーに配置されるXMLファイルです。例えば、デフォルトのT-Planディスクリプタは以下にあります。

https://downloads.t-plan.com/releases/robot/descriptor.xml

このファイルは任意で暗号化されている場合があり、その場合は閲覧できないことがあります。

リリースディスクリプタは通常、Release Descriptor Editorのようなツールを使用して作成します。これについては後ほど説明します。ただし、単純なラベルや説明の更新など、手動での編集の方が効率的な場合もあります。そのため、ディスクリプタの基本的な形式を理解しておくと便利です。

空のリリースディスクリプタは非常にシンプルです。

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<releases>

</releases>

releasesノードには、2種類の子ノードを含めることができます。

• release - リリースを指定します。

• descriptor - 別のディスクリプタの内容を読み込みます。例えば、<descriptor>https://downloads.t-plan.com/releases/robot/descriptor.xml</descriptor>のような子ノードを追加すると、すべてのT-Planリリースがディスクリプタに追加されます。

この例のプラグインのリリースディスクリプタを作成するには、まず空のディスクリプタXMLをUTF-8対応のエディタに貼り付けます。releaseノードを作成するには、プラグインディスクリプタの作成に使用したのと同じRobotのコマンドラインインターフェースを呼び出しますが、今回はプラグインファイルのパスのみを引数として指定します。

C:\Program Files (x86)\T-Plan\Robot> java -cp .\* com.tplan.robot.update.UpdateManager F:\MyPlugin\MyPlugin-1.0.zip  

  <release product="plugin" type="patch" id="tplan-plugin-example" group="other" platform="all" arch="all" label="T-Plan Installable Plugin Example" build="1.0" url="MyPlugin-1.0.zip" cksum="2913311261" size="5215" producer="T-Plan Ltd">
     <desc><![CDATA[ This plugin contains three simple features. ]]></desc>
  </release>

あとは、releaseノードをreleasesの内側にコピーするだけです。最初のディスクリプタは次のようになります。

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<releases>
  <release product="plugin" type="patch" id="tplan-plugin-example" group="other" platform="all" arch="all" label="T-Plan Installable Plugin Example" build="1.0" url="MyPlugin-1.0.zip" cksum="2913311261" size="5215" producer="T-Plan Ltd">
     <desc><![CDATA[ This plugin contains three simple features. ]]></desc>
  </release>
</releases>

ディスクリプタには任意の数のreleaseノードを含めることができるため、別のプラグインや、同じプラグインの異なるバージョンについても同じ手順を繰り返すことができます。唯一の制限は、単一のディスクリプタ内の2つのノードが同じlabel属性を持つことはできないという点です。これは、Update & Upgradeウィンドウ が製品ツリーにラベルを表示するため、同じ名前の項目が複数あると区別できなくなるためです。このため、プラグイン名にはバージョンを付加することをお勧めします。例えば「T-Plan Installable Plugin Example v1.0」のようにします。

ディスクリプタをテストするには、Update & UpgradeウィンドウのFile/URL Upgrade機能を使用しますが、今回はフィールドにディスクリプタXMLファイルのパスを入力します。読み込みが完了すると、ウィンドウは次のようになります。

以下を確認することをお勧めします。

• ボタンが想定どおり有効になっていることを確認してください。例えばDownload & Installボタンです

• Download & Installを選択してプラグインをインストールします。これにより、ファイルサイズ、チェックサム、パス(URL)属性が正しいことを確認できます。

以下は、releaseノードの属性と、それらがUpdate & Upgradeウィンドウの動作に与える影響についての完全な仕様です。

releaseノードは、以下の子ノードをサポートしています。

5. リリースディスクリプタエディタ

Release Descriptor Editor (RDE) は、T-Planが提供するGUIツールです。リリースディスクリプタとプラグインアーカイブを作成・編集できます。

RDEはJavaで実装されており、Robotプラグインとして配布されます。Robotプラグインフレームワーク上で動作します。同じAPIを使用しているため、Update & Upgradeウィンドウと同じ方法で製品ツリーを表示できる点が大きな利点です。

RDEを入手するには、Update & Upgradeでそのプラグインを探してください。表示されない場合は、T-Plan supportに連絡してダウンロードリンクを取得し、URL/File Upgradeボタンからインストールしてください。

インストール後、以下の手順でRDEを起動します。

1. Robotのホームフォルダに移動します

2. release.bat(MS Windows)またはrelease.sh(Mac OS、Linux/Unix)を実行します。release.shの場合、先に実行権限を付与する必要がある場合があります(chmod a+x release.sh)。

重要:RDEは起動時に必ず最新のT-Planリリースディスクリプタをダウンロードします。これは、最新のXML構造で動作することを保証するためです。インターネットにアクセスできない場合、起動に失敗します。

ウィンドウの左側には現在のディスクリプタの内容が表示されます。右側は編集用およびコード表示用です。

新しいディスクリプタを作成するには、ツールバーのNewボタンをクリックします。実際には、RDEは現在のドキュメントからすべてのパッケージを削除し、直近のXML構造をそのまま残すだけです。

既存のディスクリプタファイルを読み込むには、Openを選択します。

Robotプラグインのコマンドラインインターフェースとは異なり、RDEはすでにZIP圧縮済みのプラグインアーカイブ(Linux/Unixの場合は任意でtar/zip)を扱います。アーカイブにはプラグインディスクリプタやplugins/フォルダを含める必要はなく、RDEが自動的に作成します。これにより、前述したプラグインJSONディスクリプタの手動作成を省略できます。Robotインストールフォルダに配置したいファイルをZIP圧縮するだけです。

ZIPを新しいプラグインとして追加するには、ツールバーのAddをクリックしてZIPファイルを選択します。RDEはプラグインディスクリプタのJSONエディタを表示し、プラグイン属性を変更できます。これらは後からいつでも編集できます。

プラグインを追加すると、ウィンドウの右側でそのreleaseノードの属性を編集できます。

いくつかのヒント:

• 変更はすぐに適用されるため、プロパティを編集する際は注意してください。後から「変更を取り消す」オプションはありません。値をリセットするには、ディスクリプタ全体を破棄するか、プラグインを再追加するしかありません。

• リリースディスクリプタには、プラグインZIP内のJSONディスクリプタに存在する一部のプロパティが重複して含まれます。主なものはPlugin Id、Build Type、Build Version 、Architectureです。これらの値は編集可能ですが、プラグイン自体との整合性を保つため変更しないことをお勧めします。エディタは、Update & Upgradeでの見た目の変更、つまりラベル(Build Name)、グループ、説明、ダウンロードURLの更新のみに使用してください。

• 説明エディタには生のHTMLを入力できます。例えば「<html><body><h1>Hello!</h1></body></html>」を貼り付けて、左側のビューで効果を確認してください。

• 英語以外の説明を追加するには、説明エディタの上にあるDefaultタブを右クリックし、コンテキストメニューからAdd a localized descriptionを選択します。

• JSONプラグインディスクリプタを編集するには、Edit Plugin Descriptorボタンを使用します。RDEからプラグインファイルの再選択を求められた場合は、必ず正しいファイルを指定してください。

• RDE v1.4は、他のディスクリプタへのリンク(descriptor XMLノード)をサポートしていません。テキストエディタで手動で追加する必要があります。RDEはこれらを変更しません。

ディスクリプタの内容に問題がなければ、ツールバーのSaveを選択してファイルに保存します。任意で、Update & UpgradeウィンドウのFile/URL Upgradeを使用して読み込み、想定どおりに動作することを確認できます。

6. プラグインの配布

プラグインを配布するには:

1. パッケージ(プラグインZIPアーカイブ)とXMLリリースディスクリプタを公開Webサーバーのドキュメントルートに配置します。

2. ディスクリプタのURLを確認します。例:https://myserver.mydomain/downloads/descriptor.xml

3. このURLをユーザーに提供し、Update & UpgradeウィンドウのFile/URL Upgrade機能を使用して読み込むよう案内します。

Robot 7.0時点では、ディスクリプタを製品ツリーに永続的に追加することはできません。ユーザーは常にFile/URL Upgradeを通じて手動で読み込む必要があります。ただし、ウィンドウは最後に入力した値を記憶します。また、自動更新機能や新しいプラグインバージョンをユーザーに通知するポップアップもありません。これらの機能は今後のRobotリリースで提供される予定です。