Appium命令

“Appium Vega驱动程序”支持以下万维网联盟 (W3C) WebDriver命令：

find_element

find_element命令可查找与指定选择器策略相匹配的第一个用户界面元素。

复制代码 已复制到剪贴板。

element = driver.find_element('UiSelector', '{"args": {"text": "元素文本"}}')

要将XPath与Appium Vega驱动程序一起使用，您可以采用By.xpath() 定位器策略。

复制代码 已复制到剪贴板。

appium_driver.find_element(by="xpath", value="//*[contains(@clickable, \”true\”)]”)

参数

常见的XPath表达式组成部分

XPath表达式包含以下组成部分：

• 轴 - 指定搜索方向，例如后代轴、祖先轴和后续轴。
• 节点测试 - 指定要选择的节点类型，例如element、attribute或text()。
• 谓词 - 根据各种条件（例如属性值、位置或自定义函数）筛选所选节点。

以下示例演示了XPath表达式的各个组成部分：

//Text[@text='Click me', @test-id='1234']

find_elements

find_elements命令可查找多个用户界面元素，支持各种定位器策略，并返回一个元素数组（即使为空，也会返回空数组）。使用此命令执行以下操作：

• 遍历列表
• 验证多个控件

为了获得最佳性能和可靠性，请采用特定的定位器策略和适当的超时设置。在复杂的用户界面场景中，使用分层XPath等高级技术。

element = driver.find_elements('UiSelector', '{
     "args": {
         "text": “元素文本”
     }
   }'
 )

参数

find_element与find_elements的比较

要在父元素的上下文中找到子元素，请找到包含子元素的封闭元素。

window = driver.find_element("xpath", '//window[@id="{window_id}"]')

button_child_xpath = window.find_element("xpath", '//child[@test_id="button-insert"]')

button_child_uiselector = window.find_element("UiSelector", '{"args": {"test_id": "button-insert"}}')

click

click命令可模拟单击特定元素中心点的操作。虽然有各种定位器策略可供选择，但单击元素ID是一种可靠且可维护的方法。

button = appium_driver.find_element("UiSelector", '{"args":{ "text": "Button 1" }}')
button.click()

参数

click命令会对之前找到的元素执行操作，因此不需要使用参数。

send_keys

send_keys命令可模拟在元素中键入文本的操作，并且需要一个字符串参数。

# 启动测试应用后
editableEle = appium_driver.find_element("UiSelector", '{"args":{ "role": "edit" }}')
editableEle.send_keys("the quick brown fox")

参数

最佳实践：

• 验证目标元素是否含有焦点并已准备好接收输入。
• 在发送按键之前，请检查元素焦点。在发送按键之前，使用click() 等命令来选择元素。
• 在发送按键的间隔时间添加短暂延迟，因为快速或同步输入可能会导致某些设备或应用出现问题。

get_attribute

get_attribute命令可检索用户界面元素的指定属性的值。

button = appium_driver.find_element("UiSelector", '{"args":{ "text": "按钮" }}')
buttonText = button.get_attribute("UiObject:text")
assert buttonText == '["按钮"]' 

参数

属性列表

get_element_text

get_element_text命令检索用户界面元素的可见文本内容。它返回用户可见的文本，不包括任何隐藏的文本。

element = appium_driver.find_element("UiSelector", '{"args":{ "text": "按钮" }}')
text = element.text
print(f"元素文本：{text}")

参数

get_element_text命令会对之前找到的元素执行操作，因此不需要使用参数。

最佳实践：

• 在尝试获取其文本之前，请验证元素是否存在。
• 适当处理潜在空文本返回。
• 考虑断言中的文本格式和特殊字符。
• 需要时使用适当的等待策略。

press_keycode

press_keycode命令可模拟按下设备上特定硬件按键的操作。请谨慎使用，因为它可能会影响应用状态和测试流程，并且仅接受数字键码（不接受十六进制代码）。

driver.press_keycode({KEYCODE})

参数

tap

tap命令可模拟点击屏幕上一组特定坐标的操作。此命令可以精确控制触摸交互，但应谨慎使用。

buttonCoordinates = (200, 350)
appium_driver.tap([buttonCoordinates])

参数

最佳实践：

虽然tap可提供细粒度控制，但为了确保测试的稳定性和可维护性，应优先考虑基于元素的交互。仅当基于元素的方法不可行时才使用。

is_enabled

is_enabled命令检查用户界面元素的当前状态。如果已启用（交互），则返回true；如果已禁用（非交互），则返回false。

element = appium_driver.find_element("UiSelector", '{"args":{ "text": "Button 1" }}')
element.is_enabled()

启用的元素允许用户交互。但是，启用状态并不能保证交互性。元素可能以启用状态发挥作用，但缺乏可见性或存在其他交互障碍。要验证元素的交互性，请结合使用is_enabled与其他命令（例如is_displayed）。

参数

is_enabled命令会对之前找到的元素执行操作，因此不会接受参数。

最佳实践：

• 将is_enabled用作全面元素状态检查中的一个环节。
• 不要依赖is_enabled来确定元素的交互性。
• 在检查元素状态之前实施等待策略。

is_displayed

is_displayed命令用于检查用户界面元素在屏幕上是否可见。如果可见，则返回true；如果已隐藏，则返回false。

element = driver.find_element('UiSelector', '{"args": {"test_id": "my_button"}}')
element.is_displayed()

当元素出现在屏幕边界内时，会变得可见。

参数

is_displayed命令会对之前找到的元素执行操作，因此不会接受参数。

最佳实践：

• 将is_displayed用作全面元素状态检查中的一个环节。

implicitly_wait

implicitly_wait命令用于设置搜索不可用元素时的等待时间。虽然此命令增强了测试稳定性，但请谨慎使用。对于复杂场景，请结合使用implicitly_wait与explicit waits，以平衡可靠性和执行速度。

driver.implicitly_wait(5)

有关详细实现，请参阅设置隐式等待时间（仅提供英文版）。

参数

最佳实践：

• 在测试开始时设置implicitly_wait。
• 如有必要，重置为合理的默认值（例如0毫秒）。

get_window_rect

get_window_rect命令可检索当前应用窗口相对于整体屏幕大小的大小和位置。

示例：

Python

res = driver.get_window_rect()

Java

Dimension windowSize = driver.manage().window().getSize(); # 返回窗口大小 (width, height)
Point windowOrigin = driver.manage().window().getPosition(); # 返回窗口原始坐标 (x, y)

其中：

• x - 窗口左侧坐标
• y - 窗口顶部坐标
• width - 窗口的宽度
• height - 窗口的高度

参数

不需要任何参数。

最佳实践：

结合使用get_window_rect与其他命令，以创建稳健的测试脚本来处理不同的屏幕尺寸和布局。

get_page_source

get_page_source命令检索应用的当前页面源，该源代表底层用户界面结构。

Python

page_source = driver.page_source
print(page_source)

Java

String pageSource = driver.getPageSource();
System.out.println(pageSource);

参数

get_page_source命令不需要任何参数。

get_screenshot

get_screenshot命令以base64编码字符串的形式捕获当前应用状态。使用此命令时，需考虑用户隐私。不要捕获数字版权管理 (DRM) 内容。

Python

screenshot_base64 = driver.get_screenshot_as_base64() # 以base64编码字符串形式获取屏幕截图

Java

File screenshotFile     = ((TakesScreenshot)driver).getScreenshotAs(OutputType.FILE); // 获取屏幕截图并将其存储在文件中
byte[] screenshotRaw    = ((TakesScreenshot)driver).getScreenshotAs(OutputType.BYTES); // 获取屏幕截图的原始字节
String screenshotBase64 = ((TakesScreenshot)driver).getScreenshotAs(OutputType.BASE64); // 以base64编码字符串形式获取屏幕截图

有关方法的完整列表和示例，请参阅Appium文档（仅提供英文版）。

参数

此命令不需要任何参数。

install_app

install_app命令用于在设备上安装应用。VPKG文件路径必须在主机（Appium服务器）的文件系统上可用。在测试开始时，使用此命令来自动设置环境。

示例：

Python：

driver.install_app('/path/to/app.vpkg')

Java：

driver.executeScript("mobile: installApp", Map.of("appPath", "/path/to/app.vpkg"));

参数

activate_app

activate_app命令用于在设备上启动指定的应用或将其置于前台。此命令可用于测试应用切换场景，或在执行进一步测试操作之前确认特定应用处于活动状态。

示例：

Python：

driver.activate_app('com.example.myapp.main')

Java：

boolean isInstalled = (boolean) driver.executeScript("mobile: activateApp",
    Map.of("appId", "com.example.myapp.main"));

参数

最佳实践

要获取用于启动应用的正确appId，请运行vpm list applications。

terminate_app

terminate_app命令可以停止当前正在运行的应用。当测试应用在强制关闭期间的行为或建立测试案例之间的干净状态时，使用此命令。

示例：

driver.terminate_app('com.example.myapp')

参数

remove_app

remove_app命令用于从设备上卸载应用。

示例：

driver.remove_app('com.example.myapp')

参数

execute_script

execute_script命令可以运行shell命令或调用jsonrpc API。

要在设备上执行shell命令，请执行以下操作。

appium_driver.execute_script("shell", "echo hello world") #

要调用Appium公共接口中未公开的jsonrpc API，请执行以下操作：

appium_driver.execute_script("jsonrpc: getScreenContext", "")

push_file

push_file命令让您能够将文件直接传输到设备。必须以base64编码字符串形式提供文件内容。用例包括上传测试数据、配置文件或测试执行期间所需的任何其他文件。

Python：

with open('test_image.png', 'rb') as image_file:
    image_data = base64.b64encode(image_file.read()).decode('utf-8')
    driver.push_file('/data/local/tmp/test_image.png', image_data)

Java：

File fileToUpload = new File("/path/to/your/file.txt");
String base64Content;
try {
    // 将文件内容转换为Base64
    byte[] fileContent = FileUtils.readFileToByteArray(fileToUpload);
    base64Content = Base64.getEncoder().encodeToString(fileContent);
 
    // 执行pushFile命令
    driver.executeScript("mobile: pushFile", Map.of(
            "remotePath", "/tmp/uploaded_file.txt",
            "payload", base64Content
    ));
 
    System.out.println（“文件上传成功”）;
} catch (IOException e) {
    System.err.println（“上传文件时出错：”+ e.getMessage()）;
    e.printStackTrace();
}

参数

pull_file

push_file命令让您能够直接从设备传输文件。该命令以base64编码字符串形式返回文件内容。用例包括下载测试结果、配置文件或测试执行期间及之后所需的任何其他文件。

Python：

base64_string = driver.pull_file("/tmp/testFile.txt")

Java：

try {
    // 从目录中提取文件
    Object fileBase64 = driver.executeScript("mobile: pullFile", Map.of("remotePath", "/tmp/testFile.txt"));
    System.out.println（“文件下载成功”）;
} catch (IOException e) {
    System.err.println（“下载文件时出错：”+ e.getMessage()）;
    e.printStackTrace();
}

参数

方向键导航

execute_script函数通过jsonrpc: injectInputKeyEvent方法发送Linux输入事件代码。此功能可让您的应用以编程方式模拟用户输入事件，以进行自动化和测试。

该函数在脚本中运行指定的命令和按键事件，从而在专为方向键输入而设计的应用中实现方向键导航。

该表列出了输入事件代码。

有关已定义键码的完整列表，请参阅输入事件代码（仅提供英文版）。输入事件代码参考有助于创建无障碍且实用的键盘体验。对特定键码的支持因设备类型和输入配置而异。测试针对非标准键盘布局或行为的键盘输入处理。

为 injectInputKeyEvent使用以下命令：

driver.execute_script("jsonrpc: injectInputKeyEvent",[{"inputKeyEvent": "{EVENT}" , "holdDuration": 1000}])

例如，使用以下命令进行向下导航。

driver.execute_script("jsonrpc: injectInputKeyEvent",[{"inputKeyEvent": "108" , "holdDuration": 1000}])

• 上一步 – 使用Appium Vega驱动程序编写测试
• 下一步 – 使用Appium检查器来检查应用

Last updated: 2025年10月31日