Language Reference

1.はじめに

1.1 目的

このドキュメントは、T-Plan Robot がサポートするスクリプト言語の完全な仕様を提供する。 その目的は、このツールとそのテストフレームワークを使用して自動化スクリプトを書く人に、完全な構文と機能のリファレンスを提供することである。スクリプト言語はJavaスクリプトAPI
この文書で説明されている言語のスクリプトはTPRスクリプトと呼ばれる。Java Script APIに基づくスクリプトはJavaスクリプトと呼ばれる。
この文書では、スクリプトの要件、構文解析と処理のルール、言語構造、ステートメント、式、コマンド、画像比較メソッドなどの特定の要素の構文について説明する。

1.2 概要

T-Plan Robot Enterprise は、自動化スクリプトを記述するためのシンプルなスクリプト言語をサポートしています。これは Linux/Unix のシェルスクリプトにやや似た、構造化された手続き型言語です。以下のような、現代のプログラミング言語でよく知られた構造や要素をサポートしています：

• 変数(グローバルとローカルの両方）、

• 数値演算および論理式式、

• 手続きパラメータを持つ実行とインクルードコマンドと組み合わせて、関数やサブルーチンのライブラリを作成することができます、

• ループや条件構造言語リファレンスそしてif/else,

• 一連の機能コマンド数値戻り値.

T-Plan Robotは、ほとんどの一般的なリモートおよびローカルデスクトップ技術で動作するように設計されているため、スクリプト言語がサポートするコマンドは、おおよそ4つの機能領域に分類されます：

1. デスクトップコマンドデスクトップへの接続や切断、マウスやキーボードの入力（キーを押す、テキストを入力する、マウスを動かす、クリックする、ドラッグする、ホイールする）などのクライアントとサーバー間の通信を行います。

2. 管理および実行制御コマンドスクリプトの実行制御（一時停止、停止、デスクトップ画像解析、指定時間または特定のイベントの待機）に必要なインフラストラクチャを提供し、変数、ライブラリ、外部OSコマンドコールをサポートします。

3. レポートコマンド自動テストの出力を定義し、ユーザーに報告します。このカテゴリのコマンドでは、たとえば、デスクトップ画像またはその一部のスクリーンショットを撮影したり、レポートを作成したり、電子メールを送信したり、関連するテスト管理ツールに結果をアップロードしたりすることができます。

4. I/O コマンドさまざまなデータソースからの入力やデータソースへの出力を扱います。

一部のコマンドの動作は、ユーザー設定によってカスタマイズされる場合があります。このようなパラメータは実装固有のものであり、必ずしもこのドキュメントの一部を構成するものではありません。設定可能な値があるかどうかを調べるには、T-Plan Robot GUIのPreferencesウィンドウを開き、Pluginsセクションの下にコマンド設定パネルがあるかどうかを確認してください。スクリプト言語は高速で簡単な自動化の方法を提供しますが、機能が限られており、オブジェクト指向のアプローチに欠けています。このため、T-Plan Robot バージョン 2.0 では Java Script API を導入し、このリファレンスで指定されたコマンドの機能にアクセスするメソッドの呼び出しを通じて、純粋な Java でスクリプトを記述できるようにしました。そのため、Javaに固執するつもりであっても、この仕様を参照する必要があります。詳細についてはJava APIドキュメント、特にJavaスクリプトの開発スクリプトは、Javaソース・コードのスニペットを埋め込んでカスタマイズすることもできます (Javaコードブロックの章を参照)。Javaでコード化されたカスタム・アクションで言語を拡張するもう1つの方法は実行コマンドコマンドです。v2.2以降、Javaのパラメトリック呼び出しをサポートしています。

1.3 ロボット機能

T-Plan Robot Enterpriseは機能的に豊富で成熟した製品であり、以前のバージョンで開発された言語仕様の上に構築されています。一般論として、T-Plan Robot は旧バージョンの上にさらに機能を追加し、その言語はレポートジェネレーター、画像比較アルゴリズム、デスクトップクライアントなどの追加コマンドやサービスプロバイダーで拡張されています。以前の製品バージョンでデザインされたスクリプトはT-Plan Robot言語と互換性があります。

2. 言語構文

2.1 言語構造

T-Plan Robot Enterprise の言語はテキストベースのプログラミング言語であり、スクリプトは通常プレーンテキストファイルとして保存されます。以下の一般的なルールが適用されます：

• ISO8859-1 (Latin-1) 文字を推奨する。ISO8859-1(Latin-1)文字が推奨されます。このセット以外の文字をコマンド引数やパラメータ値に使用することもできますが、特定のリモートデスクトップクライアントとそのプロトコルの機能によってサポートが異なります。ISO8859-1以外の文字を使用する前に、クライアントのドキュメントを読んでください。

• このドキュメントに明示的に記載されていない限り、言語は大文字と小文字を区別しません。

スクリプトは次の規則に従って解釈されます：

• スクリプトは一行ずつ処理されます。スクリプトは一行ずつ処理されます。仕様で明示されていない限り、1つのコマンドや式を複数行に分割することはできません。

• 行には、先頭または末尾に任意の数の空白文字（スペース、タ ブレーターなど）を含めることができます。それらは、処理を進める前に切り取られます。

• 空行は無視される。

• ハッシュ '#' で始まる行はコメントとみなされ、無視されます。バージョン2.3以降では、ダブルスラッシュ'//'で始まるJava/C++スタイルのコメントも受け付けます：

# これはコメントです
// これはコメントです。

• 上記の規則で排除されない他のテキスト行には、コマンド、プロシージャーヘッダー、プロシージャーコール、if/else/for文、またはその終端である右中括弧（'}'）など、スクリプト言語の要素が1つ含まれている可能性があります。このようなテキスト行は、それぞれ次のように処理される：

1. テキストは、1つ以上の空白によってトークンに分割される。テキストは、1 つ以上のスペースによってトークンに分割されます。スペースが先行し、2 つ の二重引用符 ("...") で囲まれたテキストは、1 つのトークンと見なされます。エスケープされた二重引用符 (\") はトークンの先頭または末尾を示すものとは見なされず、以降の処理では二重引用符に置き換えられます。identifier=value'または'identifier="value with spaces"'の形式を持つ文字列は、1つのトークンとみなされ、さらに識別子と値のペアに解析されます。

   例:
   This is a text containing spaces
   - 'This', 'is', 'a', 'text', 'containing', 'spaces' の6つのトークンに解析される。

   This "is a text" containing spaces
   - 'This', 'is a text', 'containing', 'spaces' の4つのトークンに解析される。

   This text contains "double quote (\")"
   - 'This', 'text', 'contains', 'double quote (")' の4つのトークンに解析されます。

   Var SAMPLE_VAR_1="スペースを含む値" SAMPLE_VAR_2=no_spaces "NO_VAR=not_a_variable"
   - 4つのトークンに解析されます：Var」、「SAMPLE_VAR_1="空白を含む値"」、「SAMPLE_VAR_2=no_spaces」、「NO_VAR=not_a_variable」です。2番目と3番目のトークンは、さらに識別子と値のペアに解析される。

   この設計では、末尾にバックスラッシュを含む値を指定することはできません。

   Var SAMPLE_VAR="これはバックスラッシュです ୧"

   末尾の'୧'シーケンスは、バックスラッシュの後に閉じる二重引用符ではなく、エスケープされた二重 引用符として解釈されるため、コンパイラはエラーを報告します。

   Var SAMPLE_VAR="これはバックスラッシュ %26bs; "です。

2. 最初のトークンは、コマンド名またはプロシージャー名とみなされ、コマンドおよびプロシージャーテーブルと照合されます。コマンド名は大文字と小文字を区別しません。

3. さらなる処理と構文検証は、コマンド/プロシージャ・ハンドラによって実行されます。Command Syntax と Procedures の章で説明する。

2.2 時間値

コマンド引数 Wait コマンドの引数や他のコマンドのwait/timeout/delayパラメータなどの時間値は、以下の構文をサポートしている：

• 「1」は1ミリ秒として解析される、

• 「1s」は1秒、

• 「1m」は1分、

• 「1h」は1時間、

• 「1d」は1日。

• 「1w」は1週間

• 「1M」は1ヶ月

• 「1y」は1年

浮動小数点変数は英語フォーマットでのみ使用可能で、例えば '3.5h' は3.5時間（3時間30分）として解析されます。時間値には数値式を含めることができます。Numeric Expressions の章を参照してください。

例:

Wait "1.5d"

– 1日半（36時間）待つ。

Press Ctrl+C wait=5s

– Ctrl+Cを押して5秒間一時停止。

2.3 変数

変数は Var と Eval コマンドで作成することができる。変数は大文字と小文字を区別する名前と値を持つ。Var/Evalコマンドを含む）動的な内容を必要とするあらゆる場所で、変数を参照することができます。T-Plan Robot Enterpriseのプリプロセッサは、コマンド行を解析する前に{%26lt;var_name>}を%26lt;var_name%26gt;変数の値に置き換えます。

典型的な例

Var PATH=/tmp
Typeline "mkdir -p {PATH}; cd {PATH}"

Var 1="test"'のような、数字だけの変数名は避けてください。これらの変数はプロシージャー・パラメーター用に予約されており、プロシージャーを実行すると警告なしに書き換えられてしまいます。

変数が定義されていない場合、置換は行われない。以下の例では、変数定義がコメントアウトされているため、'cd /tmp'よりも'cd {PATH}'とタイプされる：

# var PATH=/tmp
Typeline "cd {PATH}"

プリプロセッサはネストされた変数参照をサポートする。この機能は、マッチの座標がSEARCH_X%26lt;number%26gt;として保存される画像比較メソッド'search'の複数のマッチを処理するために必要であり、ループの中で変数名を動的に生成する必要がある。次の例はそのような使い方を示しています。リモートデスクトップからアイコンを検索し、表示されたアイコンをクリックするとします：

Compareto "search.png" method=search
for(i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
# ネストされた変数は、接尾辞とインデックスから変数名を構成する
 Mouse click to=x:{_SEARCH_X{i}},y:{SEARCH_Y{i}} 
 }

T-Plan Robot Enterprise は、オブジェクト指向プログラミング(OOP)におけるメンバクラスとローカル変数に似たグローバル 変数とローカル 変数の概念もサポートしています。変数のタイプは明示的に宣言されませんが、コードのどこで作成されるかに依存します：

1. スクリプト本体に作成された変数はグローバル変数とみなされ、定義した時点からスクリプトの実行が終了するまでアクセス可能です。

2. 構造化されたコードブロック（プロシージャ、if/else、for文）内で作成された変数はローカル変数とみなされ、そのコードブロック内（ネストされたブロックを含む）でしか使用できません。

ローカル変数はグローバル変数を上書きすることはできません。つまり、コードブロック内でVarコマンドやEvalコマンドを実行し、その変数名がすでに存在するグローバル変数と一致した場合、同じ名前のローカル変数を定義するよりも、むしろグローバル変数を変更する方がよいということです。次の例は、その原則を示している。

# グローバル変数
Var GLOBAL=global
If (1 == 1) {
  # ローカル変数を作成し、GLOBALの値を'modified'に変更する。
  Var LOCAL=local GLOBAL=modified
  If (1 > 0) {
    Var LOCAL2=local2
    # ここで、GLOBAL、LOCAL、LOCAL2 が利用可能である。
    # コマンドは "GLOBAL=modified, LOCAL=local, LOCAL2=local2" とタイプする。
    Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"
  }
  # ここで、GLOBALとLOCALは利用可能であり、LOCAL2はもう存在しない。
  # コマンドは "GLOBAL=変更済み, LOCAL=local, LOCAL2={LOCAL2}" とタイプする.
  Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"
}
# ここで、GLOBALは利用可能であり、LOCALとLOCAL2はもう存在しない。
# コマンドは "GLOBAL=modified, LOCAL={LOCAL}, LOCAL2={LOCAL2}" とタイプする.
Type "GLOBAL={GLOBAL}, LOCAL={LOCAL}, LOCAL2={LOCAL2}"

同じルールが Include と Run コマンドでロードされたスクリプト内で定義された変数にも同じルールが適用されます。T-Plan Robot Enterpriseは、スクリプトから参照できる定義済み（明示的とも呼ばれる）変数のセットを提供します。これらの変数には、実行開始日、デスクトップサーバーのホスト名、実行されたスクリプトの名前など、様々な有用なデータが含まれています。定義済み変数の完全なリストについては Var コマンド仕様を参照してください。変数値は、CLI を使用してスクリプト実行時にオーバーライドできます。で指定されている v/-variable パラメータを参照してください。CLI Optionsドキュメントを参照してください。これにより、特定のスクリプト実行をパラメトリック化したり、スクリプトコード内の機密情報（ユーザー名、パスワード...）の漏洩を回避したりすることができます。CLIで設定すると、変数は「読み取り専用」になり、スクリプト実行中ずっとその値が固定されます。スクリプト内で実行されるこの変数を変更する Var/Eval コマンドはすべて無視され、その値には影響しません。これは、明示的な（定義済みの）変数を含む、あらゆる変数に適用される。

2.4 プロシージャ

T-Plan Robot は簡単なプロシージャをサポートしています。プロシージャは、その名前を呼び出すことで実行できる、必要な形式で記述された言語要素の名前付きブロックです。プロシージャは、ヘッダ、ボディ、右中括弧で終わります。

プロシージャの書式は

Procedure <procedure_name> {
   command1
   command2
   ...
   commandN
}

以下のルールが適用される：

• プロシージャー名は大文字と小文字を区別せず、他のコマンド名や言語要素名と衝突してはならない。v3.0.1以降、二重引用符で囲まれている場合、名前にスペースが含まれていてもよい：

Procedure "Perform action A" {
   ...
}
...
"Perform action A"

• 左中括弧'{'は、プロシージャーヘッダーと同じ行になければならない。

• 終端の右中括弧 '}' は、1行に1つでなければならない。

• プロシージャー定義は、すでに定義されている同名のプロシージャーを上書きする。

• プロシージャーは、その定義の後にスクリプトの任意の場所で呼び出すことができる。

• 他のスクリプト（ファイル）で定義されたプロシージャは Include コマンドで取り込むことができる。

プロシージャー呼び出しには、以下のようにスペースで区切られたパラメータをいくつでも渡すことができる：

<procedure_name> parameter1 "parameter2 with spaces" ... parameterN

パラメータは、'0', '1' ... 'N'という名前の変数として利用できる。インデックス0の最初の変数には、常にプロシージャー名が格納される。プロシージャが受け付けるパラメータは、プロシージャのヘッダのどこにも宣言されていないことに注意してください。

バージョン2.1以降、_PROCEDURE_ARG_COUNT 変数から多くの入力引数が利用できるようになった。これらは、パラメータの数に応じて動作を分岐させたり、省略されたパラメータにデフォルト値を代入したりするために使用されます。

次の例は、可変画像フォーマットでスクリーンショットを作成する簡単なプロシージャの書き方と呼び出し方を示しています。デフォルト値の代入（Var extension=png）は、パラメータ代入（Var extension={2}）の後に指定しなければならないことに注意してください。これは、正しいコマンド構文を検証するために、if/else構造に関係なくコンパイル時にすべての変数代入を実行するコンパイラの制限によるものです。

# プロシージャの定義。期待されるパラメータは以下の通り：
# 1} ... ファイル名(拡張子なし)
# 2} ... 画像の拡張子(jpg, jpeg, pngのいずれか).省略時のデフォルトは "png"。
procedure take_screenshot {
 Var  extension={2}
 if ({_PROCEDURE_ARG_COUNT} == 1) {
 Var extension=png
 }
  Screenshot {1}.{extension} desc="このスクリーンショットは {0} というプロシージャによって作成されました。"
}

take_screenshot image1 jpg
take_screenshot image2

プロシージャは常に、プロシージャ本体内で最後に実行されたコマンドの終了コードを返します。特定の終了コードでプロシージャを終了するには Exit コマンドを scopeラメータを procedure. 例を以下に示す：

# プロシージャの定義
Procedure exit2 {
 Exit 2 scope=procedure
}

# 手続き呼び出し
exit2

if ({_EXIT_CODE} == 2) {
# exit2 が 2 を返すため、ここにあるコードはすべて実行されます。
}

パラメータがないと、コードが正しいかどうかを判断できないため、プロシージャ定義時にプロシージャの内容がコンパイルされることはありません。T-Plan Robot Enterprise は、代わりにプロシージャ呼び出しをコンパイルします。例えば

take_screenshot image3 tiff

と入力すると、T-Plan Robot はこの行でエラーを報告します。なぜなら 'tiff' は Java がサポートしていない画像形式であるため、例のプロシージャ本体の Screenshot コマンドはコンパイルエラーを投げるからです。

2.5 フォールバック手順

T-Plan Robot Enterprise バージョン 2.3 では、いわゆるフォールバック手続きが導入されました。これは予約された名前の手続きで、特定の条件(イベント)が満たされたときに自動的に呼び出されます。フォールバック手続きは、それ以外は標準的な手続きであり、一般的な手続き規則がすべて適用されます。above が適用される。要するに、(1)名前の大文字と小文字は区別されない。Include または Run (3)プロシージャは、それを呼び出すコードの前に定義されていなければならない。

• DisconnectFallback と 呼ばれるプロシージャは、VNCサーバへの接続がクラッシュしたときに、initフェーズ（コマンドの内部）か、それ以降に呼び出されます。Connectコマンドの内部)、またはサーバが終了(kill)したときやネットワークエラーが発生したときなど、それ以降の任意のタイミングで呼び出されます。コマンドの呼び出しは Disconnect コマンドの呼び出しは、予期された接続の終了であるため、プロシージャを開始しません。Connectがフォールバック・プロシージャ本体で呼び出された場合、無限接続ループを防ぐために、失敗時にプロシージャを再度呼び出すことはありません。スクリプト実行中の通常操作フェーズで接続のクラッシュが検出されると、現在実行中のコマンドが終了した直後にプロシージャが呼び出されます。このような場合、サーバーに正しく転送されたデータの範囲が不明なため、プロシージャを安全なリカバリ（再接続とスクリプトの再開を意味する）に使用できない可能性があることに注意してください。これは、例えばテキスト入力の途中でクラッシュが発生し、接続に失敗する前に何文字が正常に入力されたかを判断できない場合に問題となります。

• ComparisonFailureFallbackと 呼ばれるプロシージャが Compareto Command または Waitfor Command のマッチ/ミスマッチが失敗し、onfail または ontimeout パラメータで明示的なフェイル・アクションが指定されていない場合に、ComparisonFailureFallback と呼ばれるプロシージャが実行されます。プロシージャ本体内で"{1}"として取得できる最初のプロシージャ引数には、常に呼び出し元の比較コマンドの数値終了コードが含まれます。これは通常、オブジェクトが見つからない場合は "1"、1つ以上のテンプレート画像が見つからないか、読み取ることができない場合は "2 "となります。

次の例は、フォールバック手続きの使用方法を示しています。どちらも単に特定の終了コードでスクリプトを終了します。比較の方は、さらに、後でデバッグできるようにスクリーンショットを作成します。この例は、他の適切なアクションを実行するように簡単に拡張できる。Sendmail コマンドによる電子メールの送信や Pause.

Procedure DisconnectFallback {
 Exit 3
}

Procedure ComparisonFailureFallback {
 Screenshot comparison_failure.png
 Exit {1}
}

// スクリプト本体
Connect localhost:1 password=welcome
Compareto button.png method=search
// ...

バージョン 7.2.4 では、BrowserFailureFallback プロシージャがサポートされました。スクリプトで定義すると、ブラウザのopen/find/closeコマンドが失敗するたびに呼び出されます。これは、3つの追加引数を公開します：

{1} はコマンドの数値終了コード、
{2} は操作を示します。これは、無関係な呼び出しを除外するために使用できます。

• 失敗したコマンドが "Browser open/close" の場合、"open" または "close" に設定される。

• 失敗したコマンドが "Browser find " で、"elaction" パラメータが指定されていない場合、引数は "find" に設定される。

• そうでなければ、引数は失敗したエレメントアクションを指定します。"click"、"submit"、"clear"、"type"、"select" のいずれかです。

{3} はエラーメッセージで、通常は実行ログに記録されるものと同じです。

以下はその例です（Chromiumプラグインが必要です）：

Procedure BrowserFailureFallback {
  Log "Failed action: {2} (exit code: {1})"
  Log "Reported error: {3}"
}

Browser open url="https://www.t-plan.com" browser="chromium"

// このコマンドは、間違ったボタンテキストに対して失敗し、"BrowserFailureFallback "プロシージャを呼び出します。
Browser find class="elementor-button-text" text="Why T-Plans" timeout="5s"

2.6 数値表現

数値式は v1.3 からサポートされている。

浮動小数点変数は英語形式（例：「1.25」）で記述してください。

'5s'(5秒)のような時間変数は、time修飾子が式の最後にある場合を除き、受け付けられない。例

• 正解：Wait 5+5s

• 不正解：Wait 5s+5s

サポートされている数値演算子

• 括弧 '(' および ')'

• プラス '+'

• マイナス '-'

• 単項マイナス '-' (負の数)

• 乗算 '*'

• 除算 '/'

• モジュロ除算 '%'

• 累乗演算子 '^'

数値式は、言語内で数値を表す場所であればどこでも使用できます。

# 1 時間待つ - ミリ秒単位
Wait "1*60*60*1000"

# 画像を検索し、その左上隅から10ポイント離れた位置をクリックする
Compareto "pattern.png" method="search2"
Mouse click to="x:{_SEARCH_X}+10,y:{_SEARCH_Y}+10"

数値式に基づいて変数を定義するには Eval コマンドの代わりに Var 例えば、'Eval HOUR_IN_MS=1*60*60*1000'である。

2.7 ブール式

論理式はif/elseやforのような構文を容易にします。以下の演算子がサポートされています：

• 括弧 '(' および ')'

• 大'>'、大 '>='、小 '<'、小'<='。これらの演算子は数値引数を必要とする。

• '==' と等しく、'!=' または'<>'と等しくない。引数の少なくとも1つが数値でない場合（二重引用符で囲まれた文字列）、プレーンな文字列比較が実行される。例

  • 'yes == no' の結果は偽となる。

  • 'yes != no'の結果は真になります。

  • どちらの引数も数値に変換でき、数値が等しいので、'1.0 == 1' の結果は真となる。

• 演算子 '&&' と '||' - 論理的な "and" と "or"。これらの演算子はブール引数、つまり他の式を必要とする。例

  • 式 '1 > 0 || yes != no' は、2つの式のどちらかが真であるため、真となる。

  • 式 '1 > 0 && yes != no' は、一方の式が偽なので偽となる。

バージョン2.2以降では、変数の存在や文字列の比較を行う演算子もサポートされています：

• 単項演算子 'exists <variableName>' は変数の存在をテストする。例

  • 式 'exists _REPORT_FILE'は、スクリプトがReportコマンドでレポートを作成する場合に真になります。

• 演算子 'contains' は、最初の文字列引数がもう一方の引数を含むかどうかをテストします（大文字と小文字が区別されます）。例

  • 式 '"{_MACHINE}" contains "sourceforge"'は、接続されているVNCサーバー名に 'sourceforge' が含まれている場合に真になります。

• 演算子 'hasphrase' は、最初の文字列がもう一方の文字列を含むかどうかを検証します(7.2.2以降)。”contains” と似ていますが、改行や不要なスペースに寛容です。これにより、OCRで認識されたテキストを画面上で簡単に評価することができます。例

  • 式 '"{_TOCR_TEXT}" hasphrase "Hello world I am here"' は、複数行に分割されているか、複数のスペースが含まれているかに関係なく、先に実行された OCR の結果のテキストに指定されたフレーズが含まれていれば真になります。

• 演算子 'startswith' は、最初の文字列引数がもう一方の引数で始まっているかどうかをテストします（大文字小文字を区別します）。例

  • 式'"{_DISPLAY}" startswith "localhost"' は、接続されているVNCデスクトップ名が ‘localhost’ で始まる場合、例えば ‘localhost:1’ のように真になります。

• 演算子 'endswith' は、最初の文字列引数が他の文字列引数で終わっているかどうかをテストします（大文字と小文字を区別します）。例

  • 式'"{_DISPLAY}" endswith ":3"' は、接続されている VNC サーバーがポート 5903 で動作している場合 (これは通常、デスクトップ名の ':3' ディスプレイ番号で示されます) に真になります。

• オペレータ 'matches' は、最初の文字列引数をjava.util.regex.Pattern 準拠の正規表現と比較します。例

  • 例 '"{_DATE}" matches "201008[12][1-5]" は、現在の日付が2010年8月11日から15日の間、あるいは21日から25日の間にある場合に真

ブール式は、次の例に示すように、if/elseとfor構文でのみ使用されます。また、ブール式は Eval コマンドに渡すこともできます。

# リモートデスクトップ上の画像を探す
Compareto "pattern.png" method=search

# 画像が見つからなかった場合は終了します、
if ({_EXIT_CODE} > 0) { 
  Exit 1
}

詳細は If/Else Statement および For Statement の章をお読みください。

2.8 関数

関数はリリース5で導入された。これらの関数は、if/else文やfor文、コマンド、その他この仕様で数値表現をサポートするコマンド・パラメータなど、ブーリアン式や数値式が期待される場所であればどこでも使用することができます。 Eval コマンドや、この仕様で数値式をサポートしているその他のコマンド・パラメータなどです。関数名は大文字と小文字を区別しません。

例えば、以下のfor文は10回繰り返し処理を行います：

for (i=0; i<MAX(6,10,9); i=i+1) {
  ...
}

サポートされている関数（カスタム関数が必要な場合はサポートにお問い合わせください）：

2.9 If/Else ステートメント

T-Plan Robotは、Javaで使用されるものと類似した機能と構文を持つif/else文をサポートしています。フォーマットは次のとおりです

if (<boolean expression>) {
  <コマンド>
} else if (<Boolean Expressions>) {
  <コマンド>
} else {
  <コマンド>
}

'else if' と 'else' の分岐は任意である。else if'分岐の数に制限はないが、'else'分岐は1つだけとする。中括弧'{'と'}'は、上で表示したように、関連するif/else/else ifキーワードと同じ行になければならないことに注意。

構造化ブロック全体を終了させる右中括弧'}'は唯一の例外で、1行に1つでなければなりません。例

# リモートデスクトップ上の画像を探す
Compareto "pattern.png" method=search

# 画像が見つからなかった場合は終了します、
if ({_EXIT_CODE} > 0) {
  Exit 1

# 画像がそれ以上見つかった場合、スクリーンショットを撮り、HTMLレポートに警告を追加します。
} else if ({_SEARCH_MATCH_COUNT} > 1) {
  Screenshot unexpected.png
  Warning "予期せぬ動作 - テンプレート画像が {_SEARCH_MATCH_COUNT} 回見つかりました！" image=unexpected.png
}

If/Else Statement ステートメントは、他の構造化プログラミングと同じように、入れ子にしたり、他の構文と組み合わせたりすることができます。 For Statement 他の構造化プログラミング言語と同じように。

2.10 For ステートメント

T-Plan Robot Enterprise は for 文をサポートしており、特定の条件が満たされる限り、値の範囲を反復したり、ループしたりすることができます。for文には2つの一般的な形式があります。

1.条件付き for 文

for 文の最初の型は、指定された論理式の結果が真である限り実行されます：

for (<statement1>; <boolean expression>; <statement2>) {
    <コマンド>
}

ブール式はすべてのループの前に評価されるので、ループ内のコマンドは、式が最初からfalseであれば、まったく実行されない。

ステートメント1とステートメント2は Eval コマンドを使って評価され、'<変数>=<数値式>'のような構文になります。これらは空でも構いません。以下の例は等価であり、0から5までの変数'index'の値をループします：

for (index=0; {index}<6; index={index}+1) {
  Type {index}
}

Eval index=0
for( ; {index} < 6; ) {
   Type {index}
   Eval index={index}+1
}

バージョン2.3以降では、文のヘッダー内の変数呼び出しが中括弧を省略する、より単純な構文もサポートしている：

for(index=0; index<6; index=index+1) {
}

2.あらかじめ定義された値の集合を反復処理するfor文

この書式では、あらかじめ定義された値の集合を繰り返し処理することができる：

for <変数名> in <スペースで区切られた値のリスト> {
<コマンド>
}

次の例では、"I speak a English, Spanish, Brazilian Portuguese. "という文章を入力する。

Type "I speak "
for language in English Spanish "Brazilian Portuguese" {
    if ("{language}" == "Brazilian Portuguese") {
        Type "{language}." 
    } else {
        Type "{language}, " 
    }
}

変数で指定することもできる。バージョン3.0.1以降では、変数で指定したスペースを含む値をサポートしています。次のコードは、変数で値セットを指定した前の例を示しています。

変数呼び出しはダブルクォーテーションで囲んではならない。

Type "I speak " 
Var VALUES="English Spanish \"Brazilian Portuguese\""
for language in {VALUES} {
    if ("{language}" == "Brazilian Portuguese") {
        Type "{language}." 
    } else {
        Type "{language}, " 
    }
}

for文の実行は、コマンドによって中断することができる。Break コマンドで中断できる。現在のループは Continue コマンドでスキップできる。ループが入れ子になっている場合、break/continue コマンドは最も内側のfor文に適用されます。

次の例では、for 文と Waitfor Command を組み合わせて、リモートデスクトップが更新を停止するまで実行を継続する方法を示します。

# 無限ループ
for (; 0 == 0; ) {
# リモート画面が少なくとも20% 更新されるまで待つ。
# 10秒間更新されなかった場合、ループを抜けます。
 Waitfor update extent=20% timeout="10s" ontimeout="break"
}

2.11 返り値

v1.3 以降、すべてのコマンドは_EXIT_CODEという変数として利用可能な整数値を返す。0（ゼロ）は通常成功を意味し、それ以外の数値は失敗を意味する。定義された終了コードの値とその意味については、特定のコマンドのドキュメントを参照してください。

戻り値（「終了コード」とも呼ばれる）は、スクリプトの実行を制御し、予期される結果と予期されない結果の両方を処理する方法を定義するために効果的に使用することができます。例えば compareto コマンドは、例えば画像比較が成功した場合は0を返し、そうでない場合は0以外の値を返します。例えば Waitfor Command コマンドは、期待されるイベントを受信すると0を返し、タイムアウトに 達すると0以外の値を返します。 以下の例は、これらの戻り値の使い方を示しています。

# Alt+F2 でGnomeのプログラム実行ウィンドウを開く。
Press Alt+F2 wait=3s

# Gnomeテキストエディタを起動する
Typeline gnome-text-editor

# リモートデスクトップの更新を待つ
Waitfor update extent=30% timeout="10s"

# もし Waitfor が0以外の値を返した場合、タイムアウトに到達した # と判断されます。
# テキストエディタが開けなかった可能性がある
If ({_EXIT_CODE} > 0) {

# スクリーンショットを撮る
  Screenshot failure.png

# スクリーンショットをEメールでテスターに送る
  Sendmail to="tester@dummyserver.com" from="robot@dummyserver.com" server="http://mail.dummyserver.com" subject="Gnome editor failed to open!" attach="{_REPORT_DIR}/failure.png"

# 実行を一時停止し、テスターが修正するのを待つ
 Pause "Gnome テキストエディタの起動に失敗したため一時停止"
}

If/else、for、break 呼び出しは値を返さないことに注意してください。これらのコマンドの後に _EXIT_CODE 変数にアクセスすると、最後に実行されたコマンドの終了コードが格納されます。

2.12 Java コードブロック

JavaコードブロックはTPRスクリプトからJavaコードを直接呼び出すことを可能にする。これは、スクリプト言語にこだわりたいが、特定のカスタム機能が必要な場合をサポートするために設計されました。

Javaコードブロックを正しく動作させるには、"java -jar robot.jar"コマンドではなく、"java -classpath %26lt;libs> com.tplan.robot.ApplicationSupport" コマンドを使ってJDK上でRobotを実行するようにしてください。後者の構文は、環境によってはJavaコンパイラの'CLASSPATH'への入力に失敗し、Javaソースコードのコンパイルと実行に失敗します。詳細はリリースノートの startup chapter を参照してください。

Javaコード・ブロックの一般的な構文を以下に示します。import句のサポートはv2.2で提供されたことに注意してください。それ以前のバージョンでは、完全修飾名でクラスを参照するか、インポートを preferences.

java {
  <import clauses>
  <Java code>
} endjava

このような各ブロックは内部的に DefaultJavaTestScript クラスを拡張した Java スクリプトに変換され、ブロック内の Java コードはその test() メソッドに挿入されます。クラス・テンプレートは Java コード・ブロック構成で公開され、Preferences ウィンドウからカスタマイズできます。次の例はその例です：

java {
  import java.util.Date;
  System.out.println("Current date: "+new Date());
} endjava

import com.tplan.robot.scripting.*;
import java.io.*;
import java.util.*;
import java.util.Date;

public class SomeDynamicName extends DefaultJavaTestScript {
  public void test() {
    System.out.println("Current date: "+new Date());
  }
}

このメカニズムには、いくつかの実用的な影響がある：

• Java コードブロックは Java コンパイラへのアクセスを必要とするため、T-Plan Robot は Java Development Kit (JDK) 上で動作するか、有効な JDK インストールパス (v2.3.3 以降) で設定されている必要があります。もしツールがJava Runtime Environment (JRE)だけで動作し、JDKが利用できない場合、コンパイラはエラーを報告します。このドキュメントの第1章を参照してください。Release Notes 章を参照してください。

• スクリプト内でJavaコード・ブロックを使いすぎないようにしてください。スクリプトとツール全体のパフォーマンスが低下する可能性があります。プリコンパイルされたJavaコードの再利用可能なパラメトライズされた部分を作成したい場合は Run 機能を探します。

• デフォルトでは、テンプレートは com.tplan.robot.scripting、java.io、java.util パッケージのすべてのクラスをインポートします。他のパッケージのクラスを使いたい場合は、Javaコードの前に import 句を置きます。他の方法としては、完全修飾名（例えば java.awt.Point など）でクラスを参照するか、Java コード・ブロックの環境設定でクラス・テンプレートにインポートを追加します。テンプレートの方法を選択した場合は、スクリプトを別のマシンに移行するときに、必ずそれを再適用してください。

• 各 Java コード・ブロックはスタンドアロンのJavaクラスとして動作するため、あるブロックで作成されたローカル変数やオブジェクトは、別のブロックでは表示されません。複数の Java ブロックでオブジェクトを共有する必要がある場合は、それらをコンテキストに格納します。コンテキストは基本的にマップであり、スクリプトのコンパイルや実行の間ずっと存在し、重要なオートメーション・フレームワーク・オブジェクトへの参照を保持します。オブジェクトをコンテキストに格納するには getContext().put() を使用し、オブジェクトを取得するには getContext().get() を使用します。すでに存在するフレームワークオブジェクトの参照を上書きしないように、必ず一意のキーを使用してください。詳細については、ScriptingContext インタフェース仕様を参照してください。

• Javaコードブロックは、コンテキストのgetContext().getVariable()とgetContext().setVariable()メソッドを通して、TPRスクリプトとグローバル変数を共有することができる。コードブロックは DefaultJavaTestScript クラスを継承しているので、スクリプト言語のコマンドに対応するメソッドを呼び出すこともできる。

次の例では、変数の共有について説明します。スクリプトはまず、テンプレート・パスを "C:/templates" に設定します。Javaコードはコンテキストを通してパスを取得し、ディレクトリ内のすべての PNG ファイルをリストアップし、FILE<n> と呼ばれる番号付き変数として、ファイル・カウンタFILECNTとともにコンテキスト変数に格納する。TPR スクリプトが再開すると、リストされたファイルを繰り返し、各 PNG ファイルに対して画像比較を実行する。

Var TEMPLATE_DIR="C:\templates"

# この行はJavaコードによって入力される変数のダミー値を宣言します。
# コンパイラが for() ループやCompareToコマンドでエラーを報告するのを防ぎます。
Var FILECNT=0 FILE1=dummy.png

java {
  File files[] = getContext().getTemplateDir().listFiles();
  int i = 0;
  for (File file : files) {
    if (file.isFile() && file.getName().endsWith(".png")) {
      i++;
      getContext().setVariable("FILE"+i, file.getName());
      }
    }
  getContext().setVariable("FILECNT", Integer.toString(i));
} endjava

for (i=1; {i}<{FILECNT}+1; i={i}+1) {
  Compareto "{FILE{i}}" method=search
}

3.コマンド構文

3.1 デスクトップコマンド

3.1.1 ブラウザ

ブラウザ - Selenium 駆動のウェブブラウザを自動化します（v5 以降）。技術と設定ステップの概要は、別の document. コマンドは以下のアクションをサポートします：

• “browser_open” 選択されたウェブブラウザを開き、指定されたウェブページをロードします。ブラウザはローカルでもリモートでもかまいません（Selenium Grid、6.3以降でサポート）。バージョン 8 以降、コマンドは新しいタブやウィンドウを開くこともできます。

• “browser_find” 指定された条件でウェブページの要素（HTML タグ）を検索し、オプションのアクション（クリック、タイプ、サブミット、クリア）を適用します。

  • コマンドがアクションを指定せず、要素が見つからない場合は、スクリプトを続行します。検索結果（見つかった/見つからなかった）は、コマンドの終了コードと要素の属性を含む_WEB変数の存在によってスクリプトに示されます。

  • コマンドがアクションを指定し、要素が見つからない場合、スクリプトは終了します。この動作は Click コマンドと Drag コマンドと一致しています。

  • 要素が存在し、継続する場合にその要素にアクションを適用する "ようなアクションをスクリプトで実行するには、2つの "Browser find "コマンドを使用します。

• "browser_switch" は、タブやウィンドウを切り替えたり、それらを記述する変数を更新したりします。v8からサポートされています。

• “browser_close” タブ、ウィンドウ、あるいはブラウザ全体を閉じ、 Selenium セッションを終了します。

リリース 8 から、ほとんどのブラウザコマンド操作は、利用可能なタブとウィンドウを記述する変数のセットを次のように入力します。追加パラメータなしで "Browser switch" を実行することで、強制的に更新することもできます：

SYNOPSIS

ローカルブラウザ：

Browser open browser=<browser_code> [url=<web_page>] [args=<CLI_arguments>] [opt-<name>=<value>]

リモート・ブラウザ：

Browser open browserName=<browser_code> hub=<hub_address> [url=<;web_page>]

すでに開いているブラウザで新しい URL を開く：

Browser open url=<webpage> [target=<self|window|tab>]

*赤色は必須パラメータ

オプション

browser=<browser_code>

– ブラウザのコードネーム。現在サポートされている値は以下の通りです：

• "ie" - Microsoft Internet Explorer

• "edge" - Microsoft Edge

• "firefox" - Firefox (Gecko)

• “chrome" - Google Chrome

• "safari" - Safari（Mac OS X）

• "chromium" - プラグインのインストールが必要 Chromium Web Driver プラグインがインストールされている必要があります (v7.0+)

url=<ウェブページ>

• 読み込むウェブページ。例："https://www.t-plan.com"。

args=<CLI_引数>

• ブラウザの種類によってサポートされている場合、ブラウザプロセスに渡される CLI 引数。v7.0 からサポートされています。詳細は seleniumの説明を参照してください。

opt-<名前>=<値>

• ブラウザの種類がサポートしている場合に、ブラウザプロセスに渡されるプリファレンス値。v7.0 からサポートされています。例えば、Chromeは "download.default_directory" 環境設定を使ってデフォルトのダウンロードディレクトリを設定します。ダウンロードを C:\MyStuff にリダイレクトするには、opt-download.default_directory="C:\MyStuff" を 使用してください。

hub=<ハブアドレス>

• Selenium Grid の ハブアドレス。

ブラウザ名=%26lt;ブラウザ名

• ハブが認識するブラウザ名。

ターゲット=%26lt;自分自身|ウィンドウ|タブ

• 指定したウェブページを開く場所。"self" (現在のウィンドウで開く)、"window" または "tab" (新しいウィンドウ/タブで開く) のいずれか。デフォルト値は "self"。v8 以降でサポートされています。

Browser find  [timeout=<time_interval>]  [elaction=<action>]  [elnumber=<element_number>]  [eltext=<text>]  [elindex=<dropdown_item_index>]  [elvalue=<dropdown_item_value>] [continue=<true|false>]  [<attributes>]

オプション

timeout=<time_value>

– 要素を探し続けるオプションの時間。有効な time_values.

• タイムアウトが指定されていない場合、コマンドは要素を一度だけ探します。

• タイムアウトが指定され、それが0より大きい場合、コマンドは時間が経過するか要素が見つかるまで要素を探し続けます。

elaction=<アクション>

– 結果の要素に適用するオプションのアクション。検索によって複数の要素が生成された場合、elnumberパラメータを使用してターゲット要素を選択することができます。サポートされるアクションは以下の通りです：

• "click" - 要素をクリックします。リンクやボタンなどのクリック可能な要素にのみ適用されます。

• “type" -eltextパラメータで指定したテキストを入力します。text要素にのみ適用されます。

• "clear" - 要素のテキストをクリアします。text要素にのみ適用されます。

• "submit" - フォームを送信します。

• "select" - 表示テキスト（eltext）、項目インデックス（elindex）、または "option" HTMLタグの "value " 属性で指定された値（elvalue）のいずれかによって、ドロップダウン項目を選択します。

elnumber=<要素番号>

– elaction で指定されたアクションで対象とする要素の序数。デフォルト値は1です(最初の要素を使用します)。要素数が elnumber より小さい場合、コマンドはエラーを投げます。

eltext=<テキスト>

– elaction アクションが "type" の場合、パラメータはtext要素に入力するテキストを指定します。アクションが "select" の場合、パラメータは選択されるドロップダウンの可視テキストを指定するために使用されます。 elaction=type パラメータとともに使用する必要があります。

elindex=<dropdown_item_index>

– 選択するドロップダウン項目のインデックス。インデックスは0から始まります。”select" HTML タグで表されるドロップダウン要素にのみ適用可能。

elvalue=<ドロップダウン項目の値>

– 検索・選択されるドロップダウン項目の値。”option" HTMLタグの "value "属性で指定します。ドロップダウン要素（"select" HTML タグ）にのみ適用可能。

continue=<true|false>

– 失敗した場合の処理方法を指定します。要素が見つからず、このパラメータが指定されていないか false の 場合、コマンドはスクリプトを終了します。このパラメータがtrueの場合、スクリプトの続行が許可され、コマンドは0以外の終了コードを返します。

<属性>

• 次のような name=value ペアの形式の属性 (検索条件) のリスト：

• "xpath=<xpath_expression>" XPath式による検索を行います。このオプションを使用する場合、他の属性を指定することはできません。

• "css=<css_selector> CSS セレクタで検索します。このオプションを使用する場合、他の属性を指定することはできません。

• "id=<element_id>" 要素IDで検索します。

• "class=<class(es)>" CSS クラス、または要素が属するクラスの空白区切りのリスト。

• "tagname=<tag_name>" ”a", "div", "img" などの HTML タグ名。

• "text=<text>"正確な要素テキスト。

• "parttext=<partial_text>"-". テキストが指定された部分テキストを含む要素を検索します。要素のテキストは親要素に継承されるため、これらの基準は一意ではないことに注意してください。例えば、ページ全体のテキストを取得するには、"HTML" または "body" タグを検索します。

• "link=<link_text>" 指定されたテキストのリンクを検索する。

• "partlink=<partial_link_text>" テキストが指定された文字列を含むリンクを検索する。

• Selenium がサポートするパラメータに加えて、コマンドは任意の HTML タグの属性とその値を受け入れます。たとえば、フォームのボタンを名前で識別するにはname=<name> を使います。

HTML 属性の概要については Mozilla dev docs を 参照してください。属性のサポートはブラウザによって異なり、認識できないものもあります。

ブラウザスイッチ[id=<window_ID>] [title=<title_or_part>] [number=<window_number>] [url=<URL_or_part>] [continue=<true|false>] です。

• タイトル、URL、番号、ウィンドウIDのいずれか1つのパラメータで指定されたタブまたはウィンドウに切り替えます。識別パラメータが指定されない場合、コマンドは browser_vars.

OPTIONS

id=<ウィンドウID>

• ウィンドウ/タブID。Seleniumが各タブやウィンドウに割り当てる一意の文字列です。利用可能なIDは browser_vars.

title=<title_or_part>

• ウィンドウ/タブのタイトルまたはその一部。利用可能なタイトルの一覧は browser_vars を参照してください。タイトルの検索では大文字と小文字が区別されます。例えば、「Google」というタイトルのタブがある場合、title="Goo "を使ってそのタブに切り替えることができます。指定したタイトルに一致するタブが複数ある場合は、最初に見つかったタブが選択されます。一致するタブが見つからない場合、"continue=true "パラメータが指定されない限り、コマンドはスクリプトを終了します。

number=<ウィンドウ番号>

• 1(1)から始まるウィンドウ/タブの序数。ウィンドウの順番はSeleniumによって決定され、通常は作成された順番を反映します。現在利用可能なウィンドウの数は_BROWSER_WINDOW_COUNTによって反映されます。 browser_vars. 利用可能なウィンドウの数が要求された数より少ない場合、"continue=true" パラメータが指定されない限り、コマンドはスクリプトを終了します。

url=<URL_or_part>

• ウィンドウ/タブのURLまたはその一部。利用可能なURLの一覧は browser_vars を参照してください。検索では大文字と小文字が区別されます。例えば、"https://www.google.com" のタブがある場合、url="google "を使って切り替えることができます。指定したタイトルに一致するタブが複数ある場合は、最初に見つかったものが選択されます。一致するタブが見つからない場合、"continue=true "パラメータが指定されない限り、コマンドはスクリプトを終了します。

continue=<true|false>

• 失敗時の処理方法を指定する。ターゲットウィンドウまたはタブが見つからず、このパラメータが指定されていないか、falseの 場合、コマンドはスクリプトを終了します。このパラメータがtrueの場合、スクリプトの続行が許可され、コマンドは0以外の終了コードを返します。

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

オプション

scope=<タブ|すべて>

• 閉じるスコープ。all" はデフォルトで、ブラウザ全体 (すべてのタブとウィンドウ) を閉じ、Selenium 接続を終了します。tab "の値は、現在のタブまたはウィンドウだけを閉じ、残りのタブまたはウィンドウがない場合にのみ接続を終了します。

例

Browser open browser=edge url="https://t-plan.com"

3.1.2 コネクト

説明

Connect - デスクトップに接続する。プロトコル、ホスト名または IP アドレス、オプションのポートが引数 URL に指定されます。接続が確立されると、暗黙の変数_MACHINE と_DISPLAY の暗黙の変数が更新されます。

接続が確立されると DisconnectFallback Fallback Procedures を参照してください。

SYNOPSIS

connect <URL> [user=<user>] [password=<password>] [force=<false|true>] [onpass=<command>] [onfail=<command>] [params=<parameters>] [paramseparator=<delimeter>]

• 赤は必須パラメータを示す。

オプション

URL

-引数は既知の connectionmanager (v4.2以降)、または <protocol>://<host_or_IP>[:<port>] の形式で有効なURLでなければなりません。プロトコルは、サポートされているプロトコルコードのいずれかと等しくなければなりません。T-Plan Robotはデフォルトで7つのクライアント (プロトコル) をサポートしています：

1. RFB (Remote Frame Buffer) v3.3クライアント (プロトコルコード "rfb")。これはVirtual Network ComputingまたはVNCとしてよく知られています。このクライアントは互換性があり、TightVNC、RealVNC、UltraVNC などの RFB v3.3 準拠のVNCサーバーに接続できます。テスト環境は Release Notes#vnc ドキュメントを参照してください。クライアントの実装の詳細は vnc.

2. Static Image (プロトコルコード "file"; v2.2以降) では、ファイルから画像を読み込み、ライブデスクトップと同じようにテストすることができます。クライアントは、PNG、BMP、WBMP、GIF など、Javaに準拠したすべてのロスレス画像フォーマットをサポートしています。ファイルが更新されるとクライアントが画像を再読み込みするメカニズムがあるので、ファイルシステム内の画像にグラフィカルな出力を生成するアプリケーションのテストにも使用できます。接続 URL は "file://<image_path>" という標準的な形式で、相対パスや ZIP ファイルやJARファイルにバンドルされた画像を特別に扱います。詳細は staticimage.

3. Android over ADB（プロトコルコード "adb"、3.1以降）により、Android Debug Bridge（ADB）経由でAndroidデバイスを自動化できます。詳細は android.

4. ローカルデスクトップ（プロトコルコード「java」、3.2以降）では、ローカルデスクトップ上に表示されるアプリケーションやシステムコンポーネントを自動化できます。詳細は local.

5. iOS Mirror（プロトコルコード "apple"、3.3以降）では、AirPlayスクリーンミラーリングとVNCサーバーを組み合わせて、iOSデバイス（iPhone、iPad）を自動化できます。プレーンなVNC接続と比較して、このソリューションは画面パフォーマンスが非常に速く、ゲームやグラフィックプログラムなどのOpenGLコンテンツをサポートしています。詳細は ios.

6. iOS Over Xcode （プロトコルコード "xcode"、4.3.1以降）は、WiFiネットワークとLightning USBケーブルを介してMac OS Xマシンの両方に接続されたiOSデバイスの自動化を可能にします。詳細は xcode.

7. RDP Server （プロトコルコード "rdp"、4.3以降）は、Microsoft Terminal Servicesとしても知られるRDPプロトコルによる自動化をサポートします。詳細は rdp.

ポートが明示的に指定されていない場合、デフォルトはプロトコル固有のウェルノウンポートになります。例えば、RFB/VNCサーバーはデフォルトで5900番ポート、Java RMIは1099番ポート、RDP（Windows Terminal Services）は 3389 番ポートで起動します。Linux/Unix上で動作するVNCに接続したい場合、デフォルトのRFBポートはX-Windowsサーバーによって占有されているため、通常は5901以上のポートを指定する必要がある。

URL にプロトコルが省略されている場合、スクリプトのデフォルトはRFB（VNC）である。この場合、ポート番号は、ポート番号から5900を引いた表示番号として扱われる。直接ポートを指定する場合は、ダブルコロンで指定します。例えば、"localhost:1 "と "localhost::5901" の両方は、ポート5901 で動作する同じローカルVNCサーバーを参照します。標準的なURL形式の同じアドレスは、"rfb://localhost:5901" です。

user=<ユーザー名>
デスクトップを認証するためのユーザー名(ID)。このパラメータは将来の使用やサードパーティの拡張のために予約されており、現在サポートされているプロトコルでは使用されません。

password=<password>
デスクトップサーバーを認証するためのパスワード。サーバーがパスワードを必要としないように構成されている場合、このパラメータは無視されます。

force=<false|true>

同じサーバーとポート(ディスプレイ)がすでに接続されている場合、再接続は行われません(force=false)。現在の接続を強制的に終了してサーバーに再接続するには、このパラメータをtrueに設定します。デフォルト値は false です。

onpass=<コマンド>
。サーバーへの接続に成功したときに実行するコマンド。単一のコマンドでなければなりません。一連のコマンドを呼び出すには、プロシージャまたは後続のIf/Else Statementコマンドの終了コードをテストします。

onfail=<command>
-Connectが接続に失敗したときに実行するコマンド。単一のコマンドでなければなりません。一連のコマンドを呼び出すには、プロシージャまたは後続のIf/Else Statementコマンドの終了コードをテストする。

params=<param_name_and_value_pairs>
-カスタムクライアントパラメータのリスト。このオプションは、paramseparator オプションと一緒に、現在サポートされているプロトコルでは使用されておらず、将来の使用やカスタム拡張のために予約されています。これらは、サードパーティのクライアントプラグインへの汎用的なログインデータの転送をサポートするためのものです。リストには、カンマ(',')または paramseparator 引数で指定されたカスタムセパレータで区切られた、任意の数のパラメータ名と値のペアを含めることができます。

例えば、2つのパラメータ PARAM_A=value_A と PARAM_B=value_B を指定する場合、引数は "PARAM_A,value_A,PARAM_B,value_B" のようになります。
paramseparator=<delimeter>
-params 引数で指定されたパラメータ名と値のリストのためのオプションのセパレータ。指定しない場合、デフォルトはカンマ(",")。

戻り値

コマンドは、成功すると 0 (ゼロ) を返し、指定されていない理由で接続に失敗すると 1 を返します。UltraVNCサーバがMSログオンを要求するなど、サポートされていない認証方法で失敗した場合、コマンドは値10を返します。

例

Connect rfb://localhost:5901 password=テスト

Connect localhost:1 password=テスト

Connect localhost::5901 password=テスト

3つの例はすべて等しく、ローカルマシンのディスプレイ番号1（ポート5901）で動作するVNCサーバーに接続する。パスワード認証が期待される。これは、ポート5900が通常X-Windowsサーバーによって占有され、VNCサーバーが通常ポート5901以上で実行されるLinux/Unixシステムの典型的な例である。

Connect "Local VNC"

• で登録された "Local VNC "接続に接続する。connectionmanager. サーバーのURLとパスワードは接続記録から読み込まれます。

Connect rfb://mywindows.companyxy.com:5902 password=mypassword force=true onfail="exit 2"

-mywindows.companyxy.com というサーバー上で動作しているRFB（VNC）サーバーに接続する。ツールがすでにこのサーバーに接続されている場合は、セッションを終了して再接続する。接続に失敗した場合は、終了コード 2 でスクリプトの実行を終了します。

Connect File://C:￤Screen.png

• 指定された画像を読み込み、デスクトップの代わりに表示する。

Connect file://C:￤testdata￤mages￤images.jar!/data/screen.png

• 指定したJARファイル(ZIPも可)内の/data/screen.pngとしてzip圧縮された画像を読み込み、デスクトップの代わりに表示する。

Connect file://screen.png

• 指定された画像を読み込み、デスクトップの代わりに表示する。URLは相対URLのため、画像は製品のインストールパスから読み込まれます。

Connect file://{_SCRIPT_DIR}/screen.png

• このコマンドを呼び出しているスクリプトと同じフォルダにある画像を読み込んで、デスクトップの代わりに表示します。

Connect rfb://mywindows.companyxy.com:5902 password=mypassword force=true onfail="exit 2"

-mywindows.companyxy.comというサーバー上で動いているRFB（VNC）サーバーに接続する。ツールがすでにこのサーバーに接続されている場合は、セッションを終了して再接続する。接続に失敗した場合は、終了コード 2 でスクリプトの実行を終了します。

Connect adb://default

• USBケーブルでローカルPCに接続された最初のAndroidデバイスに接続する。

Connect adb://MB104PY14322

• 指定したシリアル番号のAndroid端末にUSBケーブルで接続する。

Connect java://localhost

• ローカルのデスクトップに接続します。

Connect apple://192.168.1.2:5901

-iOSデバイスに ios 接続する。この例では、デバイスがネットワークに接続され、指定されたIPアドレスを持ち、5901番ポートでVNCサーバーを実行していると仮定しています。

3.1.3 ディスコネクト

説明

Disconnect - デスクトップ・サーバとの接続を切断する。接続がない場合、コマンドは何もしません。接続が切断されると、定義済みの変数 _MACHINE と _DISPLAY はクリアされる。

利用方法

disconnect

戻り値

このコマンドは、切断に成功すると0（ゼロ）を返し、切断に失敗すると1を返す。

例

Disconnect

-現在接続しているデスクトップから切断する。

3.1.4 ジェスチャー

ジェスチャー - タッチスクリーンジェスチャーをデザインして実行します（v6.2以降）。これは、以下のようなモバイルデバイス接続でのみサポートされています：

• Android Over ADB

• xcode

このコマンドは以下の動作をサポートします：

• Gesture press 指定した位置で指を押したことをジェスチャバッファに記録します。

• Gesture Move 指定した指の新しい場所への移動（ドラッグ）を記録します。

• Gesture Release 指定した指のリリースを記録します。

• Gesture Save 指定した名前でジェスチャを保存し、ジェスチャバッファをクリアする。

• Gesture Execute 接続デバイス上でジェスチャを実行し、ジェスチャバッファをクリアする。

• Gesture Clear ジェスチャバッファをクリアして、新しいジェスチャを設計できる状態にします。これは保存されたジェスチャには影響しません。バッファはデフォルトで "ジェスチャ実行"および "ジェスチャ保存"によってバッファがクリアされるので、通常はこのコマンドは必要ありません。

典型的なジェスチャーのシナリオ

1. 押す」、「動かす」、「離す」のアクションを組み合わせてジェスチャーをデザインします。複数の指を使うジェスチャーは、常に並行して実行されます。例えば、1本指のL字ドラッグなどです：

   JS

   Gesture press finger=0 to=x:200,y:200
   Gesture move finger=0 to=x:200,y:500
   Gesture move finger=0 to=x:350,y:500
   Gesture release finger=0 

2. 一度だけのジェスチャーはすぐに実行され、破棄されることがあります：

   JS

   Gesture execute 

3. ジェスチャーを再利用したい場合は、まずジェスチャーを保存し、いつでも名前を付けて実行できます：

   JS

   Gesture save name=L-shape
   Gesture execute name=L-shape

4. 保存されたジェスチャーは、カスタム位置から開始することができます。 デフォルトのジェスチャー開始位置は、最も低い指IDの「プレス」位置です（通常は指番号0ですが、許可された範囲内で任意の指番号を付けることができます）。たとえば、この例では [200,200] です。350,200]より右から開始させるには、次のようにします：

   JS

   Gesture execute name=L-shape start=x:350,y:200

   移動したジェスチャーがスクリーンに収まることを確認してください。そうしないと、このコマンドはジェスチャをスクリーン境界にトリミングし、ジェスチャの機能を変更する可能性があります。

SYNOPSIS

press finger=<fingerID> to=x:<X-coordinate>,y:<Y-coordinate>
*赤い色は必須パラメータを示します。

オプション

finger=<指ID>

• 指のID。サポートされる指の最大数は接続とデバイスに依存しますが、通常は5以上です。

to=x:<X座標>,y:<Y座標>

• 指を押す位置。

move finger=<fingerID> to=x:<X-coordinate>,y:<Y-coordinate>
※ 赤色は必須パラメータです。

オプション

finger=<指ID>

• 指のID。サポートされる指の最大数は接続とデバイスに依存しますが、通常は5以上です。

to=x:<X-座標>,y:<Y-座標>

• 最後の位置から指を移動（ドラッグ）する場所。

release finger=<fingerID>
*赤い色は必須パラメータを示します。

オプション

finger=<指ID>

• 指のID。サポートされる指の最大数は接続とデバイスに依存しますが、通常は5以上です。

save name=<名前> clear=<true|false>
※ 赤色は必須パラメータを示します。

オプション

name=<name>

• ジェスチャー名。ジェスチャー名は大文字と小文字を区別します。同じ名前を繰り返し使用すると、元のジェスチャーが上書きされます。

保存されたジェスチャーは、「clear」アクションやパラメータによって消去されることはありません。作成した時点からスクリプトが終了するまで使用できます。環境用の標準ジェスチャのセットを作成するには、名前を付けたジェスチャのライブラリ（スクリプト）を作成し、スクリプトにリンクするには Includeまたは Runコマンドを使用してスクリプトにリンクします。

clear=<false|true>

• ジェスチャバッファをクリアして、新しいジェスチャを設計できるようにするかどうかを示します。クリアすると、これまでに記録されたすべての「押す」「動かす」「離す」アクションが破棄されます。保存されたジェスチャには影響しません。デフォルト値は 'true' (バッファをクリア) です。

ジェスチャの実行 name=<名前> start=x:<X-座標>,y:<Y-座標> duration=<時間> clear=<true|false> count=<数> wait=<時間>
*赤色は必須パラメータ

オプション

name=<名前>

• 実行するジェスチャー。スクリプトによって作成され、「Gesture save」によって保存された既存のジェスチャの名前でなければなりません。ジェスチャー名は大文字と小文字を区別します。

ジェスチャ名が指定されていない場合、コマンドはジェスチャバッファの内容を実行します、

start=x:<X座標>;,y:<Y座標>

• カスタム開始点からジェスチャを実行します。デフォルトのジェスチャ開始ポイントは、最も低い指IDの「押す」位置です（通常は指#0ですが、許可された範囲内で任意の指番号を付けることができます）。このパラメータを使用すると、画面上の別の場所からジェスチャーを実行できます。

再配置されたジェスチャーがスクリーンにフィットしない場合、コマンドはそれをスクリーンの境界線にトリミングします。これは予期しない結果につながる可能性があります。

duration=<時間>

• ジェスチャの継続時間。値はミリ秒か有効な時間でなければなりません。Time Values.デフォルト値は 500 ミリ秒 (0.5 秒) です。

clear=<false|true>

• ジェスチャバッファをクリアして、新しいジェスチャを設計できるようにするかどうかを示します。クリアすると、これまでに記録されたすべての「押す」「動かす」「離す」アクションが破棄されます。保存されたジェスチャには影響しません。デフォルト値は 'true' (バッファをクリア) です。

count=<数値>

• ジェスチャを実行する回数。デフォルト値は1（1回実行）。

wait=<時間>

• ジェスチャが実行された後に待つ時間。次のコマンドが「Wait <time>」であった場合と同じ効果があります。値はミリ秒数か有効な値でなければなりません。Time Values. デフォルト値は0（待機しない）です。スクリプトは、_GESTURE_WAIT 変数に希望の遅延を設定することで、デフォルト値を設定できます。

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

オプション

なし。

例

Gesture press finger=0 to=x:125,y:202
Gesture release finger=0 
Gesture save name=press
Gesture execute name=press duration=1s

– 指定した場所を1秒間長押しする。

Gesture press finger=0 to=x:300,y:200
Gesture press finger=1 to=x:100,y:500
Gesture move finger=1 to=x:500,y:500まで
Gesture release finger=1
Gesture release finger=0 
Gesture save name=rotate
Gesture execute name=rotate

• 一本の指を長押ししながら、もう一本の指をその下の水平方向にドラッグする。これは例えばGoogleマップを回転させます。

3.1.5 モバイル

モバイルコマンドは7.1からサポートされている。このコマンドは Android Over ADB および xcode 接続でモバイル固有の機能を提供します。

このコマンドは、別々の製品として提供されていた従来の Androidと iOSの 拡張機能（プラグイン）に取って代わるものです。その目的は、モバイルデバイスの自動化のための共通言語を提供し、プラグインのインストールによるオーバーヘッドを回避することです。iOSとAndroidのオペレーティングシステムの性質が異なるため、すべてのモバイルコマンド機能が両方の接続で同じようにサポートされているわけではありません。例えば、ファイルのダウンロードとアップロードはAndroidでのみサポートされ、キーボードマップの操作はiOSに固有です。両プラットフォームを対象とした単一のスクリプトを作成する場合は、本文書の機能互換性に関する注意事項に注意してください。

サポートされている操作の完全なリストは次のとおりです：

このコマンドは、レガシープラグインの拡張機能に加え、モバイル検索と呼ばれる新機能を提供します。これは、属性（テキスト、タイプなど）によってデバイス画面上のUIコンポーネントを特定し、そのプロパティを取得し、オプションでアクションを適用（クリック）することができます。これは、iOSとAndroidがXMLドキュメントの形でUIコンポーネントのツリーを取得する機能に基づいている。これは Browser コマンドがSelenium駆動のウェブブラウザでコンポーネントを特定するのとよく似ている。

• Mobile findの利点は信頼性である。とは異なり Image Search V2 (または Text OCR (“tocr”) と異なり、画面上の標準的なUIコンポーネントをより正確かつ確実に特定することができます。

• 欠点は、スピード （XML階層の検索が遅い）と、グラフィカル出力（ゲーム）やモバイルウェブブラウザコンテンツのようなカスタムコンテンツを識別できないことです。

コンポーネントを識別するために使用されるアルゴリズムは、次のような画像比較コマンドにもさらされます。 Compareto Command と Waitfor Command と呼ばれるメソッドとして"モバイル".passrate"パラメータは使用されず、このメソッドでは無視されます。将来のリリースで変更される可能性がありますが、"cmparea "も無視されます。

SYNOPSIS

Mobile alert action=get

-モバイルデバイスの画面上にアラートウィンドウがあるかどうかをテストする。

Mobile alert action=dismiss [button=<button>] [text=<text_to_type>] [accept=<true|false>].

• アラートを解除する。アラートがない場合は何もしない。

オプション

action=<get|dimiss>

• アラートアクション名。現在サポートされている値は以下の通りです：

• "get" - モバイルデバイスにアラートが表示されているかどうかをテストします。アラートがある場合、このメソッドは_MOBILE_ALERT_TEXT、_MOBILE_ALERT_BUTTON_COUNT、_MOBILE_ALERT_BUTTON[n]変数にアラートテキストとボタンの数、およびそれらのラベルを入力します。

• "dismiss" - アラートを終了します。オプションで、ボタン、テキスト 、およびaccept パラメータを使用してアラートを閉じる方法を指定できます。
  

button=<ボタン>

• アラートを解除するボタンの名前(オプション)。以前の「モバイルアラート action=get」の呼び出しによって_MOBILE_ALERT_BUTTON[n]変数に格納されたボタン名のいずれかを使用することができます。ボタンが指定されていない場合、コマンドは1つを選択します。

text=<text_to_type>

• アラートを解除する前にアラートのテキストフィールドに入力するテキスト(オプション)。アラートにテキストフィールドがない場合、このパラメータは無視されます。

accept=<true|false>

• ボタンが指定されていない場合、このパラメータを使用して、アラートを受け入れるかキャンセルするかを指定します。これはアラートに2つ以上のボタン（例えば「OK」と「キャンセル」）が含まれている場合にのみ考慮されます。このパラメータが省略された場合、コマンドはアラートを閉じる方法を選択します。

を返します：

get」アクションはアラートがあれば0を、なければ1を返します。dismiss "アクションは、アラートの解除に成功すると0を、そうでなければ1を返します。

Mobile app

アクティブな（現在表示されている）アプリケーションのIDを_MOBILE_ACTIVE_ID変数に取得する。

戻り値

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

Mobile find [timeout=<time_interval>] [action=<action>] [number=<element_number>]【continue=<true|false>】【<attributes>】。

• 端末画面上のUI要素を指定された属性で 検索 し、オプションでクリックする。要素の属性は、_MOBIlE _FIND接頭辞を持つ変数に格納されます。 クリックが必要な場合は、continueパラメータを使用して、要素が見つからないときにスクリプトをクラッシュさせるか、続行させるかを決定します。

要素検索アルゴリズムは、次のような画像比較コマンドにも公開されています。 Compareto と Waitfor. mobile "と呼ばれるメソッドを探してください。

オプション

timeout=<時間値>

• 要素を探し続けるオプションの時間。有効な time_values.

• タイムアウトが指定されない場合、コマンドは要素を一度だけ探します。

• タイムアウトが指定され、それが0より大きい場合、コマンドは時間が経過するか要素が見つかるまで要素を探し続けます。

action=<アクション>

• 結果の要素に適用するオプションのアクション。検索によって複数の要素が生成された場合は、numberパラメータを使用してターゲット要素を選択できます。サポートされるアクションは以下のとおりです：

• "click" - 要素をクリックします。リンクやボタンなどのクリック可能な要素にのみ適用されます。

number=<要素番号>

• actionで指定したアクションで対象とする要素の序数。デフォルト値は1(最初の要素を使用)。要素数がnumberより小さい場合、コマンドはエラーを投げてスクリプトを終了します。

continue=<true|false>

• 失敗した場合の処理方法を指定します。要素が見つからず、このパラメータが指定されていない場合、またはfalseの 場合、コマンドはスクリプトを終了します。このパラメータがtrueの場合、スクリプトの続行が許可され、コマンドは0以外の終了コードを返します。

<属性>

-属性（検索条件）のリスト：

• "xpath=<xpath_expression>" のようなname=valueペアの形式の属性（検索条件）のリスト。 XPath式による検索を行います。このオプションを使用する場合、他の属性を指定することはできません。

• "type=<button|input|text>" を指定します。 要素のタイプ。"button" (任意の認識されたタイプの標準ボタン)、"input" (編集可能なテキストコンポーネント)、または "text" (静的テキストを表示するコンポーネント) のいずれか。

• "text=<text>"正確には要素のテキスト。

• "parttext=<partial_text>"-". 指定された部分テキストをテキストに含む要素を検索します。上記のパラメータに加えて、コマンドは任意のUI階層ツリーの属性とその値を受け付けます。このような検索は、iOSまたはAndroidに固有のものとなります。例えば、現在Androidにフォーカスしているものを特定するにはfocused=trueを使用します。

を返します：

actionパラメータなしで呼び出された場合、このコマンドは少なくとも 1 つの要素が見つかれば 0 を返し、見つからなければ 1 を返します。特定された要素の数は _MOBILE_FIND_COUNT 変数に格納され、個々の要素の属性は
MOBILEFIND_ 接頭辞を持つ番号付き変数として公開されます。

actionパラメータが存在し、アクションが要素に正常に適用されると、コマンドは0を返す：

• continueが 指定されていないかfalseの 場合、コマンドはエラーを投げてスクリプトを終了します。

• continueがtrueの場合、スクリプトの実行は続行され、コマンドは 1 (要素が見つからなかった) または 2 (番号で指定した要素と一致する要素が見つからなかった) を返します。

Mobile install [file=<アプリファイル>］[reinstall=<true|false>]。

*赤色は必須パラメータ

• 指定されたローカルファイルからアプリケーションをデバイスにインストールします。成功すると、コマンドは _MOBILE_INSTALLED_ID 変数にアプリケーションIDを格納し、これを使用してアプリケーションを起動、終了、アンインストールします。

OPTIONS

file=<アプリファイル>

• Androidアプリケーション・ファイル（.apk）へのパス。

reinstall=<true|false>

• trueを指定すると、アプリがすでにデバイスに存在する場合、強制的に再インストールされます。

を返します：

コマンドは、正常に完了した場合は 0 を返し、そうでない場合はエラーをスローしてスクリプトを終了します。

Mobile keyboard action=get

• 変数 _MOBILE_KEYBOARD_VISIBLE にtrue/falseを代入し、ソフトキーボードが表示されているかどうかを示します。このコマンドは0を返すか、キーボードのステータスの決定に失敗した場合（サポートされていないOS、...）スクリプトを終了する。

Mobile keyboard action=show

-Androidのみ：デバイスにソフトキーボードを表示しようと試み、その結果を終了コードで示す。この機能は、編集可能なUIコンポーネントが現在フォーカスされているかなどの条件に左右されるため、失敗することが多いことに注意してください。結果のリターンコードを必ずテストしてください。コマンドは、キーボードのステータスを決定するのに失敗した場合（サポートされていないOS、...）、エラーを投げてスクリプトを終了することがあります。

Mobile keyboard action=dismiss [keys=<semicolon_separated_list>]を指定する。

• デバイス上に現在表示されているソフトキーボードの終了を試み、その結果を終了コードで示す。keysパラメータはiOSでのみ必要で、Androidでは不要で無視されることに注意してください。このコマンドは、キーボードの状態を判断できない場合（サポートされていないOSなど）、エラーを投げてスクリプトを終了することがあります。

Mobile keyboard action=load [file=<map_file>]。

-iOSのみ：保存されているキーボードマップを 読み込みます 。ファイルが利用できないか、形式が正しくない場合、コマンドはエラーを投げてスクリプトを終了します。

Mobile keyboard action=remap

-iOSのみ：現在表示されているソフトキーボードを即座にリマップします。ソフトキーボードが表示されていないか、予期しないエラーが発生した場合、コマンドはエラーをスローし、スクリプトを終了します。

*赤色は必須パラメータです。

オプション

action=<get|show|dismiss|load|remap>

• アクション名。"get"、"show"、"dismiss"、"load"、"remap "のいずれか。

file=<マップファイル>

• キーボードマップファイル (.keymap) へのパス。

keys=<セミコロンで区切られたキー>

• キーボードを閉じるためにタップするセミコロンで区切られたキー名のリスト。このパラメータはiOSでのみ必要で、Androidでは無視されます。

を返します：

返される終了コードとエラースローについては、各アクションの説明を参照してください。

Mobile kill [id=<application_id>] [force=<true|false>] [timeout=<time_interval>] [log=<true|false>]

-指定したアプリケーションを終了させるか、最終的にバックグラウンドに送る。

オプション

id=<アプリケーションID>

• アプリケーションID。iOSの場合はアプリケーションバンドル名で、例えばSafariブラウザの場合は"com.apple.mobilesafari "と なります。Androidでは、Chromeアプリの"com.android.chrome "の ようにアプリケーションパッケージのみ（"kill "アクションと "uninstall " アクション）、または "com.android.chrome/com.google.android.apps.chrome.Main "のようにパッケージの後にスラッシュとアクティビティ（"start " アクション）が続く。 アプリケーションIDが指定されていない場合、コマンドは、"Mobile install"（Androidのみ）の呼び出しによって最近インストールされたアプリケーション、または"Mobile app "の 呼び出しによって提供されたアプリケーションを強制終了します。 MOBILE_ACTIVE_ID変数).現在表示されているアプリを終了するには、"Mobile app "コマンドと"Mobile kill "コマンドを連続して使用します。アプリケーションIDが解決できない場合、コマンドはエラーを投げてスクリプトを終了します。

force=<true|false>

• trueを指定すると、コマンドはアプリを強制終了させようとします。内部実装はターゲットOSに依存するため、このフラグが無視されることもあります。デフォルト値はtrueです。

timeout=<時間値>

• シェルコマンドが終了するまでの待機時間(オプション)。有効なtime_values.シェルコマンドによってアプリが強制終了されるAndroidでのみ使用されます。iOSでは無視されます。

log=<true|false>

• trueを指定すると、デバッグのために操作の出力を実行ログに記録します。デフォルト値はfalseです。

を返します：

コマンドは 0 を返します。

Mobile orientation action=get

- MOBILE_SCREEN_ORIENTATION_NAME 変数と _MOBILE_SCREEN_ORIENTATION 変数に、現在の画面の向きの名前とコードを代入する。名前は「Portrait」（コード0）、「LandscapeLeft」（1）、「UpsideDown」（2）、「LandscapeRight」（3）。

Mobile orientation action=set [set=<オリエンテーション>］

• 赤は必須パラメータ

• 画面の向きを設定し、"get "アクションと同じ変数を入力する。

オプション

action=<get|set>

• アクション名。"get "または"set "のいずれか。

set=<オリエンテーション>

• 名前または数値コードで特定されるターゲット方向。使用可能な値は、"Portrait"(コード0)、"LandscapeLeft"(1)、"UpsideDown"(2)、および"LandscapeRight"(3)です。Androidは、画面の向きをジャイロスコープが示す向きにリセットする「Auto」（コード4）もサポートしています。

戻り値：

コマンドは 0 を返す。

Mobile pull [remote=<リモートファイル>] [local=<ローカルファイル>］

*赤色は必須パラメータ

-Androidのみ：デバイスからローカルファイルシステムにファイルをプル（ダウンロード）します。

オプション

remote=<リモートファイル>

• デバイス上のファイル。

local=<ローカルファイル>

• ローカルファイルシステム内のファイル。

を返す：

コマンドは成功すると0を返し、失敗するとエラーを投げてスクリプトを終了します。

Mobile push [local=<local_file>] [remote=<remote_file>]

*赤色は必須パラメータ

-Androidのみ：デバイスにファイルをプッシュ（アップロード）します。

オプション

local=<ローカルファイル>

• ローカルファイルシステム内のファイル。

remote=<リモートファイル>

• デバイス上のファイル。

を返します：

コマンドは成功すると0を返し、失敗するとエラーを投げてスクリプトを終了します。

Mobile shell [command=<command>] [remote=<remote_file>] [timeout=<time_interval>] [log=<true|false>]

*赤色は必須パラメータ

-Androidのみ：デバイス上でシェルコマンドを実行する。コマンド出力は_MOBILE_OUTPUT変数に格納される。

オプション

command=<コマンド>

• 実行するシェルコマンド。

timeout=<時間値>

• シェルコマンドが終了するまでの待機時間(オプション)。有効な time_values.

log=<true|false>

• trueを指定すると、デバッグのために操作の出力を実行ログに記録します。デフォルト値はfalse です。

を返します：

コマンドは成功すると0を返し、失敗するとエラーを投げてスクリプトを終了します。

Mobile start [id=<application_id>] [timeout=<time_interval>] [log=<true|false>]

• デバイス上でアプリケーションを起動する。タイムアウトが指定されない限り、アプリの起動コマンドはキックオフされますが、アプリが正しく表示されるかどうかを確認する努力は行われません。コマンドは終了コードによって、起動処理が正しく実行されたかどうかを示し MOBILE_OUTPUT変数にエラー出力を入力します。アプリが起動して画面に表示されたことを確認するには、タイムアウトパラメーターを使用します。

OPTIONS

id=<アプリケーションID>

• アプリケーションID。iOSの場合はアプリケーションバンドル名で、例えばSafariブラウザの場合は"com.apple.mobilesafari "と なります。Androidの場合は、パッケージの後にスラッシュとアクティビティが続く必要があります。AndroidでアプリケーションIDが指定されていない場合、コマンドは「Mobile install」の呼び出しによって最近インストールされたアプリケーションを起動します（IDは IDは_MOBILE_INSTALLED_ID変数から取得されます）。アプリケーションIDが解決できない場合、コマンドはエラーを投げてスクリプトを終了します。

timeout=<時間値>

• シェルコマンドが終了するまでの待機時間(オプション)。有効な time_values.

log=<true|false>

• trueを指定すると、デバッグのために操作の出力を実行ログに記録します。デフォルト値はfalseです。

を返します：

タイムアウトパラメータが指定されていない場合、または 0 に設定されている場合、コマンドはアプリケー ションをキックオフして 0 を返します。

タイムアウトが 設定されると、コマンドは、指定された時間内にアクティブなアプリと引数のidをテストすることで、アプリが起動し、画面に表示されていることを確認します。アプリが表示されない場合は、エラーがスローされ、スクリプトが終了します。

Mobile uninstall [id=<application_id>]

-Androidのみ：デバイスからアプリケーションをアンインストールします。操作に失敗した場合、_MOBILE_OUTPUT 変数にその理由が入力されます。

オプション

id=<アプリケーションID>

• アプリケーションID。Chromeアプリの場合は "com.android.chrome " の ようにAndroidアプリのパッケージのみ、または "com.android.chrome/com.google.android.apps.chrome.Main "のようにパッケージの後にスラッシュとアクティビティ（"start "アクション）が続く。アプリケーションIDが指定されていない場合、コマンドは「Mobile install」の 呼び出しによって最近インストールされたアプリケーションをアンインストールします（IDは 変数 _MOBILE_INSTALLED_ID から取得されます。).現在表示されているアプリをアンインストールするには、「Mobile app」と「Mobile uninstall id="{_MOBILE_ACTIVE_ID}"」の一連のコマンドを使用します。アプリケーション ID が解決できない場合、コマンドはエラーを投げてスクリプトを終了します。

を返します：

このコマンドは、成功すると 0 を返し、失敗すると 1 を返します。アプリ ID を解決できない場合、または予期しない I/O エラーが発生した場合は、エラーをスローしてスクリプトを終了します。

3.1.6 マウス

説明

Mouse - マウス・イベントを実行する。このコマンドは、マウス・ポインタの移動、マウス・クリック、マウス・プレス、マウス・リリース、ドラッグ、マウス・ホイール・イベントなど、さまざまなマウス・アクションを自動化することができる。このコマンドは、マウス押下、マウス移動、マウスリリースイベントのシーケンスで構成されるカスタムドラッグにも対応しています(2.0.2以降)。構成されたイベント（クリック、ドラッグ）が失敗する場合は、マウスコマンドの環境設定でキャリブレーションパラメータを確認してください。

現在のマウスポインタの座標は、スクリプトの_MOUSE_X and _MOUSE_Y dynamic variables を通して利用できます。

SYNOPSIS

mouse [<modifier_1>+...+<modifier_N>+] <event_id> [btn=<button_name>] [modifiers=<modifier_1>+...+<modifier_N>] [to=[x:<x>][,y:<y>]] [from=[x:<x>][,y:<y>]]  [center=[x:<x>][,y:<y>]]  [start=<number>]  [end=<number]  [count=<number>] [wait=<time>]

• 赤色は必須パラメーターを示す。

オプション

modifier

-Shift、Alt、Ctrlをプラス「+」記号で区切った任意の組み合わせ。

event_id

-サポートされるイベント

• • "move"、任意の移動先からターゲットポイントへのマウスポインタの移動、

  • "click"、指定されたマウスボタンを使用したターゲットポイントでの1回以上のクリック、

  • "press"、マウスボタンの押下（リリースなし）、

  • "release"、マウスボタンのリリース（論理的には、その前に押下イベントが必要）、

  • “drag” 指定されたマウスボタンを使って、任意の移動先からターゲットポイントまでマウスをドラッグする、

  • “swipe”、タッチディスプレイを持つデバイス(AndroidやiOSデバイスなど)のためにタイミングを調整したマウスドラッグ、

  • “wheelup”、1つまたは複数のマウスホイールの回転ステップを上向きにする(ホイールがユーザーから離れる方向に回転する)、”

  • “wheeldown”、1つまたは複数のマウスホイールの回転ステップを下向きにする(ホイールがユーザーに向かって回転する)、

  • "pinch"、2本の指がタッチスクリーン上で共有された中心点に向かって移動する1つ以上のピンチイベント（"pinch close "とも呼ばれる）。このイベントは特定の環境でのみサポートされています。ios接続タイプ、

  • "zoom"、2本の指がタッチスクリーン上の共有中心点から離れる1つ以上のズームイベント（"pinch open "とも呼ばれる）。このイベントは特定の環境でのみサポートされています。ios 接続タイプで接続されている T-Plan Server を実行している Apple iOS デバイスなどでサポートされています。

btn

-このパラメータは、クリック、プレス、リリース、またはドラッグするマウスボタンを識別するために使用されます。許可される値は"left"、"middle"、"right "です。

修飾子

-このパラメータは、マウスイベントの修飾子を指定する別の方法を提供する（もう1つの方法は、イベントIDの前に修飾子を置くことである）。値はShift、Alt、Ctrlの任意の組み合わせで、「Ctrl+Alt+Shift」のようにプラス「+」記号で区切って指定します。修飾子がイベント ID と一緒に指定されている場合は、このパラメータが優先されます。

to=[x:<x>][,y:<y>]

-ターゲット座標。

• • イベントが "move "の場合、マウスポインタの移動先（ターゲットポイント）を定義する。

  • イベントが "click"、"press"、"release"、"wheelup"、または "wheeldown "の場合、マウスポインタはまずこの位置に移動され、関連するアクションが実行されます。

  • アクションが "drag "または "swipe "の場合、マウスポインタは実際の位置から(またはfromオプションで指定された位置から)このターゲット位置までドラッグされる。

座標は'x:<x>,y:<y>' の書式を持ち、各座標はピクセル単位（例えば'x:225'）またはパーセント単位（例えば'x:23%'）で指定できます。x または y が省略された場合、現在のマウスポインタの位置が不足する座標の決定に使用されます。

from=[x:<x>][,y:<y>]

-開始座標。

• アクションが"drag "または"swipe "の場合、マウスポインタはこの位置からtoオプションで指定された座標までドラッグされます。

• イベントが"click"、"press"、"release"、"wheelup"、"wheeldown "の場合、このパラメータは無視されます。

座標は'x:<x>,y:<y>' の書式を持ち、各座標はピクセルで指定するか（'x:225'など）、パーセンテージで相対的に指定します（'x:23.5%'など）。相対座標が整数でない場合は丸められます。x または y が省略された場合、現在のマウスポインタの位置が不足する座標の決定に使用されます。

center=[x:<x>][,y:<y>]

-ピンチ/ズームの中心点(オプション)。ピンチ」および「ズーム」アクションにのみ使用されます。パラメータが省略された場合、アクションのデフォルトは画面中央になります。

座標は'x:<x>,y:<y>'の形式で、ピクセル単位（'x:225'など）または相対座標（'x:23.5%'など）で指定します。相対座標が整数でない場合は丸められます。x または y が省略された場合、現在のマウスポインタの位置が不足する座標の決定に使用されます。

start=<number> end=<number>

-ピンチ/ズームの開始距離と終了距離。pinch" と "zoom" アクションにのみ使用されます。パラメータは常に一緒に指定する必要があります。省略した場合、アクションは中心点の位置と現在のスクリーンサイズに基づいてデフォルト値を計算します。

距離は、ジェスチャーの開始時（"start"）と終了時（"end"）に指が何ピクセル離れているかを指定します。
イベントが "pinch "の場合、指が互いに近づくため、開始時の距離は終了時の距離よりも当然大きくなければなりません。
ズーム "イベントの場合は逆の設定が必要です。距離は、指が互いに近づきすぎないように（最低でも 30 ピクセル）、または画面の境界線に 10 ピクセル以上近づかないように指定する必要があります。

count=<数値>

-マウスイベントを何回実行するか。デフォルト値は1。この値はclick、wheel、pinch、zoomイベントでのみ意味を持ち、他のイベントタイプでは無視される。

wait=<time>

-イベント送信後の待ち時間。以下のコマンドが'Wait <time>' であった場合と同じ効果を持つ。値はミリ秒数か有効な値でなければならない。Time Values.デフォルト値は0（待機しない）である。スクリプトは、"Var _MOUSE_WAIT=1s" のように、_MOUSE_WAIT変数に希望する遅延時間を代入してデフォルト値を設定することができます。

RETURNS
コマンドは成功すると0（ゼロ）を返し、I/Oエラーなどで失敗すると1を返す。

例

Mouse click count=2

• 現在のマウスポインタ座標でマウスをダブルクリックする。

Mouse move to=x:25,y:122

• マウスポインタを指定された座標に移動する。

Mouse move to=x:{_MOUSE_X}+50

• マウスポインタを現在の位置から右に50ピクセル移動する。

Mouse drag from=x:10%,y:450 to=x:22.5%,y:450 wait=2s

• マウスポインタを指定された開始位置から目的位置までドラッグし、2秒間待ちます。x座標は相対形式で指定します。ディスプレイの解像度が例えば800x600ピクセルの場合、'x:10%'は'x:60'に、'x:22.5%'は'x:135'になります。

Mouse swipe from=x:161,y:124 to=x:161,y:226

• タッチスクリーンを開始位置から目的位置までスワイプする。

Compareto "icon.png" method=search onfail="Exit 1"
Mouse move to=x:{_SEARCH_X}+10,y:{_SEARCH_Y}+10
Mouse press 
Mouse move to=x:{_SEARCH_X}+110 wait=500
Mouse release

{画像比較によって位置が特定されたオブジェクトに適用される「合成ドラッグ」の例。スクリプトはまず、icon.png テンプレートで表されたオブジェクトをデスクトップから探します。見つかったら、マウスポインタをその領域（各方向にプラス10ピクセル）に移動させ、押下、移動、リリースイベントのシーケンスを使ってオブジェクトを右に100ピクセルドラッグします。

Mouse pinch

• 画面をピンチする。現在の接続がピンチをサポートしている場合、現在のアプリケーションがズームアウトされます。

Mouse zoom center=x:220,y:450 start=125 end=180

• 画面を拡大します。現在の接続がピンチに対応している場合、現在のアプリケーションを拡大表示します。このコマンドは、カスタム中心点と開始距離と終了距離を使用します。

3.1.7 ペースト

ペースト - システムのクリップボードを使ってテキストをペースト（挿入）します。キーボードでテキストを一文字ずつ入力する代わりに、このコマンドはテキストをクリップボードにコピーし、Ctrl+V（Mac OS XではCommand+V）を押してシステムの貼り付けアクションをトリガーすることをシミュレートします。これは、キーボードからテキストを入力するよりもはるかに高速です。Type/Typeline.

このコマンドは、以下のようなクリップボード操作をサポートしている接続を対象としています。local のようなクリップボード操作をサポートしている接続を対象とします。それ以外の接続の場合、コマンドは黙ってTypeコマンドの機能に戻る。

SYNOPSIS

paste <text>[wait=<time>] [count=<number>]

• 赤は必須パラメータを示す。

オプション

text

-貼り付けるテキスト。テキストにスペースまたは等号「=」が含まれる場合は、二重引用符で囲む必要があります。 「これはスペースを含むテキストです。」テキストに二重引用符文字を含める必要がある場合は、その前にバックスラッシュを置きます。 「これは二重引用符 - \"" です。バックスラッシュの後に二重引用符を表示する必要がある場合は、「\\"」を使用します。 "これはバックスラッシュの後に二重引用符が続きます - \\""。

サポートされているテキスト文字は、デスクトップクライアント（プロトコル）によって制限されます。たとえば、RFB（VNC）プロトコルは、Latin-1（ISO 8859-1）文字セット以外の文字を転送できません。逆に、ネイティブJavaクライアントは、文字セットに関係なく、ローカルのキーボードで生成できる文字だけを転送することができます。詳細については、特定のクライアントのドキュメントをお読みください。

wait=<time>

-テキストが貼り付けられた後の待ち時間。これは、次のコマンドが 'Wait %26lt;time%26gt;' であった場合と同じ効果を持つ。値はミリ秒数か有効な値でなければならない。Time Values.

count=<数値>

-コマンドを何回繰り返すか。デフォルト値は1 (1回だけ貼り付ける)。

戻り値

コマンドは成功すると0（ゼロ）を返し、I/Oエラーなどで失敗すると1を返す。

例

Paste "hello world!"

-'hello world!' を貼り付ける。

3.1.8 プレス

説明

Press - キーをデスクトップに送る。キーボードのキーを押すことに似ている。

SYNOPSIS

press [<修飾子_1>+...+<修飾子_N>+]<キー｜修飾子> [location=<standard|numpad|left|right>] [release=<true|false>] [count=<number>] [wait=<time>]

• 赤は必須パラメータ

オプション

key

-押すべきキーボードのキーの名前。ほとんどのキー名はキーボードに書かれているものに対応しています。例えば'A'、'Insert'、'Tab'などです。キーは修飾子のみで構成されることもあります。キーの大文字と小文字は区別されず、どのような文字でも指定することができる。

キー名は、java.awt.event.KeyEventクラスで宣言されているVK_キーコード定数から内部的に派生します。例えば、VK_ENTER定数があるので、キー名は "ENTER"、"Enter"、"enter "となります。キー名は実行時にJava Reflection APIを使用してKeyEventクラスから抽出されるため、T-Plan Robotを実行するJavaのバージョンによってサポートされるキーの範囲が異なる場合があります。サポートされるキー名の完全な マップは Supported Keys Window.

キーの前には、プラス「+」記号で区切られたShift、Alt、Ctrl修飾子の任意の組み合わせを付けることができます（例：「Ctrl+Alt+Delete」）。修飾名は大文字と小文字を区別しません。

修飾名は特定の物理キーに対応するものであり、それらが表す文字に対応するものではないことに注意してください。例えば、標準的な「-」マイナスキーを押すと、数字キーとは異なる内部キーコードが生成される。これらの2つのケースは、「Press -」（標準）と「Press SUBTRACT location=numpad」（numpad）という2つのPressコマンドでも表すことができる。ほとんどの場合、ターゲットシステムはこれらを同じように解釈するが、失敗する場合もある。例えば、コントロールプラス（「Press Ctrl++」）は、[Press Ctrl, Press '+', Release '+', Release Ctrl]というシーケンスとして生成される。このようなキーの組み合わせは、標準の'+'ASCII文字(0x2b)を取得するためにShiftキーも押す必要があるUSキーボードでは作成不可能であるため、このシーケンスはデスクトップによって正しく解釈されるかもしれないし、解釈されないかもしれない。キーが認識されない場合は、代わりにテンキー（「Press Ctrl+ADD location=numpad」）を使ってみてください。特定のNumpadキーのキー名を取得するには、サポートされているキーウィンドウを開き、"Press a key... "テキストフィールドにフォーカスがあるときに押してください。location=numpadパラメータを指定することをお勧めしますが、指定しなくても動作します。

このコマンドは、2.0.3以降、キー名以外にほとんどのASCII文字も受け付けます。を押す "や"@を押す "のようなコマンドを使うことができる。さらに、localion="numpad" パラメータによって、これらの文字を数字キーボードにマッピングすることもできます。例えば、テンキーの "0 "キーを押すには、"Press NUMPAD0 "を呼び出す必要がありましたが、新しいバージョンでは、より直感的な "Press 0 location=numpad "もサポートしています。これは、ADD（プラス'+'）、SUBTRACT（マイナス'-'）、MULTIPLY（アスタリスク'*'）、DIVIDE（スラッシュ'/'）、DECIMAL（ピリオド'.'）、SEPARATOR（カンマ','）などの他のテンキーにも適用されます。

転送可能なキーとキーの組み合わせは、デスクトップクライアント(プロトコル)によって 適用される制限に従う。例えば、RFB (VNC)プロトコルは、Latin-1 (ISO 8859-1)文字セット以外の文字を転送できず、WinやContextMenuのようなWindowsネイティブキーのサポートは、一部の製品でのみサポートされています。逆に、ネイティブJavaクライアントは、文字セットに関係なく、ローカルのキーボードで生成できる文字だけを転送することができます。詳細は Release Notes や特定のクライアントのドキュメントを読んでください。

location=<standard|numpad|left|right>

-キーの位置。このオプションが意味を持つのは、一般的なキーボードに複数回存在するキーだけである。そのようなキーの例としては、数字キー '0'-'9' (標準の位置とテンキー) や修飾キー (キーボード左右の Ctrl と Alt) があります。サポートされている位置の値は、標準（デフォルト）、テンキー、左、右である。このコマンドは、[key,location]ペアが意味を持つかどうかを検証しないことに注意。例えば、アルファベット文字はほとんどのキーボードに一度だけ存在し、論理的に有効な位置はデフォルトの標準のものだけである。しかし、ほとんどのクライアントは、locationをヒントとしてのみ使用し、適用できないキーでは無視する。

release=<true|false>

-2.3.4からサポート。このパラメータがある場合、コマンドは完全なプレリリースシーケンスの代わりに、キープレス(release=false)またはキーリリース(release=true)だけを実行します。これにより、長いキー押下や、押下とマウスの複合イベントを自動化することができます。このパラメータを使って押下をシミュレートする場合は、キーが不要になったときに適切にキーをリリースするようにしてください。

count=<数値>

-キーを何回送るか。デフォルト値は1。複数の押下アクション間の遅延は、Press Command ユーザー設定の値によって定義される。

wait=<時間>

-イベント送信後の待機時間。このパラメータは、押されたキー/キーにサーバーが反応するまでに時間が必要な場合に便利です。これは、以下のコマンドが'Wait <time>'.値はミリ秒か有効な値でなければならない。Time Values.デフォルト値は0（待機しない）である。スクリプトは、"Var _PRESS_WAIT=1s" のように、_PRESS_WAIT変数に希望する遅延時間を代入することで、デフォルト値を設定することができる。

RETURNS
コマンドは成功すると0（ゼロ）を返し、失敗すると1を返す。

例

Press Ctrl+Alt+Del

• デスクトップで Ctrl+Alt+Del キーを押す。

Press Tab count=5 wait=2s

• Tabキーを5回押し、2秒間待ってから次のコマンドに進む。

Press Ctrl location=right

• 右のCtrlキーを押す。

Var KEY_TO_PRESS=Alt+F4
<...>
Waitfor update area=x:340,y:220,w:240,h:160 extent=80% timeout=10s ontimeout="Var KEY_TO_PRESS=Right"
Press {KEY_TO_PRESS} wait=2s

• この例は、不要なポップアップ・ウィンドウを解決する方法を示している。与えられた座標にウィンドウがポップアップしたら、'Press {KEY_TO_PRESS}''コマンドはAlt+F4を使って確実に閉じます。ウィンドウが表示されない場合、Altキーが押されますが、通常ウィンドウに害はありません。

3.1.9 タイプ、タイプライン

説明

Type, Typeline - デスクトップにテキストを入力する。Typelineコマンドはテキストを入力してEnterを押すだけの便利なコマンドである。これは'Type <text>' と'Press Enter' の組み合わせと同じ効果がある。

SYNOPSIS

type <text> [wait=<time>] [count=<number>]
typeline <text> [wait=<time>] [count=<number>]

• 赤い色は必須パラメーターを示す。

オプション

text

-入力するテキスト。テキストにスペースまたは等号「=」が含まれる場合は、二重引用符で囲む必要があります。 「これはスペースを含むテキストです。」テキストに二重引用符文字を含める必要がある場合は、その前にバックスラッシュを置きます。 「これは二重引用符 - "" です。バックスラッシュの後に二重引用符を表示する必要がある場合は、「\"」を使用します。 "これはバックスラッシュの後に二重引用符が続きます - \""。

サポートされているテキスト文字は、デスクトップクライアント（プロトコル）によって制限されます。たとえば、RFB（VNC）プロトコルは、Latin-1（ISO 8859-1）文字セット以外の文字を転送できません。逆に、ネイティブJavaクライアントは、文字セットに関係なく、ローカルのキーボードで生成できる文字だけを転送することができます。詳細については、特定のクライアントのドキュメントをお読みください。

wait=<time>

-テキストが入力されてから待つ時間。このパラメータは、押されたキーにサーバーが反応するまでに時間が必要な場合に便利です。次のコマンドが「Wait <time>」であった場合と同じ効果がある。値はミリ秒か有効な値でなければならない。time value. デフォルト値は0（待機しない）である。スクリプトは、_TYPE_WAITまたは _TYPELINE_WAIT 変数に希望する遅延時間を設定することで、デフォルト値を設定することができます。

location=<standard|numpad|left|right>

-キーの位置。指定すると、コマンドは入力された文字を指定されたキーボードの位置にマッピングしようとする。サポートされている位置の値は標準(デフォルト)、テンキー、左、右だが、このオプションが意味を持つのは、コマンドが受け付ける文字を含む唯一のキーボード部分であるテンキーだけである。

このパラメータのサポートは、モバイルデバイスのテストを容易にすることを意図している。モバイルデバイス（特に携帯電話）の数字キーは多くの場合テンキーにマッピングされており、Pressコマンドで各キー入力を処理するのは不便である。例えば、携帯電話で電話番号+0123456789を入力して電話をかけるには、単に「Typeline +0123456789 location=numpad」を使えばよい。

count=<数字>

-コマンドを何回繰り返すか。デフォルト値は1 (テキストを入力する/行を入力するのは1回だけ)。

戻り値

コマンドは成功すると0（ゼロ）を返し、I/Oエラーなどで失敗すると1を返します。

例

Type hello

• hello'とタイプする。

Typeline "mkdir /tmp/mydir" wait=2s

• アクティブな Linux/Unix ターミナルウィンドウでこのコマンドを実行すると、OS コマンド'mkdir /tmp/mydir'が起動し、次のコマンドに進む前に2秒間待つ。

Type "100*4" location=numpad

• 数字キーボードで数式を入力する。

Typeline "+111222333444" location=numpad

• 数字キーボードに数式を入力し、Enterを押す。テスト対象のシステムが、Symbian OSを搭載したNokia携帯電話など、テンキーにキーボードがマッピングされた携帯端末の場合、指定した番号に電話をかけます。

3.2 Administrative & Execution Control Commands

3.2.1 Alert

DESCRIPTION

Alert - Pop up an alert window on the local machine. The window can be customized to contain custom buttons and/or editable fields. It can also self-dispose after the specified time out.

The command populates these variables:

SYNOPSIS

Alert <text> [title=<text>]  [buttons=<list>]  [fields=<list>]  [values=<list>]  [timeout=<time_value>]  [location=x:<x_coord>,y:<y_coord>]  [size=w:<width>,h:<height>]
* Red colour indicates obligatory parameters

OPTIONS

<text>

- The text to display. If it starts with the <html> prefix it will be treated as HTML code.

title=<text>

- The window title (optional).

buttons=<list>

- The button label or a semicolon separated list of button names (optional). Name of the selected button is returned in the _ALERT_BUTTON variable. If the parameter is not specified the window will contain a single "OK" button.

fields=<list>

- A semicolon separated list of text field names (optional). This allows to design a query requiring the user to enter a value or a set of values.

values=<list>

- A semicolon separated list of values for the text fields specified in "fields" (optional). It should have the same length.

timeout=<time_value>

- The window disposal timeout (optional). It must be a time value. If not specified the window will keep displaying until closed by the user.

location=x:<x_coord>,y:<y_coord>

-Target location on the screen (optional), for example "x:100,y:100". Starting with 7.0.4 the X and/or Y coordinates may be also specified as percentages of the current screen size, for example "x:40%,y:35%". If the location is not specified the window gets centered on the screen.

size=w:<width>,h:<height>

- The window size (optional), for example "w:300,h:350". Starting with 7.0.4 the width and/or height may be also specified as percentages of the current screen size, for example "w:30%,y:10%". If the size is not specified the window will be sized to fit the content.

RETURNS

The command returns number of the selected button where the first button is 1.

EXAMPLES

Alert "<html><body><center><h1>Login</h1></center>Please enter your credentials:</body></html>" buttons="OK;Cancel" fields="User name;Password"
if ("{_ALERT_BUTTON}" == "OK") {
   Var user="{_ALERT_FIELD_1}"
   Var password="{_ALERT_FIELD_2}"
   // Login code here
}


- Example of a login window. The alert will look like:

3.2.2 Break

DESCRIPTION

Break - immediately terminate the innermost for loop and proceed to the first command after the loop's enclosing right curly brace '}'. If the command is used outside of a for loop it reports a syntax error.

To skip the current loop without breaking the for command use the continue command.

SYNOPSIS

break

RETURNS

The command doesn't modify the exit code and leaves its value on the one returned by the previously executed command.

EXAMPLES

# Infinite loop
for (; 0 == 0; ) {

    # Wait for at least 20% update of the remote screen.
    # If it doesn't update for 10 seconds, break the loop.
    Waitfor update extent=20% timeout="10s" ontimeout="break"
}

- Use a combination of for, Waitfor and break to hold on execution until the remote desktop stops to update.

3.2.3 Click

DESCRIPTION

Click is a combination of Waitfor match and Mouse click commands. It searches the desktop for a component image, a solid colour object or a text and clicks it. If the object is not found it exits the script.

SYNOPSIS

Click <comparison_method>  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [btn=<button>]  [modifiers=<modifiers>]  [count=<number>]  [wait=<time>]  [<method specific options>]
* Red colour indicates obligatory parameters

comparison_method

- Supported methods are:

• • 'image' - search for a component by the image or an image collection using the search2 method,
  • 'object' - search for a component by its colour using the object method,
  • 'ocr' - recognize text on the screen using OCR (the tocr method) and find the specified string or pattern.

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait for the component to appear on the screen at a maximum. The value must be either a number of milliseconds or valid time value. The default value is 30 seconds.

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

- The rectangular area of the desktop to limit the comparison to. If you omit this parameter the whole remote desktop will be processed. The area coordinates have the format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%"). If any of x, y, width or height are omitted, T-Plan Robot will use the full-screen values to determine the missing parameters (x:0, y:0, w:<screen_width>, h:<screen_height>).

number=<component_number>

- The number of the component on the screen to apply the click to. Components (objects) located on the screen are sorted in the reading order, from the top to the bottom and from the left to the right. The default value is 1 (click the first located component). If the number of components found on the screen is lower than the specified number the command exits the script.

move=[x:<x>][,y:<y>]

- Specifies the click location relatively from the centre of the target object (since 4.2). This allows clicking a nearby location instead of the object itself. If the comparison method is an image the parameter overrides the image click point and uses the image centre as the base point. For example, the command of "Click image template=button.png move=x:-40" will click 40 pixels to the left from the button centre.

btn=<button>

- The mouse button to click. Allowed values are "left", "middle" and "right".

modifiers=<modifiers>

- The mouse event modifiers (optional). The value may be any combination of Shift, Alt and Ctrl separated by the plus '+' sign, e.g. "Ctrl+Alt+Shift".

count=<number>

- How many times to click. The default value is 1.

continue=<number>

- The value of true will not terminate the script if the object is not found (since 4.2). The default value is false (terminate on failure). Since release 4.4.2 the command also observes the value of the _CLICK_CONNECT variable and uses it as the default value. For example, to make all Click commands in a script not terminate the script by default set the variable at the beginning to true ("Var _CLICK_CONTINUE=true"). 

step=<step_name>

- Simple integration with the Step command (since 4.2). When specified it creates a test step of the given name with the result of pass (object found and clicked) or fail (object not found).

wait=<time>

- Time to wait after the click. It has the same effect as if the following command was 'Wait <time_in_ms>'. The value must be either a number of milliseconds or valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _CLICK_WAIT variable with the desired delay, for example "Var _CLICK_WAIT=1s".

Click image template=<image_collection> [passrate=<pass_rate_in_%>]  [<search2_specific_params>] [<27459807>]

* Red colour indicates obligatory parameters

SPECIFIC OPTIONS - IMAGE

template=<image_collection>

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. Java 1.6 supports at least PNG, JPG, GIF and BMP.

Template images will be compared with the remote desktop image in the specified list order. If a template comparison produces a positive result (either match or mismatch depending on the specified event), the condition is considered to be met and the command finishes with an exit code of 0 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine the index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in%>_

- The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default search2 pass rate of 50% will be used.

search2_specific_params

- Any parameters supported by the search2 comparison method (optional).

Click object  [<object_specific_options>]  [<27459807>]

SPECIFIC OPTIONS - OBJECT

object_specific_params

- Any parameters supported by the object comparison method (optional). It is typically necessary to specify at least the object colour.

Click ocr  [<tocr_specific_options>]  [<27459807>]

SPECIFIC OPTIONS - OCR

tocr_specific_options

- Any parameters supported by the tocr comparison method. It is necessary to specify the target text to apply the click to either through the text or pattern options.

RETURNS

The command always returns 0 on success or exits the script on failure returning the error code from the specified comparison method.

EXAMPLES

Click image template="google_button.png" number="2"

 - Click the second button specified by the google_button.png image on the screen. If the button is not found or the number of buttons on the screen is lower than two the command will fail the script.  

Click object tolerance="10" color="255;0;0" max="w:20"

 - Click an object which is red and its width is not greater than 20 pixels. Tolerance ensures that the method will find more shades of red.

Click ocr text="Cancel" distance="1"

 - Read the text on the screen using OCR and click the word "Cancel". The distance ensures that the word will be found even if the OCR engine omits or fails to recognize a single character, for example, "Cancel" etc.

3.2.4 Compareto

Compareto - The Compareto command is intended to perform a one-time comparison of the current remote desktop image and a single image or an image collection using the specified image comparison method. An optional action may be executed based on the result either in the "onfail" and "onpass" parameters or through testing of the command exit code using an if/else structure. T-Plan Robot Enterprise 4.4.2Beta contains six image comparison methods which are in details described in the Image Comparison Capabilities chapter:

1. Image Search v2 ("search2", since v3.0) is the successor of the "search" method and performs a tolerant search of the desktop screen for the object represented by the template image(s).
2. Image search ("search", since v2.0) performs a tolerant search of the desktop screen for the object represented by the template image(s).
3. Object search ("object", since v2.2) searches objects on the screen by a single RGB colour or a range of similar colours.
4. Text OCR ("tocr", since 2.2) performs optical character recognition (OCR) on the desktop image using the OCR engine of choice.
5. Image-Based Text Recognition ("text", since 3.0) extracts text from the screen using a collection of pre-saved character images.
6. Histogram based comparison (code "default", since v2.0) is the legacy algorithm comparing histograms of the desktop image and the specified template image(s).

Besides the method-specific variables the command populates a set of COMPARETO prefixed variables as follows:

The command further supports one input variable which if defined controls the order of processing of the images loaded from image collections:

To make image comparison more reliable consider the factors listed in the Image Comparison Recommendations chapter. For information on how to set up a central point of failure for image comparisons see the ComparisonFailureFallback fallback procedure.

To display comparison result in the HTML report generated by the Report command use Screenshot. If you want to wait until the screen matches your template image, use 'Waitfor match'. Both Screenshot and 'Waitfor match' commands use the methods of the Compareto command internally and support the same parameters.

SYNOPSIS

compareto <image_collection> [passrate=<pass_rate_in_%>] [onpass=<command>] [onfail=<command>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]]  [<method_specific_params>]
* Red colour indicates obligatory parameters

OPTIONS

image_collection

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. Java 1.6 supports at least PNG, JPG, GIF and BMP.

Template images will be compared with the remote desktop image in the specified list order. If a template comparison produces a positive result (either match or mismatch depending on the specified event), the condition is considered to be met and the command finishes with an exit code of 0 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine the index of the matching template image. See 27459810 for a complete list of supported variables.

passrate=<pass_rate_in_%>

- The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default pass rate defined by the method or in the Robot preferences will be used (default values are 95% for the "default" and 100% for the "search" and "search2" methods).

onpass=<command>

- A command to be executed when the comparison succeeds (the selected method reports success). It must be a single command. To call a sequence of commands to use either a procedure or a  subsequent if/else construction testing the command exit code.

onfail=<command>

- A command to be executed when the comparison fails (the selected method reports failure). It must be one single command. If you need to define a sequence of command to be executed, use a procedure.

method=<comparison_method>

- The method (algorithm) to be used for image comparison. It must be one of the supported method names (codes) described in the Image Comparison Capabilities chapter or the name of a third party method enabled through the plugin interface. If omitted the command will use the default one.

methodparams=<custom_params>

 - Custom parameters to be passed to the image comparison algorithm. As the T-Plan Robot 2.0 default image comparison algorithms don't support any custom parameters, you don't need to specify this parameter unless you write your own algorithm.

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

- The rectangular area of the desktop to limit the comparison to. If you omit this parameter the whole remote desktop will be processed. The area coordinates have format of 'x:,y:,w:,h:', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%"). If any of x, y, width or height are omitted, T-Plan Robot will use the full-screen values to determine the missing parameters (x:0, y:0, w:, h:).

method_specific_params

- See the documentation of individual comparison methods for the list of supported method-specific parameters.

RETURNS

The command returns 0 (zero) when the comparison passes, 1 when it fails and 2 when the template image is not found or cannot be read.

EXAMPLES

Compareto netscape.png passrate=95% onfail="exit 1"

- Compare the image of the current remote desktop to image netscape.png using the "default" image comparison method. If there is not at least 95% match, terminate the script execution using the Exit command and return exit code 1.

Compareto button1.png;button2.png method=search
if ({_EXIT_CODE} == 0) {
  Mouse click to="x:{_SEARCH_X}+5,y:{_SEARCH_Y}+5"
}


- Search the remote desktop image for a button matching either button1.png or button2.png. If it is found, click on it. The command adds 5 pixels to the x and y coordinates to make sure you click in the middle of the button.

Compareto "search.png" method="search"
for (i=1; {i}<{_SEARCH_MATCH_COUNT}+1; i={i}+1) {
  # Nested variables compose the variable names of a suffix and an index
  Mouse click to=x:{_SEARCH_X_{i}},y:{_SEARCH_Y_{i}}
}

- Search the remote desktop image for an icon represented by the template image search.png and click onto each of the occurrences.

Var _TOCR_LINE_COUNT=0
Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22"
for (i=1; {i}<{_TOCR_LINE_COUNT}+1; i={i}+1) {
   Typeline "{_TOCR_LINE{i}}"
}

- Extracts text from the specified desktop area using OCR and types it onto the desktop.

Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22" pattern="[aA]pplication.*"
if ({_EXIT_CODE} > 0) {
  Exit 1
}


- Use regular expression to exit the script when the text recognized through Tesseract OCR doesn't start either with the 'Application' or 'application' word.

Compareto method="object" color="FF0000" draw="true"

- Find all solid colour red objects (RGB = (256, 0, 0)) on the screen and highlight them in the GUI.


Compareto circle.png method="object" color="00FF00" tolerance="100" passrate="80%" draw="true" rotations="30"

- Find all green-like objects which are at least 80% similar to the one in the circle.png image and highlight them in the GUI. The tolerance parameter defines the size of the palette of acceptable green colours. As the rotations parameter is set to 30, the algorithm will search the screen for objects rotated in 12-degree steps (360 degrees / 30).

3.2.5 Continue

DESCRIPTION

Continue - skip the current innermost for loop iteration. If the command is used outside of a for loop it reports a syntax error. Supported since 4.1.3.

To break (exit) the whole for loop use the break command.

SYNOPSIS

continue

RETURNS

The command doesn't modify the exit code and leaves its value on the one returned by the previously executed command.

EXAMPLES

# Increment X for each even loop (the resulting SUM will be 5)
Var SUM=0
for (i=0; i<10; i={i}+1) {
   if ({i} % 2 == 1) {
      continue
   } 
   Eval SUM={SUM}+1 
}

3.2.6 Date

DESCRIPTION

Date - Read, write and calculate dates. The command allows to take the current date or parse the input one, perform an optional time increase/decrease operation and save the result in the specified format to the _DATE variable or to the specified custom one.

The command populates these variables:

SYNOPSIS

date [date=<date>] [informat=<pattern>] [outformat=<pattern>] [add=<time_value>] [var=<name>] 

OPTIONS

date=<date>

- The input date string (optional). If not specified the command defaults to the current date.

informat=<pattern>

- A java.text.SimpleDateFormat compliant format to be used to parse the input date (optional). If not specified the command defaults to the _DATE format specified in the Language screen of the Preferences window.

outformat=<pattern>

- A java.text.SimpleDateFormat compliant format to be used to for the output date (optional). If not specified the command defaults to the _DATE format specified in the Language screen of the Preferences window.

add=<time_value>

- A time value to add to or subtract from the input date (optional). For example, the value of "-1d" will subtract one day.

var=<name>

- A variable name to save the output date to (optional). It defaults to _DATE.

RETURNS

The command returns 0 (SUCCESS) or 1 if the format is invalid or the input date failed to parse.

EXAMPLES

Date outformat="EEEE d MMMM y" var="TODAY"

- Save today's date in the specified format to the TODAY variable, for example "Wednesday 13 May 2020".

Date add="-1d" outformat="EEEE" var="YESTERDAY"

- Save the yesterday's day name to the "YESTERDAY" variable, for example "Tuesday".

Date date="2020-05-08T00:00:00.000Z" informat="yyyy-MM-dd'T'HH:mm:ss.SSS" outformat="d/M/y" var="ISODATE"

- Parse the specified ISO date and save it in a simple day/month/year format to the "ISODATE" variable.

3.2.7 Drag

DESCRIPTION

Drag is a combination of Waitfor match and Mouse drag commands. It searches the desktop for a source component by an image, by a solid colour or by a text and drags it to a location specified by relative coordinates or to the target component located by another image search. If the object is not found it exits the script.

The command is fairly similar to the Click one.

SYNOPSIS

Drag <comparison_method> [shift=x:<relativeX>,y:<relativeY>]  [template2=<target_component_template>]  [number2=<target_component_number>]  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [btn=<button>]  [modifiers=<modifiers>]  [count=<number>]  [continue=<true|false>]  [step=<step_name>]  [wait=<time>]  [<method specific options>]

* Red colour indicates obligatory parameters

comparison_method

- Supported methods are:

• • 'image' - search for a component by the image or an image collection using the search2 method,
  • 'object' - search for a component by its colour using the object method,
  • 'ocr' - recognize text on the screen using OCR (the tocr method) and find the specified string or pattern.

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait for the component to appear on the screen at a maximum. The value must be either a number of milliseconds or valid time value. The default value is 30 seconds.

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

- The rectangular area of the desktop to limit the comparison to. If you omit this parameter the whole remote desktop will be processed. The area coordinates have format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%"). If any of x, y, width or height are omitted, Robot will use the full-screen values to determine the missing parameters (x:0, y:0, w:<screen_width>, h:<screen_height>).

number=<component_number>

- The number of the source component on the screen to apply the drag to. Components (objects) located on the screen are sorted in the reading order, from the top to the bottom and from the left to the right. The default value is 1 (drag the first located component). If the number of components found on the screen is lower than the specified number the command exits the script.

move=[x:<x>][,y:<y>]

- Specifies the start mouse press location relatively from the centre of the target object (since 4.2). This allows to start dragging a nearby location instead of the object itself. If the comparison method is an image the parameter overrides the image click point and uses the image centre as the base point. For example, the command of "Drag image template=button.png move=x:-40 shift=x:100,y:100" will start dragging 40 pixels to the left from the button centre.

btn=<button>

- The mouse button to drag. Allowed values are "left", "middle" and "right".

modifiers=<modifiers>

- The modifiers to hold during the drag (optional). The value may be any combination of Shift, Alt and Ctrl separated by the plus '+' sign, e.g. "Ctrl+Alt+Shift".

shift=x:<relativeX>,y:<relativeY>

- Relative coordinates specifying where to drag the component to from its current location. The target (drop) location may be alternatively specified through template2.

template2=<target_component_template>

- The drop component. When specified the command performs an image search using search2 for the specified component and drags the object to its location. The number2 parameter may be used to specify the drop component number if there are more than one on the screen. When template2 is specified the shift parameter should not be present. 

number2=<target_component_number>

- Target component ordinary number. Components (objects) located on the screen are sorted in the reading order, from the top to the bottom and from the left to the right. The default value is 1 (drop at the first located component). If the number of components found on the screen is lower than the specified number the command exits the script. To be used only together with the template2 parameter.

continue=<number>

- The value of true will not terminate the script if the object is not found (since 4.2). The default value is false (terminate on failure). Since release 4.4.2 the command also observes the value of the _DRAG_CONNECT variable and uses it as the default value. For example, to make all Drag commands in a script not terminate the script by default set the variable at the beginning to true ("Var _DRAG_CONTINUE=true").

step=<step_name>

- Simple integration with the Step command (since 4.2). When specified it creates a test step of the given name with the result of pass (object found and dragged) or fail (object not found).

wait=<time>

- Time to wait after the click. It has the same effect as if the following command was 'Wait <time_in_ms>'. The value must be either a number of milliseconds or valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _DRAG_WAIT variable with the desired delay, for example, "Var _DRAG_WAIT=1s".

Drag image template=<image_collection>  [passrate=<pass_rate_in_%>]  [<search2_specific_params>]  [<864038892>]

* Red colour indicates obligatory parameters

SPECIFIC OPTIONS - IMAGE

template=<image_collection>

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. Java 1.6 supports at least PNG, JPG, GIF and BMP.

Template images will be compared with the remote desktop image in the specified list order. If a template comparison produces a positive result (either match or mismatch depending on the specified event), the condition is considered to be met and the command finishes with an exit code of 0 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine the index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in%>

 -The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default search2 pass rate of 50% will be used. 

search2_specific_params

 - Any parameters supported by the search2 comparison method (optional).

Drag object  [<object_specific_options>]  [<864038892>]

SPECIFIC OPTIONS - OBJECT

object_specific_params

 - Any parameters supported by the object comparison method (optional). It is typically necessary to specify at least the object colour.

Drag ocr  [<tocr_specific_options>]  [<864038892>]

SPECIFIC OPTIONS - OCR

tocr_specific_options

- Any parameters supported by the tocr comparison method. It is necessary to specify the target text to apply the click to either through the text or pattern options.

RETURNS

The command always returns 0 on success or exits the script on failure returning the error code from the specified comparison method.

EXAMPLES

Drag image template="lever.png" shift="x:100"

 - Find the first lever component on the screen and drag it 100 pixels to the right.

Drag image template="column.png" number="2" template2="column.png" number2="3"

 - Example of swapping of two table columns. The command will locate the second column header in the table and drags it onto the third one. If the column is not found or the number of columns on the screen is lower than three the command will fail the script. 

Drag object tolerance="10" color="0;255;0" max="w:20,h:20" shift="x:50,y:-100"

  - Find a green object which is not greater than 20x20 pixels and drag it 50 pixels rightwards and 100 pixels upwards. Tolerance ensures that the method will find more shades of green.

Drag ocr text="Flower" shift="y:220"

 - Read the text on the screen using OCR and drag the word "Flower" 220 pixels to the bottom.

3.2.8 Eval

Eval - Define a script variable where the value is evaluated as a numeric expression. See the Numeric Expressions chapter of this manual for more info. The behaviour is otherwise exactly the same as the Var command.

SYNOPSIS

eval <var_name_1>=<numeric_expression_1> \[<var_name_2>=<numeric_expression_2> ... <var_name_N>=<numeric_expression_N>\]

* Red colour indicates obligatory parameters

OPTIONS

var_name

 - A name for the variable. The name is case sensitive and must not contain spaces.

numeric_expression

- A numeric expression or a string which results in a numeric expression after all variable calls located in the argument are resolved. If it contains spaces it must be enclosed in double-quotes, e.g. "1 + 1". See the Numeric Expressions chapter of this manual for more info on expression syntax and supported numeric operators.

RETURNS

The Eval command in always returns 0 (zero) up to version 2.3.2. Version 2.3.3 and newer return 0 if the numeric expression was evaluated correctly or a value other than 0 if the expression could not be evaluated, for example when it contains the call of a variable which doesn't exist. This mechanism allows testing of whether the value was populated correctly and branch the code through the if/else statement checking the _EXIT_CODE variable value.

EXAMPLES

Eval POSITION=2*(10+1)

- Create a variable POSITION with a value of 22.

Eval SUM={SUM}+10
if ({_EXIT_CODE} != 0) {
   Exit 1
}

- Increase the existing variable of SUM by 10. If the variable doesn't exist the script will terminate with the exit code of 1.

Var A=1 B=2 C=3
// As Var resolves the variable calls and concatenates 
// the strings the ABC1 value will be a string of "123+1". 
Var ABC1="{A}{B}{C}+1"
// As Eval resolves the variable calls and evaluates the result 
// as a numeric expression the ABC2 value will be "124". 
Eval ABC2="{A}{B}{C}+1"


 - This example demonstrates the difference between how the Var and Eval commands construct the variable value.

3.2.9 Exec

DESCRIPTION

Exec - Execute an OS command on the local system (meaning on the machine which runs T-Plan Robot). The argument must be a single command, for example 'ls -l' on Unix/Linux. Due to a limitation of the interface between Java and the underlying OS pipes and redirection of the output are not allowed in the command. If you need to save the output to a file, use the outfile parameter. If you need to use pipes or redirection, put the command into a shell script or a batch file and make the Exec command call it instead.

If you need to execute a Windows command which is provided by the command line interpreter, you need to specify the interpreter in the Exec command. This applies to commands like dir, cd, copy, md, mkdir, rd, rmdir, del, erase etc. A complete list of commands depends on the Windows system and is available at the Microsoft site. Another good source is the COMMAND.COM page at Wikipedia. An example of running 'dir' on Windows would then looks like:

Exec "cmd.exe /C dir"

As each call to the underlying operating system requires some overhead, it is more efficient to create a shell script (Linux/Unix) or a batch file (.bat on MS Windows) where a sequence of OS commands need to be executed in one go. The following example shows the call of a batch file 'list.bat' located in the script directory on Windows. The batch file accepts a directory as a parameter and lists its contents into a file called dir.txt. Note that as the script path may contain spaces, it is necessary to enclose both the batch file and the parameter with double quotes which have to be escaped because they are inside a script command argument.

The list.bat file:

@echo off dir %1 > %1\dir.txt

The Exec call:

Exec "\"{_SCRIPT_DIR}\list.bat\" \"C:\Program Files\" "

Environment variables are visible to scripts in form of _ENV_ prefixed variables. You may see them for example in the Variables tab of the tool panel.

• Up to release 7.2.9 they are read only and any variable changes are not being passed to the process created by Exec.
• Starting with 7.2.10 you may set these variables for the process.

This example demonstrates setting of a variable on MS Windows. The echo command will print the variable value which will be logged to the execution log:

Var _ENV_Hello =Hello!
Exec "cmd /c echo Var Hello value: %Hello%"
Log "{_EXEC_OUTPUT}"

If you need to revert the change for the next process then simply delete the variable using "Varg delete":

Varg "delete" name="_ENV_Hello"
Exec "cmd /c echo Var Hello value: %Hello%"
Log "{_EXEC_OUTPUT}"

The Exec command populates four _EXEC prefixed variables as follows:

SYNOPSIS

exec <command> \[count=<number>\]  \[nowait=<false|true>\]  \[onpass=<command>\]  \[onfail=<command>\]  \[outfile=<file_name>\]  \[wait=<time>\]  \[kill=<process(es)>\]{_}  {_}\[autokill=<false|true>\]
exec kill=<process(es)> \[wait=<time>\]

* Red colour indicates obligatory parameters

OPTIONS

command

- The OS command to be executed on the local system. See the command description for OS-specific details.

count=<number>

- How many times to execute the command. The default value is 1 (execute once).

nowait=<false|true>

- A flag specifying whether Exec should make the script wait until the OS command finishes (supported since v3.4). The default value is false which makes it wait.

When the value is set to true the Exec command does not wait for the result and the script continues immediately after the process is started. The _EXEC_OUTPUT and _EXEC_ERROR variables are not populated because the output is not known when the Exec command returns the control to the calling script. The _EXEC_ERROR variable may be created if the underlying OS fails to start the specified command and reports it immediately to Robot.

onpass=<command>

- A T-Plan Robot command to be executed if the execution succeeds (when exit code 0 is returned). It must be one single command. If you need to define a sequence of command to be executed, use a procedure or an if/else construction based on the Exec command return value.

onfail=<command>

- A T-Plan Robot command to be executed if the execution fails (i.e. non-zero exit code is returned). It must be one single command. If you need to define a sequence of command to be executed, use a procedure or an if/else construction based on the Exec command return value.

outfile=<file_name>

- Optional file name to save the command output to. If you specify just the file name, it will be created in the current working directory (the directory where Robot was started from). To set the path relative to the script location or Robot's install directory use the _SCRIPT_DIR or _INSTALL_DIR variable. For example, to store the output file to the script folder use outfile="{_SCRIPT_DIR}\out.txt".

wait=<time>

- Optional time to wait after the command is executed. The default value is 0 (don't wait). Scripts may set the default value through populating of the _EXEC_WAIT variable with the desired delay, for example "Var _EXEC_WAIT=1s".

kill=<processes>

- Kill process(es) identified by the specified ordinary number or a semicolon-separated list of numbers. Supported since v3.5.2. Whenever the Exec command executes with nowait=true it gives the started process an ordinary number. The number can be then used to kill the process. Killing can't be applied to processes started without the nowait parameter or with nowait=false. Such processes are also not being numbered.

Numbering starts at 1. Complicated scripts which execute multiple calls of "Exec nowait=true" may learn the process number from the _EXEC_PROCESS_ID variable. Example:

// Start myapp.exe and save its ID
Exec "myapp.exe" nowait="true"
Var MYAPP_ID="{_EXEC_PROCESS_ID}"

...
Exec kill="{MYAPP_ID}"

NOTE: On Windows, it is only possible to kill the immediate child process using Exec Kill due to the way Windows OS internally organizes and accesses processes. Therefore, in order to kill sub (grandchild) processes please use CMD taskkill e.g.: Exec "cmd.exe /C taskkill /f /im <processName>".

autokill=<false|true>

- A flag specifying whether to kill the process after the script finishes (supported since v3.5.2). It is applied only to processes started with nowait=true. The default value is false (do not kill).

RETURNS

The command returns 0 (zero) if the command is successfully executed or the exit code of the OS command otherwise.

EXAMPLES

Exec "ls -l" 

- List the contents of the current directory (Unix/Linux). The listing will be available under the _EXEC_OUTPUT variable.

Exec "date" 
Screenshot image.png desc="This screenshot was taken on {_EXEC_OUTPUT}."

- Use the date OS command to insert a time stamp into a screenshot description (Unix/Linux).

Exec "C:\Program Files\Internet Explorer\iexplore.exe http://www.google.com/" 
Exec "rundll32 url.dll,FileProtocolHandler http://www.google.com/"

- Both commands should start Internet Explorer on Windows and open the Google site.

Report index.html 
Exec "mozilla file://{_REPORT_FILE}" 

- Create an HTML report and open it in a Mozilla browser on the local machine. The _REPORT_FILE variable is populated by the Report command and contains the full report file path.

// Directory to work with.
Var DIR=/tmp

// List the directory contents (Linux/Unix).
// For Windows replace the "ls" command with "cmd.exe /C dir /B"
Exec "ls {DIR}" 

// Split the directory listing by lines
String split "{_EXEC_OUTPUT}" pattern="\r?\n"

for (i=1; {i}<{_STRING_COUNT}+1; i={i}+1) {

  // Replace floating point from index (not needed on 2.3.3+)
  String replace "{i}" pattern="[.].*" replacement=""

  Var f="{_STRING{i}}"

  // If the file is a .png or a .jpg image display it for 3 seconds
  if ("{f}" endswith ".png" || "{f}" endswith ".jpg") {
    Connect "file://{DIR}/{f}" 
    Wait 3s 
  }
} 

- Perform an image slide show on a directory. The Exec command is here called to list contents of a directory which is then parsed using "String split" to individual files (one file per line is expected). The parsed strings (file names) are then checked for a known image extension and displayed in the Robot's desktop view for 3 seconds.

3.2.10 Exit

Exit - Terminate the script, procedure or structured block of code and return an exit code. If an exit command with the 'process' scope is called during script execution, it will terminate T-Plan Robot and return the indicated exit code to the underlying operating system. See the documentation on T-Plan Robot CLI Options and its automatic script execution examples for more information.

SYNOPSIS

exit  <exit_code_number>  [scope=<process|file|procedure|block>]  [desc=<description>]


OPTIONS

exit_code_number

- Mandatory exit code. It must be an integer. A value of zero is usually used to indicate success while non-zero values indicate an error or unexpected result or behaviour. If the command is called to terminate the whole script and there's a report file created by the Report command it will display the exit code of 0 as "passed/successful" and all other codes are presented as failures. The exit code is also passed to the underlying operating system and can be used to identify the reason for the script termination by third-party frameworks.

scope=<process|file|procedure|block>

- Controls scope of the exit command. The default value is a process which terminates the script execution. If the execution is an automated one and there are no more running automated processes, the command also terminates the JVM (Java Virtual Machine) and returns the specified exit code to the underlying operating system.

The file value terminates the currently executed file. If a script is being executed from another script using the Run command, only the called script is terminated and control is returned to the master script.

The procedure value exits from the innermost procedure. If no procedure is executed, the Exit command is ignored.

The block value exits from the innermost structured block of code, i.e. one of the if/else of for statements. If the command gets called out of any such a statement, it is ignored.

desc=<description>


- Optional description supported since v2.3. It is only used if the exit scope is not specified or is equal to the process. The command then saves the description under the _EXIT_DESC variable which is picked up and displayed by the reporting framework (such as the Enterprise Report Provider).

RETURNS

The command returns the exit code which is specified as its argument.

EXAMPLES

Exit 10

- Terminate the executed script and return 10 as the exit code.

Typeline myapplication 
Waitfor update extent=40% timeout=20s ontimeout="Exit 2" cumulative=true

- This is a typical usage of the Exit command. It shows a situation when you start a GUI application called myapplication from a terminal window. Let's suppose that the myapplication window has a fixed size equal to at least 40% of the screen size. If the GUI starts properly, the script will continue. The Waitfor command will otherwise wait for 20 seconds and then terminate the script with an exit code of 2.

3.2.11 Imagedoctor

DESCRIPTION

Imagedoctor - Control behaviour of the Image Doctor wizard. Supported since v3.5.

SYNOPSIS

include <action>
* Red colour indicates obligatory parameters

OPTIONS

action


- The action must be one of

• • • "on" - set on the Image Doctor,
    • "off" - set off the Image Doctor,
    • "skip" - make Image Doctor ignore eventual failure of the next image comparison command. This is equivalent to setting off Image Doctor before the command and setting it back on after it.

RETURNS

The command always returns 0 (zero).

EXAMPLES

Imagedoctor off

- Set off, Image Doctor. No image comparison failure will be processed until it gets set back on.

Imagedoctor skip
Compareto method="tocr" cmparea="x:33,y:2,w:200,h:22"
Compareto "search.png" method="search2"


- Make the Image Doctor wizard ignore eventual failure of the OCR. The second "search2" comparison is out of the scope of the "skip" action and it will be processed in case of failure provided that the Image Doctor is on.

3.2.12 Include

DESCRIPTION

Include - Include another script or compiled Java code.

When the argument is a TPR script in the language described by this document, the command will load ONLY procedures and variables from the script into the execution context and make them available to the calling script. This principle allows to build libraries with globally used variables and procedures and link them to scripts.

When the argument is a Java resource meaning a JAR or ZIP file or a classpath (directory structure containing .class files), the command adds it to the Java classpath and makes any compiled Java code it contains available for instantiation. This mechanism was introduced in v2.2 and it is intended to support dynamic loading of compiled Java scripts which may be subsequently called by the class name through the Run command.

Be aware that a dynamic update of the classpath affects the whole Java Virtual Machine (JVM) instance. If there are multiple automated testing processes, loading of such a resource makes its classes instantly available to all of them. If the file or path is already present on the classpath, the command does nothing and repeated calls of the same Include command cause no harm. Once the resource is loaded, eventual changes in the file system are not synchronized with the JVM. This means that it is not possible to apply changes to the resource code and recompile while Robot is running and it must be restarted to pick up any updates in the included library.

The name of the included file or path can be also specified dynamically through a variable. This eventually allows passing of the library name externally via the '-v' CLI option.

SYNOPSIS

include <file_or_Java_resource>
* Red colour indicates obligatory parameters

OPTIONS

file


- A TPR script file or a Java resource (JAR/ZIP file or a classpath) to be included. Filename can be either relative (e.g. sayHello.tpr) or absolute (e.g. /root/scripts/sayHello.tpr). T-Plan Robot will check if the file exists and is readable during every script compilation and report an error if not. The file can be also specified via a variable (see examples).

RETURNS

The command always returns 0 (zero). If the specified file is not found, T-Plan Robot reports a syntax error rather than returning a non-zero return value.

EXAMPLES

Include sayHello.tpr

- Load all variables and procedures from a script called sayHello.tpr which is located in the same directory as the script calling this command.

Include /root/scripts/sayHello.tpr

- Load all variables and procedures from a script called sayHello.tpr which is located in the /root/scripts/ directory.

Var PROFILE=profile1.tpr
Include {PROFILE}

- Include a script specified by a variable. If you have more scripts with different configurations, you may then include another script from CLI using '-v PROFILE=profile2.tpr'.

Include C:\projects\TestLib\testlib.jar
Run mypackage.MyTestScript

- Load a Java library (JAR file) from the specified location and execute a script from there. This presumes that the JAR file contains a package (directory) called "mypackage" with a compiled class called MyTestScript which is a valid Java script (it extends the DefaultJavaTestScript class or at least implements the JavaTestScript interface). See the Run command below for more information. 

3.2.13 MoveTo

DESCRIPTION

Similar to the Click command, MoveTo is a combination of Waitfor match and Mouse move commands. It searches the desktop for a component image, a solid colour object or a text and moves the mouse pointer to it. If the object is not found it exits the script.

SYNOPSIS

MoveTo <comparison_method>  [timeout=<time>]  [cmparea=<[x:<x>][,y:<y>][,w:<width>][,h:<height>]>]  [number=<component_number>]  [modifiers=<modifiers>]  [wait=<time>]  [<method specific options>]
* Red colour indicates obligatory parameters

comparison_method

- Supported methods are:

• • 'image' - search for a component by the image or an image collection using the search2 method,
  • 'object' - search for a component by its colour using the object method,
  • 'ocr' - recognize text on the screen using OCR (the tocr method) and find the specified string or pattern.

COMMON OPTIONS

timeout=<time>

- Timeout specifying how long to wait for the component to appear on the screen at a maximum. The value must be either a number of milliseconds or valid time value. The default value is 30 seconds.

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

- The rectangular area of the desktop to limit the comparison to. If you omit this parameter the whole remote desktop will be processed. The area coordinates have the format of 'x:<x>,y:<y>,w:<width>,h:<height>', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%"). If any of x, y, width or height are omitted the app will use the full-screen values to determine the missing parameters (x:0, y:0, w:<screen_width>, h:<screen_height>).

number=<component_number>

- The number of the component on the screen to move the mouse to. Components (objects) located on the screen are sorted in the reading order, from the top to the bottom and from the left to the right. The default value is 1 (click the first located component). If the number of components found on the screen is lower than the specified number the command exits the script.

move=[x:<x>][,y:<y>]

- Specifies the move location relatively from the centre of the target object. This allows to move the mouse to a nearby location instead of the object itself. If the comparison method is an image the parameter overrides the image click point and uses the image centre as the base point. For example, the command of "MoveTo image template=button.png move=x:-40" will move the pointer 40 pixels to the left from the button centre.

modifiers=<modifiers>

- The mouse event modifiers (optional). The value may be any combination of Shift, Alt and Ctrl separated by the plus '+' sign, e.g. "Ctrl+Alt+Shift".

continue=<number>

- The value of true will not terminate the script if the object is not found. The default value is false (terminate on failure). The command also observes the value of the _MOVETO_CONNECT variable and uses it as the default value. For example, to make all MoveTo commands in a script not terminate the script by default set the variable at the beginning to true ("Var _MOVETO_CONTINUE=true").

step=<step_name>

- Simple integration with the Step command. When specified it creates a test step of the given name with the result of pass (object found and the mouse pointer was moved to it) or fail (object not found).

wait=<time>

- Time to wait after the move gets completed. It has the same effect as if the following command was 'Wait <time_in_ms>'. The value must be either a number of milliseconds or valid time value. The default value is 0 (don't wait). Scripts may set the default value through populating of the _MOVETO_WAIT variable with the desired delay, for example "Var _MOVETO_WAIT=1s".

Moveto image template=<image_collection> [passrate=<pass_rate_in_%>]  [<search2_specific_params>] [<common options>]

* Red colour indicates obligatory parameters

SPECIFIC OPTIONS - IMAGE

template=<image_collection>

- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version. Java 1.6 supports at least PNG, JPG, GIF and BMP.

Template images will be compared with the remote desktop image in the specified list order. If a template comparison produces a positive result (either match or mismatch depending on the specified event), the condition is considered to be met and the command finishes with an exit code of 0 and skips any remaining templates in the list. Predefined variable _COMPARETO_TEMPLATE_INDEX may be then used to determine the index of the matching template image. See image comparison specific variables for a complete list of supported variables.

passrate=<pass_rate_in%>_

- The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted the default search2 pass rate of 50% will be used.

search2_specific_params

- Any parameters supported by the search2 comparison method (optional).

Moveto object  [<object_specific_options>]  [<common options>]

SPECIFIC OPTIONS - OBJECT

object_specific_params

- Any parameters supported by the object comparison method (optional). It is typically necessary to specify at least the object colour.

Moveto ocr  [<tocr_specific_options>]  [<common options>]

SPECIFIC OPTIONS - OCR

tocr_specific_options

- Any parameters supported by the tocr comparison method. It is necessary to specify the target text to move to either through the text or pattern options.

RETURNS

The command always returns 0 on success or exits the script on failure returning the error code from the specified comparison method.

EXAMPLES

Moveto image template="google_button.png" number="2"

 - Move to the centre of the second button specified by the google_button.png image on the screen. If the button is not found or the number of buttons on the screen is lower than two the command will fail the script.  

Moveto object tolerance="10" color="255;0;0" max="w:20"

 - Find a red object not wider than 20 pixels and move the mouse pointer to its centre. The tolerance ensures that the method will find more shades of red.

Moveto ocr text="Cancel" distance="1"

 - Read the text on the screen using OCR and move to the first word of "Cancel". The distance ensures that the word will be found even if the OCR engine omits or fails to recognize a single character, for example, "Cencel" etc.

3.2.14 Pause

DESCRIPTION

Pause - Pause the script execution. If T-Plan Robot is executing in GUI mode, the Pause button/menu item gets selected and the user can deselect the button or the menu item to resume the execution.

If the script is being executed in CLI mode, a message is printed out into the console and the user can press a key to resume the execution.

The Pause command can be used e.g. to pause execution when a runaway behaviour is detected.

Though the usual way is to exit the script with an error exit code (e.g. 'Exit 1'), some test suites may prefer to send an e-mail to the responsible person, pause the execution and wait for human help.

SYNOPSIS

pause <description> 


OPTIONS

description


- Optional description of the reason why the script was paused. This description will be displayed in the report (if defined) and printed out to the console in case of CLI mode execution.

RETURNS

The command always returns 0 (zero).

EXAMPLES

Compareto "application.png" 
if ({_EXIT_CODE} > 0) {
    # Cry for help - send a screenshot via E-mail and pause
    Screenshot runaway.png
  Sendmail to="tester@dummyserver.com" from="robot@dummyserver.com" server="mail.dummyserver.com" subject="Runaway behavior detected - see attached picture. Please help!" attach="{_REPORT_DIR}/runaway.png"
    Pause "Runaway behavior detected" 
}


- When image comparison fails, send a screenshot by E-mail to the tester and pause the execution.

3.2.15 Run

Run - Execute another script which may be one of:

1. TPR script in the format described by this specification (typically a .tpr file). T-Plan Robot will process its commands as if they were written in the calling script, which means that all procedures, variables, screenshots and report generators defined by the executed script will remain in the execution repository and can be accessed once the Run command finishes. Exit command with the scope set to file can be used to return from a script executed through Run to the main script.
2. Java source file (must be a .java file; supported from version 2.2). The class must be a valid T-Plan Robot Java script which extends the DefaultJavaTestScript class or at least implements the JavaTestScript interface. The Run command compiles the source code, instantiates the class and executes its test() method. As this call requires access to Java compiler, T-Plan Robot must run on Java Development Kit (JDK) or be configured with a path to the JDK installation supported since 2.3.3). If the tool runs just on Java Runtime Environment (JRE) and no JDK is available the tool will report an error. Refer to chapter 1 of the リリースノート document for instructions.
3. Java class name (supported from version 2.2). It must be a fully qualified Java class name (package+class name) corresponding to a valid T-Plan Robot Java script which extends the DefaultJavaTestScript class or at least implements the JavaTestScript interface. The class must have the default (parameterless), constructor. The Run command instantiates the class by name and executes its test() method. As this method doesn't involve compilation of Java code, it is very fast with a minimum performance overhead and it is recommended for production scenarios.
   The compiled class code must be placed on the T-Plan Robot classpath in one of the three supported ways:
   • Load the code (JAR, ZIP or classpath) through the Include command. This way makes the script load the code dynamically and make it available to the current Java/Robot instance.
   • Add the JAR, ZIP or classpath to the "-classpath" parameter of the Robot's start command described in the Release Notes. This will make the code available to the particular Java/Robot instance.
   • Put the JAR file with the code to <java-home>\lib\ext (Windows) or <java-home>/lib/ext (Linux/Unix) of the Java installation used to execute Robot. This will make the code available to any instance of Java started from this installation (and thus to all Robot instances as well).

Version 2.2 also delivers support of optional parameters in form of <name>=<value> pairs specified on the command line after the mandatory file/class argument. These parameters are exposed to the executed script as local variables which are valid only inside the executed script or Java class. In TPR scripts the parameters may be called by name as standard variables. On the side of Java code, they may be retrieved through the getContext().getVariable() method or through the set of convenience methods getVariableAsXXX() defined in the ScriptingContext interface.

Run commands can be effectively used to implement generic snippets of code (libraries) or to separate test code of individual test cases. The Java support enhancements delivered in version 2.2 allow to implement a library of parametrized Java routines and call them from TPR scripts. This is an efficient way of how to add custom functionality to the scripting language without having to go through the Plugin mechanism.

SYNOPSIS

run

run <file_or_class> [<param1>=<value1> ... <paramN>=<valueN>]
* Red colour indicates obligatory parameters

OPTIONS

file

- The file can be one of:

1. A TPR script file (.tpr) or a Java script file (.java). The file can be either relative to the current script file (for example sayHello.tpr) or absolute (/root/scripts/sayHello.tpr).  T-Plan Robot will check if the file exists and is readable during every script validation and report an error if not.
2. A fully qualified Java script class name (for example org.mytests.DoSomething). The specified class must be on the Java classpath. For details see the command description.

<param>=<value>

- An optional list of parameters and their values. They will be made available to the executed file in the form of local variables.

RETURNS

Run always returns the code returned by the last executed command. If the specified file is not found, T-Plan Robot reports a syntax error rather than returning a non-zero return value.

EXAMPLES

Run sayHello.tpr

- Execute a script called sayHello.tpr which is located in the same directory as the script calling this command.

Run /root/scripts/sayHello.tpr

- Execute a script called sayHello.tpr which is located in the /root/scripts/ directory.

Run /root/scripts/MyTest.java

- Executes the specified Java source code file. It must be a class extending com.tplan.robot.scripting.DefaultJavaTestScript or at least implementing the com.tplan.robot.scripting.JavaTestScript interface. The file is first compiled using the Java Compiler API into the byte code format and then instantiated and executed. This will work only if T-Plan Robot runs on Java from a JDK distribution or is configured with a valid path to a JDK installation (v2.3.3 and newer).

Run com.testsuite.MyDummyTestScript server="rfb://localhost:5901" pass="welcome"

- Instantiates a Java script class and executes it. The class must be on the Java classpath and it must extend com.tplan.robot.scripting.DefaultJavaTestScript or at least implement the com.tplan.robot.scripting.JavaTestScript interface. The two parameters on the command line are made inserted into the context as variables; it is however up to the executed class to use them or not.

Var SCRIPT_TO_EXECUTE=sayHello.tpr
Run "{SCRIPT_TO_EXECUTE}"

- Execute a script specified by a variable.

3.2.16 String

String - Process or parse text. The command applies a text processing function to the argument text. While basic string "test" operations such as "contains", "startswith", "endswith" or "matches" may be performed in if/else statements through boolean expressions, the String command rather targets more complicated processing of text consisting of a sequence of one or more operations.

If the argument text contains variable calls they will be resolved (replaced with values) before the text is processed. The command populates a set of _STRING prefixed variables as follows:

Result of the operation is by default saved to the _STRING variable or to the custom variable specified through the optional 'var' parameter. If the operation produces multiple values (such as the 'split' operation), each value is saved to a numbered variable such as _STRING1, _STRING2 etc. or to similarly numbered set of variables derived from name specified by the 'var' parameter. The number of values is then stored to the _STRING_COUNT variable.

The command has a basic structure of:

String <operation> "<text>" [<parameters>]

Supported operations in alphabetical order are listed below. Their names are in most cases derived from method names of the java.lang.String Java class.

• indexof - Returns the index within the text of the first occurrence of the substring specified through the 'string' parameter. Since v3.5.2 the command may also perform a fuzzy text search similar to the functionality provided by the "tocr" comparison method. Indexing starts from zero. If the specified string is not found, the result is -1. For example, 'String indexof "Demo text" string=text'  will set the _STRING variable to 5. This operation is typically used in combination with the 'substring' one to text parsing. If you need to test the existence of a substring in the given text and you are not interested in its position it is easier to take advantage of the 'contains' Boolean operator.
• length - Returns the text length (number of characters). For example, 'String length  "Demo" '  will set the _STRING variable to 4.

• matches - Matches the text to a java.util.regex.Pattern compliant regular expression specified through the 'pattern' parameter and produces a Boolean result (either 'true' or 'false'). For example, 'String matches "a20" pattern="[a-z][0-9]*" ' sets the _STRING variable to 'true' because the regular expression matches any sequence consisting of a lower case character followed by a sequence of digits. The 'matches' operation is also supported in form of a boolean operator for easy use with the if/else statements.

Since v3.5.2 the command also allows to perform fuzzy text matching. See the "matches" command for details.

• replace - Returns a new text resulting from replacing all occurrences of a value specified by the 'string' parameter in the text with the string provided in the 'replacement' parameter. The operation may be also used with 'pattern' instead of 'string' to perform replacement of all occurrences matching the specified java.util.regex.Pattern regular expression. For example, 'String replace "fox" string=f replacement=s' will set the _STRING variable to 'sox'.
• split - Splits the text into a set of strings around matches of the given string ('string' parameter) or java.util.regex.Pattern regular expression ('pattern'). For example, 'String split "brown fox" string=" " ' will produce two values, _STRING1=brown and _STRING2=fox and sets the _STRING_COUNT variable to 2.
• substring - Returns a substring of the text which is defined by the input 'start' and/or 'end' index numbers. Indexing starts from zero and the value of 0 refers to the text beginning (first character). For example, 'String substring "someone" start=4' will set the _STRING variable to 'one'.
• tostring - Creates a new text from one or more semicolon-separated numeric ASCII or Unicode values. This can be used to produce special characters and/or characters of national alphabets. For example, 'String tostring "49;43;49" ' will set the _STRING variable to '1+1'.
• trim (since 2.3.3) - Removes all leading and trailing whitespace characters (spaces, new line characters etc.). For example, 'String trim " apple   " ' will set the _STRING variable to 'apple'.

String indexof  "<text>"  string=<text> [start=<index>]  [end=<index>]  [distance=<number>]  [var=<variable_name>]

* Red colour indicates obligatory parameters

OPTIONS

text

- The text to process.

string

- The string to search for in the text.

start

- Optional start index to start the search from. It must be a number or a valid numeric expression. Indexing starts from zero where zero refers to the text beginning (the first character). The default start index value is 0. 

end

- Optional end index to end the search at. It must be a number or a valid numeric expression. The default value is the text length (the end of the text).

distance

- Optional distance used in conjunction with the "string" parameter to perform tolerant text search (supported since 3.5.2). When the parameter is set to the default value of 0 (no distance) the command falls back to plain string search where the argument text is searched for the first occurrence of the provided string. 

The tolerant (fuzzy) text search is performed for the distance values of 1 and higher. The text is searched for an occurrence of a string which is similar enough to the specified one. The tolerance (similarity) is based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent. 
To perform fuzzy text matching instead of search, use the String matches command.

var


- Optional name of the variable to store the resulting index to. If this parameter is not specified the result will be stored to the default _STRING variable. 

RETURNS

The 'String indexof ' command returns 0 (zero) if the specified string was found in the text and 1 otherwise. The command further on stores the index (or -1 if not found) to the _STRING variable (or a custom variable specified by the 'var' parameter). Indexing starts from zero where zero refers to the text beginning (first character).

EXAMPLES

String indexof "Demo text" string="text" var=result 

- Get position (index) of "text" in "Demo text" and store the result of 5 into the "result" variable.

String indexof "Demo text" string="test" var=result  distance=1 

- Same as the previous example save that the word of "text" will be located by the specified string of "test" because it is within the distance of 1.

String length  "<text>"  [var=<variable_name>]

* Red colour indicates obligatory parameters

OPTIONS

var

- Optional name of the variable to store the resulting text length to. If this parameter is not specified the result will be stored to the default _STRING variable. 

RETURNS

The 'String length' command always returns 0 (zero) and stores the argument text length (number of characters) to the _STRING variable or a custom variable specified by the 'var' parameter.

EXAMPLES

String length "Demo text" var=len 

- Stores the length of "Demo text" (9) into the "len" variable.

 String matches "<text>" pattern="<regular_expression>" [var=<variable_name>]

String matches "<text>" string="<text>" [distance=<number>]  [var=<variable_name>]

* Red colour indicates obligatory parameters

OPTIONS

pattern

- A java.util.regex.Pattern compliant regular expression. The regular expression of "." matches by default any character except for the line terminator. This behaviour may be changed through command preferences. 
Be aware that the expression must match the whole text. The command will NOT search the text for its portion that would match the expression. For example, to search the text for the "*.test.*" word, you have to use the expression of ".test.". Meaning "the word of 'test' which may or may not contain any (.*) preceding and/or trailing text". 

string

- A string to search the text for (supported since 3.5.2). 

distance

- Optional distance used in conjunction with the "string" parameter to perform tolerant text matching (supported since 3.5.2). When the parameter is set to the default value of 0 (no distance) the command falls back to plain string comparison where the argument text is tested whether it is equal to the provided string. 
The tolerant (fuzzy) text matching is performed for the distance values of 1 and higher. The text is tested whether it is similar enough to the specified string. The tolerance (similarity) is based on the Levenshtein distance. It is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character. The distance approximately specifies how many characters may be omitted or not recognized properly at a maximum to consider the sample text equivalent. 
Be aware that the specified string must match the whole argument text. To perform a fuzzy text search to find a string similar to the specified one use String indexof instead.

var

- Optional name of the variable to store the resulting Boolean flag (true/false) to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS

The 'String matches' command returns 0 (zero) if the text matches the regular expression or 1 when not. The command further on stores the result as 'true' or 'false' to the _STRING variable or a custom variable specified by the 'var' parameter.

EXAMPLES

File open file="C:\data.txt"
Var result=-1

for (i=1; {i}<{_FILE_LINE_COUNT}+1; i={i}+1) {
   File read line={i}
   String matches "{_FILE_READ}" pattern="[a-z]*"
   if ({_EXIT_CODE} == 0) {
       Var result={i}
       Break
      }

}

- Open a data file, read it line by line and match each one against the specified regular expression. If the line matches, save the line number to the "result" variable and stop.

// Create a sample text 
Var TEXT= "this is sample text" 

// This command will return 0 (pass) because the specified 
// pattern will match any text containing "simple" or "sample" 
String "matches" "{TEXT}" pattern=".*s[ia]mple.*" 

// This will return 0 because the text does not contain "simple" 
String "matches" "{TEXT}" string="simple" 

// This will return 0 because the text contains "sample" 
// which has only one character different from "simple" 
String "matches" "{TEXT}" string="simple" distance=1 

- Test the sample text in various ways.

String replace "<text>" string="<text>"  replacement="<text>" [var=<variable_name>]

String replace  "<text>" pattern="<regular_expression>"  replacement="<text>" [var=<variable_name>]

* Red colour indicates obligatory parameters


OPTIONS

replacement

- The new string (replacement). 

string

- The old string (to be replaced in the text). 

pattern


- A java.util.regex.Pattern compliant regular expression representing the strings to be replaced. The regular expression of "." matches by default any character except for the line terminator. This behaviour may be changed through command preferences.


var


- Optional name of the variable to store the resulting new text to. If this parameter is not specified the result will be stored to the default _STRING variable.

RETURNS

The 'String replace' command returns 0 (zero) if at least one replacement has been performed or 1 when no replacement has been done and the resulting text equals to the original one. The new text is stored to the _STRING variable or a custom variable specified by the 'var' parameter regardless of whether it has been changed or not.

EXAMPLES

String replace "bad fat cat" string="b" replacement="s"

- Updates the _STRING variable with "sad fat cat" and returns 0 because the string has been updated.

String replace "bad fat cat" pattern="[bf]a[td]" replacement="cat"

- Updates the _STRING variable with "cat cat cat" and returns 0 because the string has been updated.

String split  "<text>" string="<text>"  [var=<variable_name>]
String split  "<text>" pattern="<regular_expression>"  [var=<variable_name>]
* Red colour indicates obligatory parameters

OPTIONS

string

-The delimiter (separator) to split by.

pattern

-A java.util.regex.Pattern compliant regular expression to split by. The regular expression of "." matches by default any character except for the line terminator. This behaviour may be changed through command preferences.

var

-The optional base name of the variables to store the resulting strings to. If this parameter is not specified the result will be stored to the default numbered _STRING<number> variables.

RETURNS

The 'String split' command always returns 0 (zero). Each parsed value is saved to a numbered variable such as _STRING1, _STRING2 etc. or to similarly numbered set of variables derived from name specified by the 'var' parameter. The number of values is then stored to the _STRING_COUNT variable.

EXAMPLES

String split "bad fat cat" string=" " var="s"

- Split the text by spaces. As a custom variable base name of "s" is specified the command produces a set of three variables s1="bad", s2="fat" and s3="cat". The _STRING_COUNT variable will be set to 3.

String split "bad, fat cat" pattern="[,]* "

- Split the text by spaces which may be optionally preceded by a comma. Similarly to the previous example, the command produces a set of three variables _STRING1="bad", _STRING2="fat" and _STRING3="cat". The _STRING_COUNT variable will be set to 3.

// Directory to work with.
Var DIR=/tmp

// List the directory contents (Linux/Unix).
// For Windows replace the "ls" command with "command.com /C dir /B"
Exec "ls {DIR}" 

// Split the directory listing by lines
String split "{_EXEC_OUTPUT}" pattern="\r?\n"

for (i=1; {i}<{_STRING_COUNT}+1; i={i}+1) {

  // Replace floating point from index (not needed on 2.3.3+)
  String replace "{i}" pattern="[.].*" replacement=""

  Var f="{_STRING{i}}"

  // If the file is a .png or a .jpg image display it for 3 seconds
  if ("{f}" endswith ".png" || "{f}" endswith ".jpg") {
    Connect "file://{DIR}/{f}" 
    Wait 3s 
  }
} 

- Perform an image slide show on a directory. The "String split" command is here used to split the directory listing to individual files (one file per line is expected). The parsed strings (file names) are then checked for a known image extension and displayed in the Robot's desktop view for 3 seconds.

String substring  substring "<text>" start=<index>  [end=<index>]  [var=<variable_name>]
String substring  "<text>" end=<index>  [start=<index>]  [var=<variable_name>]
* Red colour indicates obligatory parameters

OPTIONS

start

- Start index (a number or a valid numeric expression). Indexing starts from zero where zero refers to the text beginning (the first character). The default value is 0. 

end

- End index (a number or a valid numeric expression). The default value is the text length (end of text). 

var

- The optional base name of the variables to store the resulting substring to. If this parameter is not specified the result will be stored to the default _STRING variable. 

RETURNS

The 'String substring' command returns 0 (zero) when the start and end indices refer to valid positions in the text. If the start position is invalid (meaning it is less than zero or equal to or larger than the text length), the command sets the start index to 0 and returns 1. Otherwise, if the end position is invalid (meaning it is less than the start position or larger than the text length), the command sets the end index to the default value of text length and returns 2. Regardless of the returned value the _STRING variable (or the custom one passed through the 'var' parameter) is always populated with a new substring between the start and end positions.