Waitfor Command

3.2.21 Waitfor

説明

Waitfor - スクリプトの実行を一時停止し、RFB イベントやリモートデスクトップイメージの状態を待ちます。現在サポートされているイベントは、画面更新、ベル（デスクトップサーバーが ASCII 文字 0x07 を印字してビープ音を発した）、リモートシステム上にコピーされたテキストの配信（デスクトップサーバーのクリップボードの変更）、一致/不一致（正負の画像比較結果を待つ）です。

特定のイベントのサポートは、プロトコルの能力によって異なります。T-Plan Robotはオープンで柔軟なアーキテクチャを採用しており、リモートデスクトップ技術で一般的に提供されている機能のサブセットだけをクライアントにプラグインすることができます。Waitforイベントが選択したデスクトッププロトコルでサポートされていない場合、スクリプトはエラーを報告します。以下の表は、サポートされている2つのプロトコルの機能の一覧です：

Waitfor イベント	RFB クライアント（”rfb”）	静止画像 ("file")
"update"（画面更新）	はい	はい(画像ファイル変更の検出による)
"bell"（ビープ音）	あり	なし
"clipboard" (クリップボードの変更)	はい（VNCサーバーの機能による）	いいえ
"match" (正画像比較結果)	はい	はい
“mismatch"（負の画像比較結果）	はい	はい

全てのWaitforコマンドは以下の変数に値を入れます：

変数名	変数名
_TIMEOUT=<true\|false>	タイムアウトが定義され、それに達した場合、Waitforコマンドはこの変数を'true'に設定し、そうでなければ'false'に設定します。

Waitforupdateコマンドは、追加の変数を設定する：

変数名	変数名
_X=<X-coordinate> _Y=<Y-coordinate> _W=<width> _H=<width>	条件を満たした最後の更新イベントのX、Y座標と幅と高さ。これらの変数は、Waitfor 更新のためだけに設定されます。

Waitfor matchコマンドとmismatchコマンドは、。Compareto commandとの結果の互換性を維持し、さらに2つの変数グループに値を割り当てます。：

で指定された _COMPARETO 接頭辞の付いたすべての変数が、Waitfor update で入力されます。 Compareto Command,
で指定されたすべての _COMPARETO 接頭辞付き変数。Image Comparison method.

Waitforクリップボードには_SERVER_CLIPBOARD_CONTENT変数が記述されていますが、これはWaitforコマンドによって作成されたものではなく、どのコマンドからも独立してコアフレームワークによって入力されています。

SYNOPSIS

Waitfor <event_id>[<event specific options>][timeout=<time>] [ontimeout=<command>] [onpass=<command>][count=<number>] [wait=<time>]

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

<イベントID>

-サポートされるイベントIDは、'bell'、'update'、'match'、'mismatch'、'clipboard'です。

bell event は、サーバーがビープ音を鳴らしたこと、つまりアプリケーションがベル文字（ASCII 0x07）を出力したことを示します。
Waitfor Command は、ウィンドウがポップアップするなど、リモートデスクトップイメージの更新を待つことを意味します。期待したイベントが受信されると、Waitfor コマンドはスクリプトの実行を再開し、更新座標を表す変数で実行コンテキストを更新します (Waitfor predefined variables).
match イベントは、選択された比較方法が肯定的な結果を生成するまでコマンドを待機させます（デスクトップが一致するまで待機します）。この mismatch イベントは、メソッドが肯定的な結果を生成する限り、コマンドを待たせます（デスクトップがマッチしなくなるまで待ちます）。
clipboard は、リモートサーバのクリップボードコンテンツの配信を待ちます。リモートデスクトップ上でテキストが選択され、コピーアクションが呼び出されると（Ctrl+Cなど）、一部のデスクトップサーバーはテキストをクライアントに送信します。メッセージを受信すると、_SERVER_CLIPBOARD_CONTENT変数を通して、リモートのクリップボードの内容が利用できるようになります（_SERVER_CLIPBOARD_CONTENTのコマンドも参照してください）。Var コマンドも参照)。

一般的な選択肢

timeout=<時間>

-最大待機時間を指定するタイムアウト。値はミリ秒数または有効なTime Values.デフォルト値は設定されておらず、タイムアウト値が指定されない場合、コマンドは無期限に待機します。

ontimeout=<コマンド>

-タイムアウト時に実行されるコマンド。単一のコマンドでなければならなりません。実行するコマンドのシーケンスを定義する必要がある場合は、プロシージャを使用してください。

onpass=<コマンド>

-条件が満たされたとき（予想されたイベントを受信したとき、または画像比較が予想された結果を返さなかったとき）に実行されるコマンド。単一のコマンドでなければなりません。一連のコマンドを呼び出すには、プロシージャまたは後続のIf/Else Statementコマンドの終了コードをテストします。

count=<数字>

-待機するイベントの数。デフォルト値は1。このパラメータは画像比較イベント（Waitfor match/mismatch）では無視されます。

wait=<時間>

-Waitfor条件が満たされた後の待ち時間。これは、次のコマンドが「Wait <time_in_ms>」であった場合と同じ効果を持つ。timeoutパラメータで定義されたタイムアウトに達した場合、このパラメータは無視される。値はミリ秒数か、有効なTime Values.デフォルト値は0（待機しない）です。スクリプトは、"Var _WAITFOR_WAIT=1s "のように、_WAITFOR_WAIT変数に希望する遅延を代入してデフォルト値を設定できます。

Waitfor bell [<common_options>]

特定のオプション - bell

なし。

Waitfor update [area=[x:<x>][,y:<y>][,w:<width>][,h：<height>]] [extent=<number>[%]] [cumulative=<false|true>] [<common_options>]

特定のオプション - update

area=[x:<x>][,y:<y>][,w:<幅>][,h:<高さ］

-更新を待機する画面領域。このパラメータはupdate イベントにのみ適用され、ユーザーがカスタムエリアを定義して更新を監視することができます。領域の座標は'x:<x>,y:<y>,w:<width>,h:<height>'のフォーマットを持ち、各座標はピクセル(例えば'x:225')またはパーセント(例えば'x:23%')で指定できます。x,y,width,heightのいずれかが省略された場合、Robotはフルスクリーンの値を用いて足りないパラメータを決定します。ステータスバーを使って更新領域を定義することもできます。 update coordinates機能を使うこともできます。

extent=<number>[%] を指定します。

-画面更新の範囲（スコープ）。このパラメータはupdateイベントのみに適用され、画面更新の大きさを定義します。値は、更新ピクセル数（例：'extent=400'）またはパーセンテージ（例：'extent=22%'）です。area パラメータでカスタム領域が定義されている場合、パーセント/ピクセル値はこの領域に対して計算されます。

cumulative=<false|true>を指定します。

-累積更新のオン/オフを切り替えます。もしデスクトップサーバが漸進的な画面更新を好み、予想される大きな画像の断片ではなく、小さな画像の断片を多数送信するのであれば、この機能をオンにすると、Robotは定義された範囲内の部分的な更新を要約します。デフォルトはfalseです。

WindowsのVNCサーバは画面を少しずつ更新することが知られているので、このモードをtrueに設定することをお勧めします。

Waitfor match | mismatch [template=<image_collection>][passrate=<pass_rate>%] [interval=<comparison_interval>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x：<x>][,y:<y>][,w:<width>][,h:<height>][<waitfor_common>] [<Compareto Command>]

画像収集は、選択された画像比較アルゴリズム（パラメータ "method"）によって必要とされる場合にのみ必須です。詳細は Compareto Command 仕様を参照してください。

特定のオプション - match と mismatch

template=<画像コレクション>

-画像コレクション|#imgcol] - リモートデスクトップイメージと比較する1つ以上の画像ファイル名、またはセミコロン(';')で区切られた画像を含むフォルダ。Linux/Unix では、ファイル名にセミコロンが含まれていないことを確認してください。ファイル名には、相対パス（img.png など）または絶対パス（/root/report/img.png など）を指定できます。相対パスを使った場合、画像は[_TEMPLATE_DIR変数|#_template_dir]で定義されたディレクトリで検索されます。サポートされる画像フォーマットは、Javaのバージョンとインストールされている拡張機能（Java Advanced Imaging library, JAIなど）に依存します。Java 1.6では、少なくともPNG、JPG、GIF、BMPをサポートしています。

テンプレート画像は、指定されたリスト順序でリモートデスクトップ画像と比較されます。テンプレート比較が肯定的な結果（指定されたイベントに応じて、一致または不一致のいずれか）を生成した場合、条件は満たされたとみなされ、コマンドは終了コード0で終了します。事前定義された変数_COMPARETO_TEMPLATE_INDEXは、リスト内の一致するテンプレートのインデックスを決定するために使用することができます。詳細は[画像比較固有の変数|#compareto_vars]を参照してください。

画像比較はJPEGのような非可逆圧縮の画像に対して実行すべきではありません。代わりにPNGまたはBMPを使用してください。これらは画像情報を100％保持し、信頼できる安定した比較結果を保証します。画像比較については、[Comparetoコマンド仕様|#compareto]で説明しています。

interval=<時間>

-このパラメータは画像比較の時間間隔を定義します。デフォルト値は3秒で、これはデスクトップ画像が3秒ごとに指定されたテンプレート画像と比較されることを意味します。プレーンな数値はデフォルトではミリ秒として解析されます。詳細は Time Values パラグラフを参照してください。デフォルト値は設定ウィンドウ Preferences ウィンドウの「待機設定パネル」で設定できます。

passrate=<パスレート>%

-画像比較のパスレート。0から100の間の数値を指定し、その後にパーセンテージ文字(例えば "passrate=95 "または "passrate=95%")を付けることができます。このパラメータが省略された場合、メソッドまたはRobot環境設定で定義されたデフォルトの通過率が使用されます（デフォルト値は "default "メソッドで95%、"search"および "search2"メソッドで100%）。

method=<比較メソッド>

-- 画像比較に使用するメソッド（アルゴリズム）。の章で説明されているサポートされているメソッド名(コード)のいずれかでなければなりません。 Image Comparison Capabilities 章で説明されているサポートされているメソッド名(コード)のいずれか、またはプラグインインターフェイスで有効になっているサードパーティのメソッド名でなければなりません。省略した場合、コマンドはデフォルトのものを使用します。

methodparams=<custom_params>

-画像比較アルゴリズムに渡すカスタムパラメータ。T-Plan Robot 2.0のデフォルトの画像比較アルゴリズムはカスタムパラメータをサポートしていないので、独自のアルゴリズムを作成しない限り、このパラメータを指定する必要はありません。

cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]

-比較を制限するデスクトップの矩形領域。このパラメータを省略すると、リモートデスクトップ全体が使用されます。領域の座標は、'x:,y:,w:,h:'の形式で、各座標はピクセル単位（例えば、"x:225"）またはパーセンテージ（"x:23%"）で指定できます。x,y,width,heightのいずれかが省略された場合、T-Plan Robotはフルスクリーンの値を用いて足りないパラメータを決定します(x:0, y:0, w:, h:)。

Waitfor clipboard [<waitfor_common>]

特定のオプション - clipboard

なし。

戻り値

コマンドは通常、条件(イベント)が満たされると0(ゼロ)を返します。タイムアウトに達すると0以外の値（通常は1）が返されます。Waitfor match' と'Waitfor mismatch' はComparetoコマンドの動作を模倣し、比較が成功すると0（ゼロ）、失敗すると1、テンプレート画像が見つからないか読み込めない場合は2を返します。

例

JS

Typeline "export MYDOC=`find / -name mydoc.txt`; sleep 1; echo -e '\007\007'" 
Waitfor bell count=2
Typeline "gnome-text-editor $MYDOC"

-これは、Unix/Linuxシステムでbellイベントを使う典型的な例です。ハードディスク上のファイルを見つけて編集する必要があるとしよう。最初のコマンドはターミナル・ウィンドウで検索を実行し、Waitforコマンドに進む。検索が終わると、echo OSコマンドを使ってベルが2文字表示され、マシンがビープ音を2回鳴らす。これによってWaitforコマンドが実行され、Gnomeテキストエディタでドキュメントを開く3番目のコマンドが実行されます。

行目の'sleep 1'コマンドに注意してください。デスクトップサーバーが非常に高速で、T-Plan Robotが動作しているマシンが多少遅い場合、T-Plan RobotがWaitforコマンドに進む前に文書検索が終わってしまうことがあります。sleep 1'を指定すると、サーバーは1秒待ってから2文字のベルを表示するので、この問題を防ぐことができます。

JS

procedure terminate {
    Screenshot error.jpg 
    Report report.html 
    Exit {1} 
}
Typeline myapplication 
Waitfor update extent=40% timeout=20s ontimeout="terminate 2"

これは「Waitfor update」コマンドの典型的な使い方です。ターミナル・ウィンドウからmyapplicationというGUIアプリケーションを起動しているときの状況を示しています。アプリケーション・ウィンドウは、画面サイズの少なくとも40%に等しい固定サイズを持っているとします。GUIが正しく起動すれば、スクリプトは続行される。そうでなければ、Waitforコマンドは20秒間待機し、与えられた終了コードで終了手続きを実行します。

JS

Waitfor match template=application.png;application2.png passrate=95% interval=5s timeout=5m ontimeout="exit 1"

リモートデスクトップ画像と画像application.pngおよびapplication2.pngを、少なくとも95%一致するまで5秒ごとに比較します。この条件が5分以内に満たされない場合は、Exitコマンドを使用してスクリプトの実行を終了し、終了コード1を返します。

JS

Press Ctrl+C 

Waitfor clipboard timeout=5s
if ({_EXIT_CODE} == 0) {
  Screenshot copied_text.jpg desc="Received text copied on the remote desktop: {_SERVER_CLIPBOARD_CONTENT}"
}

リモートデスクトップでCtrl+Cを押すと、選択したテキストがリモートシステムのクリップボードにコピーされます。このテキストをクライアントに送信できるデスクトップサーバーもあります。Robotはこのようなメッセージをデコードし、_SERVER_CLIPBOARD_CONTENT変数という形でスクリプトにテキストを渡すことができます。上の例では、Waitforクリップボードを通してコピーされたテキストの受信を確認する方法と、スクリーンショットの説明などに使用する方法を示しています。