スクリプト仕様 - TapEzy Guide Page

TapEzyで使用できるスクリプトの仕様について説明します。

仕様概要

スクリプト言語は、Lua 5.2 を使います。
通常の Lua の言語機能に加えて、TapEzy独自の関数(tapなど) を呼び出すことでシナリオを作成します。
シナリオが実行された時、スクリプト内の run() 関数が呼び出されます。これはスクリプト内で実装が必須の関数です。
画像検出やテキスト検出など、画面のスクリーンキャプチャが必要がシナリオの場合は、should_capture_screen() 関数を実装し、true を返す必要があります。false を返した場合または should_capture_screen() 関数がない場合は、画像検出やテキスト検出を実行しようとした際にシナリオ実行を中断します。
スクリプトシナリオ実行時にエラーが発生した場合、実行を中断します。その際、シナリオ実行ログにエラーが表示されますので、エラー内容を確認してください。

シナリオ実行ログ
Lua の print を使用可能です。print の内容は、シナリオ実行ログに表示されます。

TapEzy独自関数

delay(milliSeconds)

指定された時間、待機します。

引数
- milliSeconds: 待機する時間（ミリ秒）
戻り値
なし

tap(x, y, duration)

画面内の場所をタップします。

引数
- x: タップする場所の x座標
- y: タップする場所の y座標
- duration: 画面にタッチする時間（ミリ秒）。
戻り値
なし

gesture(path, duration)

画面内でジェスチャー操作を行います。引数として、パスを一つ指定する形式で、一本指でのジェスチャー操作を表現できます。

引数
- path: パスを表現するテーブルです。パスは、キーフレームの配列です。キーフレームは{x, y, frame} の形式の配列です。frame は指定された座標位置にタッチ点が来る時の時刻で、ジェスチャー開始からのミリ秒を指定します。
  例: 座標 (500, 500) から座標 (100, 100) へのスワイプ操作を 100 ミリ秒かけて行う
```
gesture({{500,500, 0},{100, 100, 100}}, 100)
```
- duration: ジェスチャー操作を実行する時間。パスの最終のキーフレームと同じ値を指定した場合、等速のジェスチャーとなります。より小さい値を指定することで、ジェスチャー全体のスピードを早めることもできます。
戻り値
なし

gesture(path_list, duration)

画面内でジェスチャー操作を行います。引数として、パスを複数指定する形式で、二本以上の指でのジェスチャー操作を表現できます。

引数
- path_list: パスの配列。パスは、キーフレームの配列です。キーフレームは{x, y, frame} の形式の配列です。frame は指定された座標位置にタッチ点が来る時の時刻で、ジェスチャー開始からのミリ秒を指定します。
  例: 座標 (500, 500) あたりを中心に、座標 (200, 200)と座標(800, 800) へのピンチ操作を 1000 ミリ秒かけて行う
```
gesture({{{450, 450, 0}, {200, 200, 100}}, {{550,550, 0},{800, 800, 100}}}, 1000)
```
- duration: ジェスチャー操作を実行する時間。パスの最終のキーフレームと同じ値を指定した場合、等速のジェスチャーとなります。より小さい値を指定することで、ジェスチャー全体のスピードを早めることもできます。
戻り値
なし

input_text(text)

フォーカス中のテキスト入力欄にテキスト入力を行います。

引数
- text: 入力するテキスト
戻り値
テキスト入力の成否

input_text(element, text)

指定したテキスト入力欄にテキストを入力します。

引数
- element: テキスト入力欄の要素情報。要素情報は detect_ui で画面要素検出を行った時の戻り値として取得できます。
- text: 入力するテキスト
戻り値
テキスト入力の成否

detect_image(image_id, require_detection_count, parameters, timeout)

画像検出を行います。検出に使用する画像はあらじめアプリに登録しておく必要があります。

画像一覧

detect_image で画像検出を行うと、結果が戻り値として返されます。検出結果に含まれる検出矩形を使って、検出画像をタップするなどの動作を行うことができます。

使用例

画像ID “3” の画像を検出し、検出した矩形の中心をタップ

local result = detect_image("3", 1, {grayscale = true, error_tolerance = 70, scaling_level = 0, }, 1000)
if result ~= nil then
    local r1 = result.rects[1] -- 1つ目の検出矩形
    -- 検出画像をタップ            
    tap(r1[1] + r1[3] * 0.5 ,r1[2] + r1[4] * 0.5, 100)
    delay(100)
else
end

引数
- image_id: 画像ID。文字列形式
- require_detection_count: 検出要求数。この数以上の検出が同時に成功した場合にのみ戻り値に nil 以外が返ってきます。検出対象間ドラッグような、複数の検出対象を使う処理を行う場合は 2 以上の値を指定します。
- parameters: 検出パラメータテーブル。画像検出に関係するパラメータをテーブル形式で指定します。省略したパラメータはデフォルト値が使用されます。パラメータは以下
  - max_detection: 最大検出数。デフォルト 1。require_detection_count 以上の値を指定してください。
  - target_rect: 検出範囲を矩形形式で指定します。デフォルトは全画面。
  - grayscale: グレースケール検出を行うか。デフォルトは true。
  - error_tolerance: 誤差許容度。デフォルトは 70。低いほど厳格に検出します。0〜100 の範囲で指定します。
  - scaling_level: スケーリングレベル。デフォルトは 0。整数値で、数値が低いほど縮小して検出を行います。2 ^(scaling_level) 倍にスケーリングします。
  パラメータの意味は、画像検出ステップの設定項目も参考にしてください
  
  🖼️画像検出
- timeout: 検出タイムアウトをミリ秒で指定します。
戻り値
画像検出結果を表すテーブル。検出失敗した場合は nil

テーブルは { rects: 検出矩形配列 } の形式です。

detect_text(text, require_detection_count, parameters, timeout)

テキスト検出を行います。

detect_text でテキスト検出を行うと、結果が戻り値として返されます。検出結果に含まれる検出矩形を使って、検出画像をタップするなどの動作を行うことができます。

使用例

“テスト” または “シナリオ” のテキストを検出し、検出した矩形の中心をタップ

local result = detect_text({"テスト", "シナリオ"}, 1, {matches_only_element = false, scaling_level = 0, }, 1000)
if result ~= nil then
    local r1 = result.rects[1] -- 1つ目の検出矩形
    -- 検出テキストをタップ            
    tap(r1[1] + r1[3] * 0.5 ,r1[2] + r1[4] * 0.5, 100)
    delay(100)
else
end

引数
- text: 検出するテキスト。文字列形式または文字列の配列形式
- require_detection_count: 検出要求数。この数以上の検出が同時に成功した場合にのみ戻り値に nil 以外が返ってきます。検出対象間ドラッグような、複数の検出対象を使う処理を行う場合は 2 以上の値を指定します。
- parameters: 検出パラメータテーブル。テキスト検出に関係するパラメータをテーブル形式で指定します。省略したパラメータはデフォルト値が使用されます。パラメータは以下
  - target_rect: 検出範囲を矩形形式で指定します。デフォルトは全画面。
  - matches_only_element: テキスト検出した要素単位で一致したときのみ成功したとみなします。デフォルトは false。
  - scaling_level: スケーリングレベル。デフォルトは 0。整数値で、数値が低いほど縮小して検出を行います。2 ^(scaling_level) 倍にスケーリングします。
  パラメータの意味は、テキスト検出ステップの設定項目も参考にしてください
  
  🔤テキスト検出
- timeout: 検出タイムアウトをミリ秒で指定します。
戻り値
テキスト検出結果を表すテーブル。検出失敗した場合は nil

テーブルは { rects: 検出矩形配列, text: 検出したテキスト, rect_map: {検出したテキスト: 検出矩形配列} } の形式です。テキスト検出は複数のテキストを同時に検出できるため、検出できた全情報が rect_map として含まれています。

detect_ui(condition, require_detection_count, settings, timeout)

画面要素検出を行います。

detect_ui で画面要素検出を行うと、結果が戻り値として返されます。検出結果に含まれる検出矩形や要素情報を使って、検出画面要素にテキスト入力などの動作を行うことができます。

使用例

“種類” の内包テキストを持つテキスト入力欄を検出し、検出したテキスト入力欄に “テスト” と入力する

local result = detect_ui(
    {
        class_name = "android.widget.EditText",
        contained_text = "種類"
    }, 
    1, 
    {
        editable_only = true,
        match_settings = {
            class_name = "required",
            contained_text = "required"
        },
        text_match_settings = {
            contained_text = "exact"            
        }
    },
    1000
)
if result ~= nil then
    input_text(result.candidates[1], "テスト")
    delay(100)
else
end

引数

引数でアプリ名などの各属性を使う場合、属性名は下記のものを使用します。

項目	属性名	説明
アプリ名	package_name	対象の画面要素が含まれるアプリの識別子（パッケージ名）です。
要素の種類	class_name	検出対象とする画面要素の種類です。
内部ID	view_id	画面要素に割り当てられた内部ID（viewId）です。開発者がアプリ内で定義している場合に使用できます。
テキスト	text	画面要素に表示されているテキストです。
内包テキスト	contained_text	指定した要素の中に表示されているテキストです。
説明ラベル	content_description	画面要素に設定されている説明ラベル（contentDescription）です。視覚的なテキストとは異なる場合があります。
要素の位置	bounds	画面内での表示位置と大きさを表す矩形領域（バウンディングボックス）です。
要素の構造	path	画面上の構造における順序を表す番号です。対象の画面要素が階層内で何番目に位置するかを表します。

condition: 検出対象の情報をテーブル形式で指定します。各属性の値の形式は以下の通り
- bounds: 矩形形式
- path: 数値配列
- それ以外: 文字列形式
require_detection_count: 検出要求数。この数以上の検出が同時に成功した場合にのみ戻り値に nil 以外が返ってきます。検出対象間ドラッグような、複数の検出対象を使う処理を行う場合は 2 以上の値を指定します。

settings: 探索条件の設定をテーブル形式で指定します。

clickable_only: タップ可能な要素に限定するかどうかを boolean で指定します。省略した場合は false になります。
editable_only: テキスト入力可能な要素に限定するかどうかを boolean で指定します。省略した場合は false になります。

match_settings: 各属性の使用モードをテーブル形式で指定します。指定していない属性は使用されません。使用モードとして使える値は以下の通り

使用モード	値	意味
必須	required	一致していなければ候補になりません
優先	preferred	一致していれば候補の中で優先されます
使用しない	ignored	この項目は比較に使用しません

text_match_settings: テキスト、内包テキスト、説明ラベルの各属性でテキストの一致方法をテーブル形式で指定します。一致方法として使える値は以下の通り

一致方法	値	意味
完全一致	exact	指定されたテキストと完全に一致する要素にマッチします
含む	contains	指定されたテキストが含まれていればマッチします
前方一致	starts_with	指定されたテキストで始まっていればマッチします
後方一致	ends_with	指定されたテキストで終わっていればマッチします

timeout: 検出タイムアウトをミリ秒で指定します。

戻り値
テキスト検出結果を表すテーブル。

テーブルは { rects: 検出矩形配列, candidates: 検出要素配列 } の形式です。各配列は、優先に指定した条件に応じて整列されており、rect[1]とcandidates[1] が最も合致した要素の情報になります。candidates は input_text に引数として指定することができます。