🚀 移动设备命令与交互工具文档

本项目旨在打造一个灵活且可靠的移动设备自动化测试框架，支持借助辅助功能定位器（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() 方法来依次执行这些操作。

这种方法允许用户灵活地组合不同的操作，并且每个操作独立实现，便于扩展和维护。

📄 许可证

文档未提及许可证相关内容，故跳过此章节。