Mobile MCP

🚀 移動設備命令與交互工具文檔

本項目旨在打造一個靈活且可靠的移動設備自動化測試框架，支持藉助輔助功能定位器（preferred）和基於座標的輸入開展操作。用戶能夠依據實際需求挑選不同的定位方式，進而實現無縫的自動化流程。

🚀 快速開始

本項目提供了一系列用於操作移動設備的命令和方法，可通過調用相應的函數來實現各種功能，如應用管理、屏幕操作、網絡連接管理等。

✨ 主要特性

• 豐富的命令集：涵蓋了應用管理、屏幕操作、網絡連接管理等多種功能，滿足不同場景下的移動設備自動化測試需求。
• 靈活的定位方式：支持通過輔助功能定位器和基於座標的輸入進行操作，用戶可根據實際情況選擇合適的定位方式。
• 參數校驗：在每個操作函數中都進行了必要的參數校驗，確保輸入參數的格式和數據類型正確。
• 可組合性：允許用戶靈活地組合不同的操作來實現複雜的交互邏輯。

📦 安裝指南

文檔未提及安裝相關內容，故跳過此章節。

💻 使用示例

基礎用法

// 示例：使用 mobile_tap_elements 函數依次點擊兩個元素
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

• 描述：在指定的屏幕座標上點擊。
• 參數：
  • x (數字)：X 座標
  • y (數字)：Y 座標

mobile_list_elements_on_screen

• 描述：列出屏幕上所有元素及其座標，包括顯示文本或輔助功能標籤。
• 參數：無

mobile_element_tap

• 描述：根據輔助功能定位器點擊指定的 UI 元素。
• 參數：
  • element (字符串)：人類可讀的元素描述（例如，“登錄按鈕”）。
  • ref (字符串)：輔助功能/自動化 ID 或從快照中獲取的引用。

mobile_tap

• 描述：在指定的屏幕座標上點擊。
• 參數：
  • x (數字)：X 座標
  • y (數字)：Y 座標

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

• 描述：在兩個座標點之間執行滑動操作。
• 參數：
  • 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

• 描述：對指定元素進行 pinch（捏）操作。
• 參數：
  • elementRef (字符串)：元素的輔助功能/自動化 ID
  • scaleFactor (數字, 可選)：捏合的比例因子，範圍在 (0,1) 之間，默認為 0.5
  • duration (數字, 可選)：操作的時間，以毫秒為單位，默認為 500

mobile_zoom_element

• 描述：對指定元素進行 zoom（縮放）操作。
• 參數：
  • 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

• 描述：在指定座標位置進行 pinch（捏）操作。
• 參數：
  • startX (數字)：起始點的 x 座標
  • startY (數字)：起始點的 y 座標
  • endX (數字)：終止點的 x 座標
  • endY (數字)：終止點的 y 座標
  • scaleFactor (數字, 可選)：縮放比例，默認為 0.5
  • duration (數字, 可選)：操作的時間，以毫秒為單位，默認為 500

mobile_pinch_elements

• 描述：對一組元素進行 pinch（捏）操作，按順序依次捏每個元素。
• 參數：
  • elements (數組)：元素的輔助功能/自動化 ID 數組
  • simultaneous (布爾值, 可選)：是否同時捏，默認為 false

mobile_zoom_coordinates

• 描述：在指定座標位置進行 zoom（縮放）操作。
• 參數：
  • x (數字)：縮放的 x 座標
  • y (數字)：縮放的 y 座標
  • scaleFactor (數字, 可選)：縮放比例，默認為 2
  • duration (數字, 可選)：操作的時間，以毫秒為單位，默認為 500

mobile_zoom_elements

• 描述：對一組元素進行 zoom（縮放）操作，按順序依次縮放每個元素。
• 參數：
  • elements (數組)：元素的輔助功能/自動化 ID 數組
  • simultaneous (布爾值, 可選)：是否同時縮放，默認為 false

mobile_rotate_coordinates

• 描述：在指定座標位置進行旋轉操作。
• 參數：
  • x (數字)：旋轉的 x 座標
  • y (數字)：旋轉的 y 座標
  • degrees (數字, 可選)：旋轉角度，默認為 90
  • duration (數字, 可選)：操作的時間，以毫秒為單位，默認為 500

mobile_rotate_elements

• 描述：對一組元素進行旋轉操作，按順序依次旋轉每個元素。
• 參數：
  • elements (數組)：元素的輔助功能/自動化 ID 數組
  • degrees (數字, 可選)：旋轉角度，默認為 90
  • simultaneous (布爾值, 可選)：是否同時旋轉，默認為 false

注意事項

⚠️ 重要提示

1. 參數名、類型及默認值請保持與示例中的統一，特別是布爾型參數如 simultaneous 的處理。
2. 對於每個操作函數，請確保輸入參數的格式和數據類型正確，並進行必要的參數校驗。
3. 如有必要，可以添加更多的註釋來解釋複雜的功能或特殊情況。

解決方案代碼

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() 方法依次執行。

主要特點包括：

1. 模塊化設計：每個操作都是一個獨立的方法，便於維護和擴展。
2. 可組合性：允許用戶靈活地組合不同的操作來實現複雜的交互邏輯。
3. 錯誤處理：在每個方法中都進行了參數驗證，確保輸入的正確性。

通過這種方式，開發者可以輕鬆地構建和執行各種移動設備的交互操作。

🔧 技術細節

移動設備的交互操作通常包括點擊、長按、滑動、拖拽、捏合和旋轉等基本操作。為了實現這些操作，可以將每一種操作封裝成一個函數，並允許它們組合在一起執行。

這個解決方案中定義了一個 MobileOperations 類，它包含各種移動設備操作的方法（如點擊、長按等），每個方法對應一種交互類型。通過使用 addOperation 方法可以將多種操作添加到操作隊列中，最後調用 execute() 方法來依次執行這些操作。

這種方法允許用戶靈活地組合不同的操作，並且每個操作獨立實現，便於擴展和維護。

📄 許可證

文檔未提及許可證相關內容，故跳過此章節。