Utils | T-Plan Robot | T-Plan | Test Automation & RPA

T-Plan Robot Enterprise用 Utilitiesプラグイン

1. 概要

Utilitiesプラグインは、テストスクリプトで使用できる様々なユーティリティコマンドを提供します。ご質問やご提案がございましたら、 T-Planサポートまでご連絡ください。T-Planが提供するその他のプラグインの一覧はこちらをご覧ください。

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

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

バージョン0.6:

https://downloads.t-plan.com/releases/robot/plugins/utils_v0.6.zip

バージョン間の違いについては変更履歴を参照してください。

オプション1:

ファイルを解凍し、utils.jarファイルをRobotインストールディレクトリ配下のplugins/ディレクトリにコピーします。これによりRobotは起動時にクラスをロードするようになります。プラグインの古いバージョンが残っていないことを確認してください。
Robotを起動または再起動します。テストスクリプトがRobotに公開されます。TPRスクリプトでRunコマンドを作成すると、プロパティウィンドウにプラグインスクリプトが一覧表示されます。

オプション2:

ファイルをハードドライブ上の任意の場所に解凍します。
TPRスクリプトでプラグインを使用する場合は、各テストスクリプトの先頭に以下のコマンドを記述してください:

Include "<location>/utils.jar"

Javaテストスクリプトでプラグインを使用する場合は、utils.jarファイルをJavaのクラスパスに置いてください。

プラグインをアンインストールするには、ファイルを削除し、Includeの参照も削除してください。

3. 使用方法

バージョン0.5には、以下のJavaテストスクリプトが含まれています:

スクリプト名	説明
com.tplan.utils.StopSchedule	呼び出し元のスクリプトおよび/またはそれが実行されているワークアイテムを停止します。
com.tplan.utils.GetDate	日付を処理し、任意の書式で保存します。
com.tplan.utils.Terminal	端末(コマンドプロンプト)にメッセージを出力します。
com.tplan.utils.FileControl	別のプロセスによって生成されたテキストファイルからコマンドを実行します。
com.tplan.utils.PopUpWindow	ポップアップウィンドウを表示します。
com.tplan.utils.CompareTexts	2つのテキストを1行ずつ比較します。
com.tplan.utils.GetJsonValue	JSONドキュメントから属性の値を抽出します。

プラグインスクリプトは、 Runコマンドを使用してTPRテストスクリプトから呼び出します。コマンドはコマンドウィザードツールを使って簡単に作成できます。既存のRunコマンドを編集するには、右クリックしてコンテキストメニューのプロパティ を選択してください。

3.1 StopScheduleスクリプト

説明

com.tplan.utils.StopScheduleコマンドは、 Exitコマンドを内部的に呼び出すことで、呼び出し元のスクリプトを停止します。スクリプトがワークアイテム(旧称"schedule")内で実行されている場合は、そのワークアイテムも停止します。これは、ワークアイテムの実行中にユーザーがStopボタンをクリックした場合と同じ効果になります。スクリプトが単独で(ワークアイテム内ではなく)実行されている場合、このコマンドは Exit コマンドと同じ動作をします。

構文(TPRスクリプト)

Run com.tplan.utils.StopSchedule [code=<number>] [desc=<description>]

構文(Javaスクリプト)

run("com.tplan.utils.StopSchedule" [, "code", "<number>"] [, "desc", "<description>"] );

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

オプション

code=<number>

- Exitコマンドに渡す数値の終了コードです(任意)。値が0(ゼロ)の場合はスクリプトが成功したことを示し、それ以外の値は失敗を示します。省略した場合はデフォルトで0(成功)になります。
desc=<description>

- Exitコマンドに渡す説明文です(任意)。終了コードが0以外の場合、この内容がスクリプトレポートに失敗の説明として表示されます。

戻り値

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

使用例

- 画面上でコンポーネントが見つからなかったため、スクリプトとワークアイテムを終了します:

Run "com.tplan.utils.StopSchedule" code="1" desc="Terminated because component A did not appear on the screen."

3.2 GetDateスクリプト

説明

com.tplan.utils.GetDateスクリプトは、日付の読み込み(または現在日時の使用)、日付の変更(加算・減算)、および結果の変数への保存を行います。次の4つのステップを実行します:

dateパラメータで指定された日付を読み込みます。入力日付の書式はinformatパラメータで指定します。日付が指定されない場合、スクリプトは現在の日付を使用します。
addパラメータで指定された時間を加算または減算します。
outformatパラメータで指定されたパターン、またはデフォルトのパターンを使って日付を書式化します。
書式化した日付を、varパラメータで指定された名前のスクリプト変数、

またはデフォルトの変数に書き込みます。

構文(TPRスクリプト)

Run com.tplan.utils.GetDate [date=<date>] [informat=<pattern>] [add=<time_value>] [outformat=<pattern>] [var=<variable_name>]

構文(Javaスクリプト)

run("com.tplan.utils.GetDate" [, "date", "<date>"] [, "informat", "<pattern>"] [, "add", "<time_value>"] [, "outformat", "<pattern>"] [, "var", "<variable_name>"] );

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

オプション

date=<date>

- 入力日付。例: '22-04-16' または '22 April 2016'。

informat=<pattern>

java.text.SimpleDateFormat 準拠の、入力日付の書式を指定するパターンです。上記の例に対応するパターンは 'dd-MM-yy' と 'dd MMMM yyyy' です。書式が指定されない場合、DATE変数に設定されているもの、それも設定されていない場合はシステムのデフォルトが使用されます([環境設定]→[言語]パネルを参照)。

add=<time>

- 日付に加算 plus または減算 minus する時間です。正または負の整数の後に、's'(秒)、'm'(分)、'h'(時)、'd'(日)、'M'(月)、'y'(年)のいずれかの時間修飾子を付けて指定します。例えば、'-7d' は日付を1週間過去に移動します。修飾子のない単なる数値はミリ秒として解釈されます。

outformat=<pattern>

java.text.SimpleDateFormat 準拠の、出力日付の書式を指定するパターンです。上記の例に対応するパターンは 'dd-MM-yy' と 'dd MMMM yyyy' です。書式が指定されない場合、DATE変数に設定されているもの、それも設定されていない場合はシステムのデフォルトが使用されます([環境設定]→[言語]パネルを参照)。

var=<variable_name>

- 日付の保存先の変数名です。変数名が設定されない場合、デフォルトの_GDATEが使用されます。

戻り値

このコマンドは常に0(ゼロ)を返します。引数が不正な場合は構文エラーがスローされ、スクリプトが終了します。

使用例

- 昨日の日番号を変数 'Y' に保存します:

Run "com.tplan.utils.GetDate" add="-1d" var="Y" outformat="d"

- 指定日付 '22-03-2016' を読み込み、カスタム書式 '23/03/16' で変数MYDATEに保存します:

Run "com.tplan.utils.GetDate" date="22-03-2016" informat="dd-MM-yyyy" outformat="dd/MM/yy" var="MYDATE"

- 現在の日付に1か月を加算し、デフォルトの書式で変数 'D' に保存します:

Run "com.tplan.utils.GetDate" add="1M" var="D"

3.3 Terminalスクリプト

説明

com.tplan.utils.Terminalスクリプトは、端末(コマンドプロンプト)にメッセージを出力します。これにより、テキストはプロセスの出力だけでなく、Robotのアプリケーションログ([ヘルプ]→[ログビューア])にも表示されるようになります。

構文(TPRスクリプト)

Run com.tplan.utils.Terminal text="<text>" [err=<true|false>]

構文(Javaスクリプト)

run("com.tplan.utils.Terminal", "text", "<text>" [, "err", "true|false"] );

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

オプション

text=<text>

- 出力するテキストです。改行文字は '\n' として指定する必要があります。例えば、2行を出力するには "First line\nSecond line\n" を使用します。

err=<true|false>

- パラメータが省略された場合、または 'false' に設定された場合、テキストは標準出力(Javaの System.out)に出力されます。'true' を指定するとエラー出力が使用されます。

戻り値

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

使用例

標準出力に2行を出力します:

Run "com.tplan.utils.Terminal" text="First line\nSecond line\n"

3.4 FileControlスクリプト

説明

com.tplan.utils.FileControlスクリプトを使用すると、共有ファイル(「入力ファイル」)を介して別のプロセスから自動化を操作できます。これは、サードパーティ製フレームワークとの簡単な統合を可能にすることを目的としています。この仕組みは、サードパーティプロセス(「操作プロセス」)がTPRコードまたはJavaテストスクリプトのブロック(「コードブロック」)を生成し、実行中のRobotインスタンスに渡して即座に実行させる、プロデューサー・コンシューマー方式に従います。このスクリプトのライフサイクルは次のとおりです:

無限ループに入り、指定された入力ファイルを定期的にチェックします。
ファイルが作成または変更されると、スクリプトはファイルのコピーを作成し、

Run

コマンドの呼び出しでそれを実行します。ファイルの拡張子が.javaの場合、それは有効な

Javaテストスクリプト

である必要があります。それ以外の拡張子のファイルは

TPRスクリプト

として扱われます。
コードブロックの実行後、スクリプトは受信ファイルを作成し、次のコードブロックを処理する準備ができたことを示します。
上記のプロセスは、スクリプトが以下のいずれかの終了メカニズムによって終了されるまで繰り返されます:
- ユーザーによってスクリプトが停止された場合。例えば、RobotのGUIのStopボタンによる停止です。
- 実行されたコードが構文エラーをスローした場合。
- スクリプトが受信ファイルの作成または書き込みに失敗した場合。例えば、ファイル権限が不十分な場合や、ファイルがロックされている(別のプロセスに使用されている)場合です。
- 実行されたコードがスクリプトを終了させた場合。例えば
  
  Exit
  
  コマンドの呼び出し、または
  
  Click
  
  もしくは
  
  Drag
  
  の失敗による終了です。この場合、通常FileControlスクリプトだけでなく、それを起動した親スクリプトも終了します。
- ファイルに "quit" コマンドが書き込まれた場合。これはFileControlスクリプトのみを終了させ、親スクリプトは継続を許可されます。

実装の詳細:

入力ファイルの変更を検知するには、最後のファイル更新日時が使用されます。
コードの実行中はファイルの変更はチェックされません。操作プロセス側では、同期のために受信ファイルを利用することを推奨します。典型的なシナリオでは、プロセスは受信ファイルを削除し、コードを入力ファイルに書き込んでから、次のコードブロックを処理する前に受信ファイルが作成されるのを待ちます。
変更が検知されると、内容を安全にコピーできるようにするため、ファイルはFileControlスクリプトによって短時間ロックされます。操作プロセスは、ファイルがロックされている間にアクセスしようとした際にスローされるファイルI/Oエラーに対処できる必要があります。I/Oエラーを安全に処理できないプロセスは、受信ファイルを待つか、FileControlスクリプトがファイルを処理するのに十分な時間を与えることを推奨します。例えば、チェック間隔がデフォルトの250ミリ秒に設定されている場合、コードがファイルに書き込まれてから1、2秒以内に変更が検知され、入力ファイルがコピーされると考えて差し支えありません。
操作プロセスがRobotインスタンスと同じマシン上にあり、自動化がローカルデスクトップ接続に依存している開発・デバッグ環境では、外部からのマウス操作でスクリプトが一時停止してしまうという制限があります。この回避策として、各コードブロックの先頭で "Connect java://localhost" を呼び出し、末尾で Disconnect を使って接続を閉じてください。接続を高速化するには、保存済みキーボードマップの有効化をご検討ください。
入力ファイルからのすべてのコードは単一のセッション内で実行されるため、親スクリプトが定義した

グローバル変数

に対して読み書きアクセスできます。コードブロック内で作成された変数はローカル変数として作成され、親スクリプトや他のコードブロックからは参照できません。

実行例については使用例の段落を参照してください。

構文(TPRスクリプト)

Run com.tplan.utils.FileControl input="<input_file>" [receipt="<receipt_file>"] [interval="<milliseconds>"] [verbose="<true|false>"]

構文(Javaスクリプト)

run("com.tplan.utils.FileControl", "input", "<input_file>" [, "receipt", "<receipt_file>"] [, "interval", "<milliseconds>"] [, "verbose", "true|false"] );

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

オプション

input=<input_file>

- TPRコマンドまたはJavaコードをRobotに投入するために使用するファイルです。

receipt=<receipt_file>

- 投入されたコードの実行が完了するたびに受信結果を書き込む任意のファイルです。ファイルが存在しない場合は作成されます。実行完了を検知するには、操作プロセス側でファイルの更新日時を監視するか、入力ファイルへの書き込み前に受信ファイルを削除してからその存在を確認することを推奨します。受信ファイルには、RFC 4180準拠のCSVデータ(カンマ区切り値)として、重要なリソースの簡単なサマリーが含まれます:

1行目には、常に次の3つの値が含まれます

exit,<exitCode>,<processExited>

ここで "<exitCode>" は実行されたコードの数値の終了コード(戻り値)、"<processExited>" は自動化が終了したかどうかを示します。値が "true" の場合、スクリプトはまだ実行中でコードを処理する準備ができています。値が "false" の場合、上記のいずれかの終了メカニズムによりスクリプトは既に終了しており、実行されていません。

2行目には、常にHTML

実行ログ

ファイルへの完全パスが次の形式で含まれます:

log,<logFile>

パフォーマンス上の理由から、ログファイルはスクリプトが終了した後にのみ作成される点にご注意ください。つまり、スクリプトが実行中はこのファイルは存在せず、このフィールドはそれがどこに作成されるかを示しているに過ぎません。

スクリプトが

Report

コマンドを使ってレポートに結果を記録している場合、3行目にはそのパスが "report,<reportFile>" として含まれます
以降の行は、実行されたコマンドによって内容が異なります(順序は保持されます):
- Screenshot
  
  の呼び出しがあった場合、そのパスが "screenshot,<screenshotFile>" として追加されます
- Step
  
  の呼び出しがあった場合、"step,<stepName>,<result>" という行が追加されます。<result>は認識されるステップ結果ワード(pass, fail, nt, na)のいずれかです

interval=<milliseconds>

- ファイルのチェック間隔(ミリ秒単位、任意)です。デフォルト値は250ミリ秒です。

verbose=<true|false>

- 任意のログレベルフラグです。'true' を指定すると、実行されたすべてのコードが実行ログに記録されます。デバッグ目的でのみ使用してください。冗長モードでの長時間の操作は、メモリ使用量を増加させる可能性があります。

戻り値

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

使用例

FileControlスクリプトの動作を理解するには、以下の手順を実行してください:

Robotを開き、以下の内容(ファイルパスはご自身の環境に合わせて調整してください)で新しいTPRスクリプトを作成します
Include "C:\Users\John\MyAutomation\utils.jar"
Report

"results.xml"
Run

"com.tplan.utils.FileControl"

input="C:\Users\John\MyAutomation\control.tpr"

receipt="C:\Users\John\MyAutomation\receipt.csv" verbose="true"
Screenshot

"finalscreen.png"
スクリプトを実行し、実行したままにしておきます。
テキストエディタ(メモ帳、Jeditなど)で入力ファイルを開く(作成する)。以下の行を入力して保存します:
Step "Example step #1" pass
Wait "5s"
RobotのGUIを確認します。実行ログビューアには受信したコードが記録されます。画面下部のステータスバーには、5秒間の待機操作が進行中であることを示すタイムアウトのカウントダウンが表示されます。完了後、受信ファイルを確認すると、次のような内容が含まれています:
exit,0,true
log,C:\Users\John\MyAutomation\reports\Script1.tpr_1473159479894.a42cc\log.html
report,C:\Users\John\MyAutomation\reports\Script1.tpr_1473159479894.a42cc\results.xml
step,Example step #1,pass
テキストエディタに戻ります。内容を "Exit 1" または "Quit" に置き換えて保存し、RobotのGUIでの動作を確認します。スクリプトは終了します。受信ファイルを確認すると、1行目の最後の値が "false" になっており、スクリプトがもう実行されていないことを示しています。ExitとQuitの違いは次のとおりです:

- Quit はFileControlスクリプトのみを終了させ、制御を親スクリプトに戻します。結果のレポートを確認すると、"finalscreen.png" のスクリーンショットが含まれています。
- Exit は親スクリプトを終了させます。上記コード内のScreenshotコマンドは実行されません。

3.5 PopUpWindowスクリプト

説明

com.tplan.utils.PopUpWindowスクリプトは、ローカルデスクトップにポップアップウィンドウを表示します。デモンストレーション目的や、対話型のスクリプト(ユーザーに選択肢を選ばせる)に使用できます。

構文(TPRスクリプト)

Run com.tplan.utils.PopUpWindow [text="<text>"] [title="<title>"] [buttons="<button_list>"] [timeout=<time>]

構文(Javaスクリプト)

run("com.tplan.utils.PopUpWindow" [, "text", "<text>"] [, "title", "<title>"] [, "buttons", "<button_list>"] [, "timeout", "<time>"] );

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

オプション

text=<text>

- 表示するメッセージです(任意)。プレーンテキストまたは "<html><body>" で始まるHTMLコードのいずれかを指定できます。

title=<title>

- ウィンドウのタイトルです(任意)。

buttons=<button_list>

- セミコロン(;)区切りのボタンラベルのリストです(任意)。例えば、"OK;Cancel" を指定すると、"OK" と "Cancel" の2つのボタンを持つウィンドウが表示されます。ユーザーが選択したボタンは _POPUP_BUTTON スクリプト変数に保存されます。ウィンドウがタイムアウトした場合は最初のボタンが使用されます。パラメータが省略された場合、ウィンドウにはデフォルトの "OK" ボタンのみが表示されます。

timeout=<true|false>

- ユーザーがボタンでウィンドウを閉じない場合に自動的に閉じるまでの、任意のタイムアウトです。有効な time値を指定する必要があります。無効にするには、パラメータを省略するか値を0にしてください。

戻り値

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

使用例

見出しフォントで "Hello!" というメッセージを表示し、10秒後に閉じます:

Run "com.tplan.utils.PopUpWindow" text="<html><body><h1>Hello!</h></body></html>" timeout="10s"

3.6 CompareTextsスクリプト

説明

com.tplan.utils.CompareTextsは、2つの複数行テキストを1行ずつ比較し、欠落している行を検出します。行の比較には完全一致またはあいまい一致を使用できます。行の順序の違いは無視されます。

構文(TPRスクリプト)

Run com.tplan.utils.CompareTexts [text1="<text>"] [text2="<text>"] [distance="<number>"] [template="<templateText>"]

構文(Javaスクリプト)

run("com.tplan.utils.CompareTexts", "text1", "<text>", "text2", "<text>" [, "distance", "<number>"] [, "template", "<templateText>"] );

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

オプション

text1=<text>

- 一方のテキストです(必須)

text2=<text>

- 比較対象のもう一方のテキストです(必須)

distance=<button_list>

- あいまい一致のための距離です(任意)。パラメータが指定されない場合、デフォルトは0になり、スクリプトは完全一致で比較します。0より大きい値を指定すると、レーベンシュタイン距離によるあいまい一致が可能になります。これは、2つの行を一致していると見なすために、何文字まで異なっていても、または省略されていても良いかをおおよそ表します。

template=<templateText>

- 比較サマリーを格納する _TEXTDIFF 変数に使用される、行の差異のテンプレートです(任意)。レポート用途に合わせてカスタマイズできます。デフォルトのテンプレートは次のとおりです:

Item "{0}" is present in the {1} text only

ここで {0} は行のテキストに、{1} は "first" または "second" という単語に置き換えられます。

戻り値

このコマンドは、一致しないテキスト行の数を返します。両方のテキストが同じ行から成る場合は0(ゼロ)を返します。一致しない行の数は _TEXTDIFF_COUNT 変数にも保存されます。

使用例

- 典型的な使用方法は、OCRで画面から取得した2つのテキストを比較することです:

// Recognize texts in the first screen area
Compareto method= "tocr" cmparea="x:4,y:71,w:119,h:53"

// Save the resulting multiline text to a variable
Var TEXT1= "{_TOCR_TEXT}"

// Recognize text in another area
Compareto method= "tocr" cmparea="x:6,y:225,w:119,h:80"

// Compare the texts. For results see the _TEXTDIFF prefixed variables.
Run "com.tplan.utils.CompareTexts" distance="3" text1="{TEXT1}" text2="{_TOCR_TEXT}"

3.6 GetJsonValueスクリプト

説明

com.tplan.utils.GetJsonValueはJSONドキュメントを解析し、属性の値を抽出します。

構文(TPRスクリプト)

Run com.tplan.utils.GetJsonValue [json="<JSON_document>"] [name="<attribute_name>"] [parent="<parent_attribute_name>"] [var="<var_name>"]

構文(Javaスクリプト)

run("com.tplan.utils.GetJsonValue", "json", "<JSON_document>", "name", "<attribute_name>" [, "parent", "<parent_attribute_name>"] [, "var", "<var_name>"] );

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

オプション

json=<JSON_document>

- JSONドキュメントです(必須)。

name=<attribute_name>

- 属性の名前です(必須)

parent=<parent_attribute_name>

- 親属性の任意の名前です。これにより、検索を文書内の特定のオブジェクトに限定できます。親は直接の親でも、間接的な親(親のさらに親など)でも構いません。

var=<var_name>

- 属性値の保存先の変数名です。パラメータが省略された場合、結果はデフォルトの _JSON_VALUE 変数に保存されます。

戻り値

このコマンドは、成功時は0、検索に失敗した場合は1、内部エラーの場合は2を返します。

使用例

- この例では、"date" の値を "mydate" 変数に抽出し、それを出力します。

// Save the resulting multiline text to a variable
Var JSON="{\"status\":{\"id\":240000778,\"date\":\"2024-05-08\"}}"
Run "com.tplan.utils.GetJsonValue" json="{JSON}" name="date" var="mydate"
Log "The date is: {mydate}"

4. 変更履歴

バージョン0.6(2024年5月8日リリース)

GetJsonValueスクリプトを導入しました。

バージョン0.5(2017年12月11日リリース)

CompareTexts

スクリプトを導入しました。

バージョン0.4(2016年9月8日リリース)

FileControl

および

PopUpWindow

スクリプトを導入しました。

バージョン0.3(2016年4月11日リリース)

Terminal

スクリプトを導入しました。

バージョン0.2(2016年3月24日リリース)

GetDate

スクリプトを導入しました。

バージョン0.1(2015年3月9日リリース)

最初の公開リリースで、

StopSchedule

スクリプトを含みます。

目次:

1. 概要

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

3. 使用方法

3.1 StopScheduleスクリプト

説明

3.2 GetDateスクリプト

説明

3.3 Terminalスクリプト

説明

3.4 FileControlスクリプト

説明

3.5 PopUpWindowスクリプト

説明

3.6 CompareTextsスクリプト

説明

3.6 GetJsonValueスクリプト

説明

4. 変更履歴