🚀 モバイルデバイスコマンドとインタラクションツールドキュメント
本プロジェクトは、柔軟で信頼性の高いモバイルデバイス自動化テストフレームワークを提供することを目的としています。アクセシビリティロケーター(preferred)と座標ベースの入力をサポートし、ユーザーは実際のニーズに応じて異なるロケーション方式を選択して、シームレスな自動化プロセスを実現できます。
🚀 クイックスタート
このツールを使用することで、モバイルデバイスの様々な操作を自動化できます。以下に、各コマンドの詳細を説明します。
✨ 主な機能
- モバイルデバイス上のアプリケーションの一覧表示、起動、終了などの操作をサポートします。
- 画面のサイズ取得、指定座標でのクリック、スワイプ、ドラッグなどの操作が可能です。
- デバイスのハードウェアボタンの操作、URLの開き、テキストの入力などの機能を備えています。
- ネットワーク接続のチェック、位置情報の設定、アプリケーションのインストール・アンインストールなどの操作もサポートします。
📦 インストール
このドキュメントではインストールに関する具体的な手順は記載されていません。
💻 使用例
基本的な使用法
var elements = ["element1", "element2"];
mobile_tap_elements(elements, true);
高度な使用法
const mobileOperations = new MobileOperations();
mobileOperations.addOperation(MobileOperations.OPERATION_TYPE.TAP, { x: 100, y: 200 });
mobileOperations.addOperation(MobileOperations.OPERATION_TYPE.LONG_TAP, { x: 300, y: 400, duration: 1000 });
mobileOperations.execute();
📚 ドキュメント
コマンド一覧と説明
mobile_list_apps
- 説明: デバイス上にインストールされているすべてのアプリケーションをリストします。
- パラメータ:
bundleId
(文字列): アプリケーションの一意のパッケージ/識別子。例: com.google.android.keep
または com.apple.mobilenotes
。
mobile_launch_app
- 説明: デバイスまたはシミュレーター上で指定されたアプリケーションを起動します。
- パラメータ:
bundleId
(文字列): アプリケーションの一意のパッケージ/識別子。例: com.google.android.keep
または com.apple.mobilenotes
。
mobile_terminate_app
- 説明: 実行中のアプリケーションを終了します。
- パラメータ:
packageName
(文字列): アプリケーションのパッケージ/識別子に基づいて am force stop
を呼び出すか、プロセスを直接終了します。
mobile_get_screen_size
- 説明: デバイスの画面解像度をピクセル単位で取得します。
- パラメータ: なし
mobile_click_on_screen_at_coordinates
- 説明: 指定された画面座標でクリックします。
- パラメータ:
mobile_list_elements_on_screen
- 説明: 画面上のすべての要素とその座標をリストします。表示テキストまたはアクセシビリティラベルも含まれます。
- パラメータ: なし
mobile_element_tap
- 説明: アクセシビリティロケーターに基づいて指定されたUI要素をクリックします。
- パラメータ:
element
(文字列): 人間が読み取り可能な要素の説明(例: “ログインボタン”)。
ref
(文字列): アクセシビリティ/自動化IDまたはスナップショットから取得した参照。
mobile_tap
- 説明: 指定された画面座標でクリックします。
- パラメータ:
mobile_press_button
- 説明: デバイス上のハードウェアボタン(例: ホーム、戻る、音量、入力など)を押します。
- パラメータ: なし
mobile_open_url
- 説明: デバイスのブラウザで指定されたURLを開きます。
- パラメータ:
url
(文字列): 開くURLアドレス。例: https://example.com
。
mobile_type_text
- 説明: フォーカスされた要素(TextField、SearchFieldなど)にテキストを入力します。
- パラメータ:
text
(文字列): 入力するテキスト
submit
(ブール値): 入力後にエンターキーを押すかどうか
mobile_element_swipe
- 説明: あるUI要素から別のUI要素にスワイプします。
- パラメータ:
startElement
(文字列): 開始要素の人間が読み取り可能な説明
startRef
(文字列): 開始要素のアクセシビリティ/自動化ID
endElement
(文字列): 終了要素の人間が読み取り可能な説明
endRef
(文字列): 終了要素のアクセシビリティ/自動化ID
mobile_swipe
- 説明: 2つの座標点間でスワイプ操作を実行します。
- パラメータ:
startX
(数値): 開始X座標
startY
(数値): 開始Y座標
endX
(数値): 終了X座標
endY
(数値): 終了Y座標
mobile_press_and_hold
- 説明: 指定された位置で画面を長押しします。
- パラメータ:
x
(数値): X座標
y
(数値): Y座標
duration
(数値): 長押しの持続時間(ミリ秒)
mobile_drag_and_drop
- 説明: ある位置から別の位置に要素をドラッグします。
- パラメータ:
fromX
(数値): ドラッグ開始点のX座標
fromY
(数値): ドラッグ開始点のY座標
toX
(数値): ドラッグ終了点のX座標
toY
(数値): ドラッグ終了点のY座標
mobile_scroll
- 説明: 画面上でスクロール操作を実行します。
- パラメータ:
direction
(文字列): スクロール方向。選択可能な値: up
, down
, left
, right
mobile_get_text
- 説明: 指定された要素のテキスト内容を取得します。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
mobile_set_text
- 説明: 指定された要素にテキスト内容を設定します。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
text
(文字列): 設定するテキスト内容
mobile_clear_text
- 説明: 入力ボックス内のテキスト内容をクリアします。
- パラメータ:
elementRef
(文字列): 入力ボックス要素のアクセシビリティ/自動化ID
mobile_click_element_by_text
- 説明: テキスト内容に基づいて指定されたUI要素をクリックします。
- パラメータ:
text
(文字列): 要素に表示されるテキスト内容
partialMatch
(ブール値, オプション): 部分一致を許可するかどうか。デフォルトは false
mobile_click_element_by_content_description
- 説明: コンテンツ説明に基づいて指定されたUI要素をクリックします。
- パラメータ:
contentDescription
(文字列): 要素のコンテンツ説明
partialMatch
(ブール値, オプション): 部分一致を許可するかどうか。デフォルトは false
mobile_wait_for_element
- 説明: 指定された要素が表示されるのを待ちます(例: ページの読み込み完了を待つ)。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
timeout
(数値, オプション): 待機時間のタイムアウト(ミリ秒)。デフォルトは 30000
mobile_take_screenshot
- 説明: 画面をスクリーンショットして保存します。
- パラメータ:
filename
(文字列, オプション): 保存するファイル名。デフォルトは自動生成
mobile_device_time
- 説明: デバイスの現在の時刻を取得します。
- パラメータ: なし
mobile_set_volume
- 説明: デバイスの音量を調整します。
- パラメータ:
volumeLevel
(数値): 音量レベル。範囲は 0
から 1.0
mobile_toggle_airplane_mode
- 説明: 飛行モードをオンまたはオフに切り替えます。
- パラメータ: なし
mobile_check_wifi_connection
- 説明: デバイスがWi-Fiネットワークに接続されているかどうかをチェックします。
- パラメータ:
ssid
(文字列, オプション): チェックするWi-FiのSSID
timeout
(数値, オプション): 待機時間のタイムアウト(秒)。デフォルトは 30
mobile_connect_to_wifi
- 説明: 指定されたWi-Fiネットワークに接続します。
- パラメータ:
ssid
(文字列): 接続するWi-FiのSSID
password
(文字列, オプション): Wi-Fiパスワード
mobile_disconnect_WIFI
- 説明: 現在のWi-Fi接続を切断します。
- パラメータ: なし
mobile_check_network_connection
- 説明: デバイスのネットワーク接続状態(モバイルデータとWi-Fiを含む)をチェックします。
- パラメータ:
networkType
(文字列, オプション): チェックするネットワークタイプ。選択可能な値: wifi
, mobile
mobile_set_geolocation
- 説明: デバイスの地理位置情報を設定します(模擬位置シナリオに適用)。
- パラメータ:
latitude
(数値): 緯度
longitude
(数値): 経度
altitude
(数値, オプション): 標高。デフォルトは 0
mobile_unset_geolocation
- 説明: デバイスのデフォルトの地理位置情報を復元します。
- パラメータ: なし
mobile_back_to_home_screen
- 説明: ホーム画面に戻ります。
- パラメータ: なし
mobile_launch_app
- 説明: 指定されたアプリケーションを起動します。
- パラメータ:
packageName
(文字列): アプリのパッケージ名
activityName
(文字列, オプション): 起動するActivity名。デフォルトはアプリのデフォルト起動ページ
mobile_close_app
- 説明: 現在のアプリケーションを閉じます。
- パラメータ:
packageName
(文字列): アプリのパッケージ名
mobile_clear_app_data
- 説明: アプリケーションのデータとキャッシュをクリアします。
- パラメータ:
packageName
(文字列): アプリのパッケージ名
mobile_install_apk
- 説明: デバイスにAPKファイルをインストールします。
- パラメータ:
apkPath
(文字列): APKファイルのパス
waitTime
(数値, オプション): インストール完了後の待機時間(秒)。デフォルトは 5
mobile_uninstall_apk
- 説明: 指定されたアプリケーションをアンインストールします。
- パラメータ:
packageName
(文字列): アプリのパッケージ名
mobile_push_file
- 説明: ファイルをデバイスに転送します。
- パラメータ:
localFilePath
(文字列): ローカルファイルのパス
remoteFileName
(文字列, オプション): デバイス上のファイル名。デフォルトはローカルファイル名と同じ
mobile_pull_file
- 説明: デバイスから指定されたファイルをローカルに取得します。
- パラメータ:
remoteFileName
(文字列): デバイス上のファイルパス
localSavePath
(文字列, オプション): ローカルの保存パス。デフォルトは現在の作業ディレクトリ
mobile_logcat_clear
- 説明: デバイスのlogcatログをクリアします。
- パラメータ: なし
mobile_logcat_dump
- 説明: デバイスのlogcatログをファイルにエクスポートします。
- パラメータ:
filename
(文字列, オプション): 保存するログファイル名。デフォルトは自動生成
mobile_input_text
- 説明: 入力ボックスにテキストを入力します(sendKeys操作に似ています)。
- パラメータ:
elementRef
(文字列): 入力ボックス要素のアクセシビリティ/自動化ID
text
(文字列): 入力するテキスト内容
mobile_input_number
- 説明: 数字入力ボックスに数値を入力します。
- パラメータ:
elementRef
(文字列): 数字入力ボックス要素のアクセシビリティ/自動化ID
numberValue
(数値): 入力する数値
mobile_switch_to_webview
- 説明: WebViewウィンドウに切り替えます(ハイブリッドアプリに適用)。
- パラメータ:
webViewIndex
(数値, オプション): 切り替えるWebViewのインデックス。デフォルトは最初のWebView
mobile_switch_to_native
- 説明: Native要素に切り替えます(ハイブリッドアプリに適用)。
- パラメータ: なし
mobile_get_current_context
- 説明: 現在のコンテキスト(NativeまたはWebView)を取得します。
- パラメータ:
result
(文字列): 現在のコンテキストのタイプ。返される値は NATIVE
, WEBVIEW
mobile_wait_for_element_text
- 説明: 指定された要素のテキスト内容が表示されるのを待ちます。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
expectedText
(文字列): 期待するテキスト内容
timeout
(数値, オプション): 待機時間のタイムアウト(ミリ秒)。デフォルトは 30000
mobile_compare_element_text
- 説明: 指定された要素の現在のテキスト内容と期待するテキストが一致するかどうかを比較します。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
expectedText
(文字列): 期待するテキスト内容
ignoreCase
(ブール値, オプション): 大文字と小文字を区別しないかどうか。デフォルトは false
mobile_is_element_present
- 説明: 指定された要素が存在するかどうかをチェックします。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
result
(ブール値): 存在する場合は true
、そうでない場合は false
mobile_is_element_enabled
- 説明: 指定された要素が有効(クリック可能)かどうかをチェックします。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
result
(ブール値): 有効な場合は true
、そうでない場合は false
mobile_is_element_selected
- 説明: 指定された要素が選択されているかどうかをチェックします(RadioButton、CheckBoxなど)。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
result
(ブール値): 選択されている場合は true
、そうでない場合は false
mobile_is_element_displayed
- 説明: 指定された要素が表示されているかどうかをチェックします。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
result
(ブール値): 表示されている場合は true
、そうでない場合は false
mobile_element_attribute
- 説明: 指定された要素の特定の属性値を取得します。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
attributeName
(文字列): 取得する属性名
result
(文字列): 属性に対応する値
mobile_element_text
- 説明: 指定された要素のテキスト内容を取得します。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
result
(文字列): テキスト内容
mobile_set_value
- 説明: 入力ボックスに値を設定します(sendKeys操作に似ています)。
- パラメータ:
elementRef
(文字列): 入力ボックス要素のアクセシビリティ/自動化ID
value
(文字列): 設定するテキスト内容
mobile_press_element
- 説明: 指定された要素をクリックします。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
times
(数値, オプション): クリック回数。デフォルトは 1
mobile_long_press_element
- 説明: 指定された要素を長押しします。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
duration
(数値, オプション): 長押し時間(ミリ秒)。デフォルトは 500
mobile_swipe_element
- 説明: 指定された要素をスワイプします(左、右方向)。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
direction
(文字列): スワイプ方向。選択可能な値: LEFT
, RIGHT
distance
(数値, オプション): スワイプ距離。デフォルトは要素の幅の半分
mobile_drag_element
- 説明: 指定された要素をドラッグします。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
targetElementRef
(文字列, オプション): ドラッグ先の目標要素のアクセシビリティ/自動化ID。デフォルトはnull(画面中央にドラッグ)
duration
(数値, オプション): ドラッグ操作の時間(ミリ秒)。デフォルトは 500
mobile_scroll_element
- 説明: 指定された要素をスクロールします。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
direction
(文字列): スクロール方向。選択可能な値: UP
, DOWN
, LEFT
, RIGHT
steps
(数値, オプション): スクロールステップ数。デフォルトは 1
mobile_pinch_element
- 説明: 指定された要素をピンチ操作します。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
scaleFactor
(数値, オプション): ピンチのスケール係数。範囲は (0,1)
。デフォルトは 0.5
duration
(数値, オプション): 操作時間(ミリ秒)。デフォルトは 500
mobile_zoom_element
- 説明: 指定された要素をズーム操作します。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
scaleFactor
(数値, オプション): ズームのスケール係数。範囲は (0,1)
または (1, infinity)
。デフォルトは 2
duration
(数値, オプション): 操作時間(ミリ秒)。デフォルトは 500
mobile_rotate_element
- 説明: 指定された要素を回転操作します。
- パラメータ:
elementRef
(文字列): 要素のアクセシビリティ/自動化ID
degrees
(数値, オプション): 回転角度。範囲は -180
から 180
。デフォルトは 90
duration
(数値, オプション): 操作時間(ミリ秒)。デフォルトは 500
mobile_tap_coordinates
- 説明: 指定された座標位置をクリックします。
- パラメータ:
x
(数値): クリックするX座標
y
(数値): クリックするY座標
mobile_tap_elements
- 説明: 要素のグループをクリックします。各要素を順番にクリックします。
- パラメータ:
elements
(配列): 要素のアクセシビリティ/自動化IDの配列
simultaneous
(ブール値, オプション): 同時にクリックするかどうか。デフォルトは false
mobile_long_tap_coordinates
- 説明: 指定された座標位置を長押しします。
- パラメータ:
x
(数値): 長押しするX座標
y
(数値): 長押しするY座標
duration
(数値, オプション): 長押し時間(ミリ秒)。デフォルトは 500
mobile_swipe_coordinates
- 説明: 指定された座標位置をスワイプします。
- パラメータ:
startX
(数値): 開始点のX座標
startY
(数値): 開始点のY座標
endX
(数値): 終了点のX座標
endY
(数値): 終了点のY座標
duration
(数値, オプション): スワイプ操作時間(ミリ秒)。デフォルトは 500
mobile_swipe_elements
- 説明: 要素のグループをスワイプします。各要素を順番にスワイプします。
- パラメータ:
elements
(配列): 要素のアクセシビリティ/自動化IDの配列
direction
(文字列, オプション): スワイプ方向。デフォルトは RIGHT
simultaneous
(ブール値, オプション): 同時にスワイプするかどうか。デフォルトは false
mobile_drag_coordinates
- 説明: 指定された座標位置をドラッグします。
- パラメータ:
startX
(数値): ドラッグ開始点のX座標
startY
(数値): ドラッグ開始点のY座標
endX
(数値): ドラッグ終了点のX座標
endY
(数値): ドラッグ終了点のY座標
duration
(数値, オプション): ドラッグ操作時間(ミリ秒)。デフォルトは 500
mobile_drag_elements
- 説明: 要素のグループをドラッグします。各要素を順番にドラッグします。
- パラメータ:
startElements
(配列): 開始点の要素のアクセシビリティ/自動化IDの配列
endElements
(配列): 終了点の要素のアクセシビリティ/自動化IDの配列
simultaneous
(ブール値, オプション): 同時にドラッグするかどうか。デフォルトは false
mobile_pinch_coordinates
- 説明: 指定された座標位置をピンチ操作します。
- パラメータ:
startX
(数値): 開始点のX座標
startY
(数値): 開始点のY座標
endX
(数値): 終了点のX座標
endY
(数値): 終了点のY座標
scaleFactor
(数値, オプション): スケール係数。デフォルトは 0.5
duration
(数値, オプション): 操作時間(ミリ秒)。デフォルトは 500
mobile_pinch_elements
- 説明: 要素のグループをピンチ操作します。各要素を順番にピンチします。
- パラメータ:
elements
(配列): 要素のアクセシビリティ/自動化IDの配列
simultaneous
(ブール値, オプション): 同時にピンチするかどうか。デフォルトは false
mobile_zoom_coordinates
- 説明: 指定された座標位置をズーム操作します。
- パラメータ:
x
(数値): ズームするX座標
y
(数値): ズームするY座標
scaleFactor
(数値, オプション): スケール係数。デフォルトは 2
duration
(数値, オプション): 操作時間(ミリ秒)。デフォルトは 500
mobile_zoom_elements
- 説明: 要素のグループをズーム操作します。各要素を順番にズームします。
- パラメータ:
elements
(配列): 要素のアクセシビリティ/自動化IDの配列
simultaneous
(ブール値, オプション): 同時にズームするかどうか。デフォルトは false
mobile_rotate_coordinates
- 説明: 指定された座標位置を回転操作します。
- パラメータ:
x
(数値): 回転するX座標
y
(数値): 回転するY座標
degrees
(数値, オプション): 回転角度。デフォルトは 90
duration
(数値, オプション): 操作時間(ミリ秒)。デフォルトは 500
mobile_rotate_elements
- 説明: 要素のグループを回転操作します。各要素を順番に回転します。
- パラメータ:
elements
(配列): 要素のアクセシビリティ/自動化IDの配列
degrees
(数値, オプション): 回転角度。デフォルトは 90
simultaneous
(ブール値, オプション): 同時に回転するかどうか。デフォルトは false
注意事項
- パラメータ名、タイプ、デフォルト値は例と同じに保つようにしてください。特に
simultaneous
などのブール型パラメータの処理に注意してください。
- 各操作関数について、入力パラメータの形式とデータ型が正しいことを確認し、必要なパラメータチェックを行ってください。
- 必要に応じて、複雑な機能や特殊なケースを説明するためのコメントを追加してください。
ソリューションコード
class MobileOperations {
constructor() {
this.operations = [];
}
addOperation(type, params) {
if (!this[type]) {
throw new Error('未知の操作タイプ');
}
this.operations.push({ type, params });
return this;
}
execute() {
for (const op of this.operations) {
this[op.type](op.params);
}
return this;
}
mobile_tap(params) {
const { x, y } = params;
if (typeof x !== 'number' || typeof y !== 'number') {
throw new Error('x と y は数値でなければなりません');
}
console.log(`座標 (${x}, ${y}) をクリックします`);
}
mobile_long_tap(params) {
const { x, y, duration = 500 } = params;
if (typeof x !== 'number' || typeof y !== 'number') {
throw new Error('x と y は数値でなければなりません');
}
console.log(`座標 (${x}, ${y}) を ${duration} ミリ秒長押しします`);
}
mobile_swipe(params) {
const { start, end, duration = 500 } = params;
if (typeof start.x !== 'number' || typeof start.y !== 'number') {
throw new Error('start は x と y 座標を持たなければなりません');
}
if (typeof end.x !== 'number' || typeof end.y !== 'number') {
throw new Error('end は x と y 座標を持たなければなりません');
}
console.log(`(${start.x}, ${start.y}) から (${end.x}, ${end.y}) へスワイプします`);
}
mobile_drag(params) {
const { start, end, duration = 500 } = params;
if (typeof start.x !== 'number' || typeof start.y !== 'number') {
throw new Error('start は x と y 座標を持たなければなりません');
}
if (typeof end.x !== 'number' || typeof end.y !== 'number') {
throw new Error('end は x と y 座標を持たなければなりません');
}
console.log(`(${start.x}, ${start.y}) から (${end.x}, ${end.y}) へドラッグします`);
}
mobile_pinch(params) {
const { points, scale = 0.5, duration = 500 } = params;
if (!Array.isArray(points)) {
throw new Error('points は配列でなければなりません');
}
console.log(`点 ${JSON.stringify(points)} をピンチし、スケール係数は ${scale} です`);
}
mobile_rotate(params) {
const { center, startAngle, endAngle, duration = 500 } = params;
if (typeof center.x !== 'number' || typeof center.y !== 'number') {
throw new Error('center は x と y 座標を持たなければなりません');
}
console.log(`点 (${center.x}, ${center.y}) を中心に、${startAngle} 度から ${endAngle} 度へ回転します`);
}
static example() {
const operations = new MobileOperations()
.addOperation('mobile_tap', { x: 100, y: 200 })
.addOperation('mobile_long_tap', { x: 300, y: 400, duration: 1000 })
.addOperation('mobile_swipe', {
start: { x: 50, y: 50 },
end: { x: 250, y: 250 }
})
.addOperation('mobile_drag', {
start: { x: 100, y: 100 },
end: { x: 300, y: 300 }
})
.addOperation('mobile_pinch', {
points: [{ x: 150, y: 150 }, { x: 250, y: 250 }],
scale: 0.8
})
.addOperation('mobile_rotate', {
center: { x: 200, y: 200 },
startAngle: 0,
endAngle: 360
});
operations.execute();
}
}
MobileOperations.example();
説明
このソリューションでは、MobileOperations
クラスを定義して、モバイルデバイスの様々なインタラクション操作を管理しています。各操作(クリック、長押し、スワイプなど)は独立したメソッドとして封じ込められており、これらの操作をキューに追加して、最後に execute()
メソッドで順番に実行できます。
主な特徴は以下の通りです。
- モジュール化設計:各操作は独立したメソッドであり、保守と拡張が容易です。
- 組み合わせ可能:ユーザーは異なる操作を柔軟に組み合わせて、複雑なインタラクションロジックを実現できます。
- エラー処理:各メソッドでパラメータの検証を行い、入力の正確性を確保します。
この方法により、開発者は簡単に様々なモバイルデバイスのインタラクション操作を構築して実行できます。