画像およびOCR検索
ここに挙げるコマンドと関数は、テスト対象システム(SUT)において画像検索やOCR検索を実行します。
下記の画像およびOCR検索のコマンドおよび関数の検索における振る舞いは、実行オプションのグローバルプロパティであるthe ImageSearchCount、the ImageSearchDelayおよびthe ImageSearchTimeによって、さらに細かく管理できます。
Eggplant Functionalスクリプト内に下記の例をコピーして貼り付けると、最適な結果が得られます。
EveryImageLocation()関数
挙動:SUT上で、指定の画像またはテキスト(OCR)の出現箇所をすべて検索し、画像の出現箇所ごとのホットスポット座標のリストまたはテキスト文字列の中心点のリスト(OCR使用時)を返します。座標のリストは、見つかった順に並べられます。SUTの左上の角に一番近い画像やテキストから最初に見つかります。画像やテキスト(OCR)が見つからない場合、EveryImageLocationは空のリストを返します。
パラメータ:1つまたは複数の画像参照またはテキスト(OCR)参照と、画像またはOCR検索プロパティ。追加の画像検索プロパティを渡す際には、必ずImageNameプロパティを含めます。
構文:
戻り値:指定の1画像または複数画像の各インスタンスの座標。例:((288,325),(288,356),(288,387),(288,448))
例:
log EveryImageLocation(ImageName:"CheckBoxes",scale:(1,.5)) // 元のサイズおよび半分の縮尺の両方で見つかった画像の各出現箇所のホットスポット座標のリストをログします。このように、画像検索用の追加プロパティを含める際にはImageNameプロパティを使用します。
例:
click the penultimate item of EveryImageLocation(text:"AddressField") // テキスト(OCR)出現箇所リスト内のpenultimate(最後から2番目の)アイテムをクリックします。
例:
set the RemoteWorkInterval to .1 // the RemoteWorkInterval(デフォルト=.7)を短縮して、Eggplant FunctionalがSUTに送信するアクション同士の間隔を短くします。これにより、一連のクリックの実行を高速化できます。
repeat with EveryImageLocation("RadioButton") // everyImageLocation()で見つかった画像の各出現箇所について繰り返します。
click it // it変数を使い、repeatループで扱われている現在の出現箇所をクリックします。
end repeat
set the RemoteWorkInterval to .7
例:
// 次の例は、上の例の代わりとなる構文です。
repeat with each item of EveryImageLocation("RadioButton")
click it // it変数を使い、repeatループで扱われている現在の出現箇所をクリックします。
end repeat
ヒント:EveryImageLocation()関数を呼び出したら、すぐにthe resultを呼び出すことで、EveryImageLocation()で表される各画像のImageInfo()を返すことができます。
例:
put EveryImageLocation("GreenSaveButton","BlueSaveButton","RedSaveButton") // 画像の各出現箇所のホットスポット座標のリストを返します。
put the result // EveryImageLocationで表された各画像のimageInfo()を返します。
EveryImageRectangle()関数
挙動:SUT上で、指定の画像またはテキスト(OCR)の出現箇所をすべて検索し、それぞれの画像またはテキスト(OCR)の出現箇所の矩形座標のリストを返します。座標のリストは、見つかった順に並べられます。SUTの左上の角に一番近い画像やテキストから最初に見つかります。画像やテキスト(OCR)が見つからない場合、 EveryImageRectangle()は空のリストを返します。
パラメータ:1つまたは複数の画像参照またはテキスト(OCR)参照と、画像またはOCR検索プロパティ。追加の画像検索プロパティを渡す際には、必ずImageNameプロパティを含めます。
構文:
戻り値:指定の1画像または複数画像の各インスタンスの矩形座標。
例:
put EveryImageRectangle("TotalAmountLabel", "ItemizedAmountLabel") // 画像の各出現箇所の矩形座標のリストを返します。
例:
assert that the number of items in EveryImageRectangle(ImageName:"CheckBoxes",searchRectangle:("SelectOptionsUpperLeft","SelectOptionsLowerRight")) is 4 // 画像の出現数が、期待される数字である4に等しいかどうかを表明します。出力の例:AssertionFailed (assertion: the number of items in EveryImageRectangle(ImageName:"ImageName") is 4; actually: 5 IS NOT equal to 4)
例:
Set StatusRectangles to EveryImageRectangle(text:"StatusLabel") // EveryImageRectangleの戻り値をStatusRectanglesという変数に格納します。
Log "There are"&&the number of items of StatusRectangles&&"statuses to check." // 連結を使って、StatusRectangles内に格納されたリストにある出現箇所の数と2つの文字列とを結合し、その出力をログします。
repeat with each Rectangle of StatusRectangles // Rectangleという名前の変数を使い、リスト内の各アイテムについて繰り返しを行います。
Set StatusIndicatorLocation to the TopRight of Rectangle plus (15,0) // 現在の出現箇所の右上角に対して右に15ピクセルの座標調整を行い、それを変数StatusIndicatorLocationに格納します。
If ColorAtLocation(StatusIndicatorLocation) is "59,170,43" then Log "The status is green." // ColorAtLocation()関数を使ってStatusIndicatorLocationでのRGB値を検出し、期待されるRGB値である59,170,43と比較します。
end repeat
例:
put EveryImageRectangle("GreenSaveButton","BlueSaveButton","RedSaveButton") // 該当画像の各出現箇所の矩形座標のリストを返します。
put the result // EveryImageRectangleで表された各画像のimageInfo()を返します。
ImageFound() 関数
挙動:Viewerウィンドウ内で指定の画像を検索し、画像が見つかればtrueを、見つからなければfalseを返します。最大待ち時間パラメータは、画像発見のための時間的猶予で、それを過ぎるとfalseが返されます。
パラメータ:1つまたは複数の画像参照またはテキスト(OCR)参照と、画像またはOCR検索プロパティ。追加の画像検索プロパティを渡す際には、必ずImageNameプロパティを含めます。
構文:
戻り値: TrueまたはFalse
例:
put ImageFound(ImageName:"CloseButton",WaitFor:0) // 画像が見つかったかどうかに応じてtrueまたはfalseを返します。ここで使用している値0のWaitForプロパティは、SUT画面を1回だけ渡すように画像検索を制限します。WaitForプロパティが含まれていない場合のデフォルトの回数は7回です。なお、このように画像検索用の追加プロパティを含める際にはImageNameプロパティを使用します。
例:
if ImageFound(ImageName:"OKButton") then // 画像が見つかるかどうかをチェックします。
click FoundImageLocation() // ImageFound()でtrueが返されたら、FoundImageLocation()関数を使用し、そこに格納されたImageFound()関数により発見された画像の該当位置をクリックします。
else
TypeText AltKey,F4 // ImageFound()でfalseが返された場合はアプリケーションを閉じるキーストロークを実行します。
end if
例:
Repeat until ImageFound(ImageName:"NextButton",WaitFor:0) // このrepeatループはImageFound()関数がtrueを返すまで繰り返しを行います。
Typetext PageDown // Page Downキーボードアクションを送信してページをスクロールダウンします。
Wait 2 // スクロールアクション後にアプリケーションが動きを止められるように2秒待ちます。
if the repeatindex is greater than 5 then throw "Image Not Found:", "NextButton not found when scrolling." // この条件文は、repeatループの繰り返しが5回を上回ったかどうかをチェックし、上回っていれば例外を投げて実行を停止します。
end repeat
ImageLocation()関数
挙動:SUT上で、指定の画像またはテキスト(OCR)を検索し、見つかった最初の画像の最初の出現箇所のホットスポット座標またはテキスト(OCR)矩形の中心点を返します。画像が見つからない場合は、例外が投げられます。
パラメータ:1つまたは複数の画像参照またはテキスト(OCR)参照と、画像またはOCR検索プロパティ。追加の画像検索プロパティを渡す際には、必ずImageNameプロパティを含めます。
構文:
戻り値:画像のホットスポット位置またはテキスト(OCR)矩形の中心点の座標。例:(338, 335)
例:
set SectionHeaderLocation to ImageLocation(text:"Billing Address") // ImageLocation()の戻り値をSectionHeaderLocationという変数に格納します。これはテキスト(OCR)検索であるため、戻り値は「Billing Address」矩形の中心座標になります。
例:
click ImageLocation("NameLabel") + (50,-10) // 画像のホットスポット位置より50ピクセル右かつ10ピクセル上の位置をクリックします。
例:
tap (ImageName:"OKButton",searchRectangle:("PopupHeader",ImageLocation("LowerRightAnchor") - (400,500))) // searchRectangleの右下角を、LowerRightAnchor画像のホットスポットより400ピクセル上かつ500ピクセル左に調整した形で設定します。
例:
// スクロールバーの下ボタンの位置を格納し、その格納位置をクリックすることで、Eggplant Functionalによる画像検索が一回で済み、ボタン10回クリックの実行スピードが上がります。
set ScrollDownButtonLocation to ImageLocation("ScrollDownButton")
repeat 10 times
click ScrollDownButtonLocation
end repeat
ImageRectangle()関数
挙動:SUT上で、指定の画像またはテキスト(OCR)を検索し、見つかった最初の画像の最初の出現箇所の矩形座標を返します。画像検索の場合、ImageRectangle()は、キャプチャされる画像のサイズおよび形状に従います。ただし、ClipRectangle画像検索プロパティが使用されている場合はこの限りではありません。OCR検索の場合、ImageRectangle()は、SUT上での当該テキスト文字列の表示に合わせて、その周囲に自動調整されます。画像またはテキスト(OCR)が見つからない場合は、例外が投げられます。
パラメータ:1つまたは複数の画像参照。
構文:
戻り値:見つかった画像の矩形座標。例:(348,451,460,554)
例:
put ImageRectangle ("CompanyLogo") // ImageRectangle()の戻り値をRunウィンドウにのみ出力します。
例:
log "The coordinates of the rectangle are"&&ImageRectangle (ImageName:"PhoneTypeLabel",searchRectangle:("PhoneContactHeader","SectionDivider")) // 連結を使い、文字列とImageRectangleの戻り値とを間にスペースを入れて結合します。このように、画像検索用の追加プロパティを含める際にはImageNameプロパティを使用します。
例:
click the topLeft of ImageRectangle (ImageName:"EnableSetting") // ImageRectangle()は、SUTを操作するコマンドと組み合わせることができます。ここでは、topLeft関数を使ってImageRectangleの特定の角を選択しています。
例:
set NameFieldRectangle to ImageRectangle (Text:"Name") // 見つかったテキスト(OCR)の矩形座標を変数に格納します。
set NameFieldValue to ReadText(Right of NameFieldRectangle,Top of NameFieldRectangle,Width of the RemoteScreenSize,Bottom of NameFieldRectangle) // ReadText()を使い、NameFieldLocationのすぐ右の領域から、ずっとSUT画面の右端までを読み取ります。
WaitForコマンド
挙動:SUT上で画像またはテキスト(OCR)が見つかるまで、次のスクリプト行の実行を一時停止します。指定の待ち時間以内に画像またはテキスト(OCR)が見つからなければ、例外が投げられます。実際の待ち時間は、指定した待ち時間を超える可能性があります。これは、SUTの解像度、Discrepancy設定、ネットワーク遅延、画像収集サイズといった要素に合わせて、待ち時間が自動で調節されるためです。
パラメータ:待ち時間と、1つまたは複数の画像参照またはテキスト(OCR)参照、および画像またはOCR検索プロパティ。追加の画像検索プロパティを渡す際には、必ずImageNameプロパティを含めます。待ち時間はデフォルトでは秒単位です。
構文:
例:
WaitFor 6.5, "OKButton", "ExitButton" // どちらかの画像が現れるのを最大6.5秒間待ちます。
例:
WaitFor 2 minutes, (ImageName:"InstallationCompleteMessage",searchRectangle:("InstallProgressDialogUpperLeft","InstallProgressDialogLowerRight"))
注: WaitForは、画像またはテキスト(OCR)検索コマンドのプロパティとしても使用可能です。WaitForプロパティも、WaitForコマンド同様、Eggplant FunctionalがSUT上での指定画像の出現を待つ最大時間を表します。
例:
Click (ImageName:"Done_button", waitFor: 2 minutes)
また、the ImageSearchTimeグローバルプロパティを使用して、画像またはテキスト(OCR)検索セクションの検索時間に影響を与えることもできます。
関連:
- Wait:特定の待ち時間を挿入するときは、こちらのコマンドを使用します。
WaitForAllコマンド
挙動:Viewerウィンドウ内で画像またはテキスト(OCR)の全パラメータが見つかるまで、次のスクリプト行の実行を一時停止します。最大待ち時間内にすべての画像が見つからなければ、例外を投げます。
パラメータ:待ち時間と、1つまたは複数の画像参照またはテキスト(OCR)参照、および画像またはOCR検索プロパティ。追加の画像検索プロパティを渡す際には、必ずImageNameプロパティを含めます。待ち時間はデフォルトでは秒単位です。
構文:
例:
WaitForAll 15, "OKButton", "ExitButton"
例:
WaitForAll 5, ("Welcome"), (text:"Susan",CaseSensitive:"yes")
注:括弧で囲った画像リストがWaitForAllパラメータとして渡された場合、リスト内のアイテムがどれか1つ見つかったときに、Eggplant Functionalはそのパラメータが「見つかった」と判断します。
例:
WaitForAll 20, "crust", "sauce", ("peppers", "olives")
このコマンドのパラメータは、"crust"、"sauce"、そして(括弧で囲まれた)それ以外の2アイテムのリストの3つです。意味的には、次のように考えることができます。
WaitFor20, "crust" // それと同時に...
WaitFor 20, "sauce"
WaitFor 20, "peppers", "olives" // どちらかのアイテムを待ちます。
関連:
- Wait:特定の待ち時間を挿入するときは、こちらのコマンドを使用します。
SetSearchRectangleコマンド(非推奨)
挙動:2組の画面座標をパラメータとして取り、これらの点によって検索領域の2つの対角部を定義します。
パラメータ:2組の座標または2つの画像を取り、画面領域の左上角と右下角を定義します。
構文:
例:
SetSearchRectangle((0,0),(100,100))
例:
SetSearchRectangle("TLImage","BRImage")