AppiumLibrary中文翻译
AppiumLibrary
原文链接： http://serhatbolsu.github.io/robotframework-appiumlibrary/AppiumLibrary.html
| 版本: | 1.5.0.7 |
|---|---|
| 生效范围: | GLOBAL |
| 具名参数: | 支持 |
介绍
AppiumLibrary是一个Robot Framework的移动应用测试库
定位及指定元素
AppiumLibrary中，所有关键字都需要一个定位符locator或页面元素webelement参数，以便在页面上找到元素。
定位符locator是描述定位策略及语法的一个字符串。 页面元素webelement是一个代表页面元素的WebElement对象。
使用定位符
默认情况下，提供定位符后，它会根据指定的关键属性来匹配特定元素类型。 对于iOS和Android，id 是所有元素的关键属性，只需使用id即可轻松定位元素，例如：
Click Element id=my_element
AppiumLibrary1.4中的新增功能，使用id和xpath定位可以省略定位方式。xpath表达式以//开头时，可以省略定位方式xpath，否则需要明确指定使用xpath定位。
例如：
Click Element my_element
Wait Until Page Contains Element //*[@type="android.widget.EditText"]
Appium还支持Mobile JSON Wire Protocol的一些其他定位策略。 AppiumLibrary还支持，通过指定定位方式加定位表达式来定位元素。支持的定位方式有：
| 定位方式 | 示例 | 说明 | 注意 |
|---|---|---|---|
| identifier | Click Element identifier=my_element | 通过id属性定位 | |
| id | Click Element id=my_element | 通过resource-id属性定位 | |
| accessibility_id | Click Element accessibility_id=button3 | 通过content-desc属性定位 | |
| xpath | Click Element xpath=//UIATableView/UIATableCell/UIAButton | 通过任意XPath定位 | |
| class | Click Element class=UIAPickerWheel | 通过class定位 | |
| android | Click Element android=UiSelector().description('Apps') | 通过Android UI Automator定位 | |
| ios | Click Element ios=.buttons().withName('Apps') | 通过iOS UI Automation定位 | |
| nsp | Click Element nsp=name=="login" | 通过iOSNsPredicate定位 | Check PR: #196 |
| chain | Click Element chain=XCUIElementTypeWindow[1]/* | 通过iOS Class Chain定位 | |
| css | Click Element css=.green_button | 通过css定位webview元素 | |
| name | Click Element name=my_element | 通过name属性定位 | 仅支持Selendroid引擎 |
使用页面元素
从AppiumLibrary的1.4版开始，除定位符locator外，还可以传递一个包含页面元素WebElement对象。可以使用Get WebElements或Get WebElement关键字，来获取面元素WebElement对象。
例如：
@{elements} Get Webelements class=UIAButton
Click Element @{elements}[2]
导入
| 参数 | 说明 |
|---|---|
| timeout=5, run_on_failure=Capture Page Screenshot | AppiumLibrary导入时可以包含一些可选参数。timeout 是所有等待操作的默认等待时间. 也可以后面使用关键字 Set Appium Timeout进行设置。run_on_failure 用于指定AppiumLibrary关键字执行失败时要执行的关键字 (可以来这任何可用的库)，默认使用Capture Page Screenshot对当前页面截图。 使用No Operation 将完全禁用此功能。 该功能的更对信息可以参考关键字Register Keyword To Run On Failure 。 示例: # 设置默认超时时间为10秒，出错后不做任何操作 `Library |
捷径
Background App · Capture Page Screenshot · Clear Text · Click A Point · Click Button · Click Element · Click Element At Coordinates · Click Text · Close All Applications · Close Application · Element Attribute Should Match · Element Name Should Be · Element Should Be Disabled · Element Should Be Enabled · Element Should Be Visible · Element Should Contain Text · Element Should Not Contain Text · Element Text Should Be · Element Value Should Be · Execute Adb Shell · Execute Async Script · Execute Script · Get Activity · Get Appium SessionId · Get Appium Timeout · Get Capability · Get Contexts · Get Current Context · Get Element Attribute · Get Element Location · Get Element Size · Get Matching Xpath Count · Get Network Connection Status · Get Source · Get Text · Get Webelement · Get Webelements · Get Window Height · Get Window Width · Go Back · Go To Url · Hide Keyboard · Input Password · Input Text · Input Value · Install App · Is Keyboard Shown · Landscape · Launch Application · Lock · Log Source · Long Press · Long Press Keycode · Open Application · Page Should Contain Element · Page Should Contain Text · Page Should Not Contain Element · Page Should Not Contain Text · Pinch · Portrait · Press Keycode · Pull File · Pull Folder · Push File · Quit Application · Register Keyword To Run On Failure · Remove Application · Reset Application · Scroll · Scroll Down · Scroll Up · Set Appium Timeout · Set Location · Set Network Connection Status · Shake · Start Activity · Start Screen Recording · Stop Screen Recording · Swipe · Swipe By Percent · Switch Application · Switch To Context · Tap · Text Should Be Visible · Toggle Touch Id Enrollment · Touch Id · Wait Activity · Wait Until Element Is Visible · Wait Until Page Contains · Wait Until Page Contains Element · Wait Until Page Does Not Contain · Wait Until Page Does Not Contain Element · Xpath Should Match X Times · Zoom
关键字
| 关键字 | 参数 | 说明 |
|---|---|---|
| Background App | seconds=5 | 将应用置于设备后台一段时间。 |
| Capture Page Screenshot | filename=None | 对当前页面截图并嵌入日志。 filename 参数用于指定写入截图的文件名称。 如果没有指定filename, 截图将以appium-screenshot-.png名称保存在日志文件所在目录中。 如果filename没有使用绝对路径，则也被视为使用同一目录。 css 可用于修改截图样式。 默认情况下，会自动更改背景色以避免页面布局被破坏时背景泄漏等可能问题。 |
| Clear Text | locator | 清空定位符locator所定位到的元素。 元素定位详情，可以参考介绍 。 |
| Click A Point | x=0, y=0, duration=100 | 点击指定坐标 |
| index_or_name | 点击按钮 | |
| Click Element | locator | 点击定位符locator指定元素。 任意元素的关键属性为index及name。 元素定位详情，可以参考介绍。 |
| Click Element At Coordinates | coordinate_X, coordinate_Y | 点击元素指定坐标 |
| Click Text | text, exact_match=False | 单击以text标识的文本。默认情况下，单击定位到的第一个文本。 如果想单击完全匹配的文本，则将exact_match设置为True。 如果不想要第一个，可以使用locator与Get Web Elements结合使用。 |
| Close All Applications | 关闭所有应用。 该关键字用于用例及测试套件teardown测试清理过程，以确保测试结束前所有应用都被关闭。 执行该关键字后，由Open Application返回的应用所有被重置为1. |
|
| Close Application | 关闭应用及WebDriver会话 | |
| Element Attribute Should Match | locator, attr_name, match_pattern, regexp=False | 验证定位符定位到的元素的指定属性，匹配指定规则。 元素定位详情，可以参考介绍 。如果匹配到多个元素，则选择第一个元素。 attr_name是所选元素内的属性的名称。 match_pattern用于匹配，如果match_pattern为如下值： 布尔值或'True'/'true'，则将 'False'/'false'字符串，然后应用布尔匹配 任何其他字符串都会导致字符串匹配。 regexp定义是否使用正则表达式(如BuiltIn库的Should Match Regexp)或字符串匹配(如BuiltIn库的Should Match 示例: `Element Attribute Should Match |
| Element Name Should Be | locator, expected | 验证定位符locator指定元素name属性为expected文本。 |
| Element Should Be Disabled | locator, loglevel=INFO | 验证定位符locator指定元素不可用。任意元素的关键属性为id及name。 元素定位详情，可以参考介绍 |
| Element Should Be Enabled | locator, loglevel=INFO | 验证定位符locator指定元素可用。任意元素的关键属性为id及name。 元素定位详情，可以参考介绍 |
| Element Should Be Visible | locator, loglevel=INFO | 验证定位符locator指定元素可见。 任意元素的关键属性为id及name。 元素定位详情，可以参考介绍。 AppiumLibrary 1.4.5新功能 |
| Element Should Contain Text | locator, expected, message= | 验证定位符locator指定元素text属性中包含expected文本。如果想验证元素文本完全等于指定文本，可以使用Element Text Should Be.任意元素的关键属性为id及xpath。 message用于覆盖默认的出错信息。AppiumLibrary 1.4新功能 |
| Element Should Not Contain Text | locator, expected, message= | 验证定位符locator指定元素text属性中不包含expected文本。message用于覆盖默认的出错信息。 S详情参考Element Should Contain Text |
| Element Text Should Be | locator, expected, message= | 验证locator指定元素text属性中应为expected指定文本。相反关键字为Element Should Contain Text, 本关键字不支持包含，需要需要完全等于。message用于覆盖默认的出错信息。AppiumLibrary 1.4新功能 |
| Element Value Should Be | locator, expected | 元素value属性应为expected指定文本 |
| Execute Adb Shell | command, *args | 执行Adb Shell命令，仅支持Android。 command - Adb Shell命令 args - 命令参数 返回Adb Shell命令退出码exit code。 需要在Appium服务器上设置服务器标志 --relaxed-security。 |
| Execute Async Script | script | (仅限Web页面) 在当前框架中注入异步JavaScript脚本。 函数最后一个参数为指定的回调函数，异步执行的脚本执行后调用回调函数，并将回调函数的返回值返回给客户端。 AppiumLibrary 1.5新功能 |
| Execute Script | script | (仅限Web页面) 在当前框架中注入通过JavaScript脚本。 执脚本执行后将返回值返回给客户端。 AppiumLibrary 1.5新功能 |
| Get Activity | 获取设备当前Activity页面，仅支持Android。 | |
| Get Appium SessionId | 返回当前会话ID作为参考 | |
| Get Appium Timeout | 返回当前设置的Appium超时时间，单位秒。相关解释可参考[Set Appium Timeout | |
| Get Capability | capability_name | 返回desired capability指定配置项的值 |
| Get Contexts | 获取当前所有可用的上下文 | |
| Get Current Context | 获取当前上下文。 | |
| Get Element Attribute | locator, attribute | 获取元素属性，支持的属性为: name, value。 示例: `Get Element Attribute |
| Get Element Location | locator | 获取locationKey属性 for arbitrary elements are id and name. 元素定位详情，可以参考介绍 |
| Get Element Size | locator | 获取元素尺寸。 任意元素的关键属性为id及name.. 元素定位详情，可以参考介绍 |
| Get Matching Xpath Count | xpath | 返回Xpath匹配到的元素个数，Xpath表达式不可以使用xpath=前缀。正确示例: ${count} | Get Matching Xpath Count | //android.view.View[@text='Test']错误示例: `$ |
| Get Network Connection Status | 返回设备网络状态整数位掩码，仅支持Android。 详情参看Set network connection status |
|
| Get Source | 获取当前页面的整个源码 | |
| Get Text | locator | 获取元素文本(在混合App和移动浏览器中使用xpath定位符, 其他可能会有问题) 示例： `$ |
| Get Webelement | locator | 返回 locator定位到的第一个WebElement对象。示例： ${element} Get Webelement id=my_element Click Element ${element}AppiumLibrary 1.4新功能 |
| Get Webelements | locator | 返回locator定位到的 WebElement对象列表。示例： `@ |
| Get Window Height | 获取当前设备屏幕高度。 示例： `$ |
|
| Get Window Width | 获取当前设备屏幕宽度。 示例： `$ |
|
| Go Back | 在浏览器中返回上一个页面 | |
| Go To Url | url | 在默认浏览器上打开URL 示例： `Open Application |
| Hide Keyboard | key_name=None | 在设备上隐藏键盘。 可选参数 在iOS,上，使用 key_name 按下指定键, 如. Done 在Android上, 无须参数 |
| Input Password | locator, text | 在通过locator定位到的元素中输入指定密码 与Input Text不同的是，密码不会记录在日志中 元素定位详情，可以参考介绍 |
| Input Text | locator, text | 在定位符指定元素输入框中输入指定text文本。 元素定位详情，可以参考介绍 |
| Input Value | locator, text | 仅限iOS设备，使用set_value在通过locator定位到的元素中输入指定文本元素定位详情，可以参考介绍 |
| Install App | app_path, app_package | 通过Appium安装App，仅支持Android。 app_path - Apk文件路径 app_package - 待验证app包名 |
| Is Keyboard Shown | 如果Android键盘显示则返回True，否则返回False，无须参数。 | |
| Landscape | 设置屏幕方向为横屏模式 | |
| Launch Application | 加载应用，可以在Appium会话中加载应用。 该关键字可用于在用例中或用例间启动应用 在使用Open Application打开应用运行测试时，推荐在用例之间，使用Launch Application和Quit Application打开和关闭应用。 可以在测试套件的Test Setup中使用Open Application来启动应用。 示例： 以下为伪代码, Setup/Teardown使用可参考RF Guide:`[Setup Suite] |
|
| Lock | seconds=5 | 锁定屏幕一定时间，仅支持iOS。 |
| Log Source | loglevel=INFO | 记录日志并返回当前页面的HTML源码 loglevel参数用于定义用例等级 可用日志等级为 WARN, INFO (默认), DEBUG, TRACE and NONE (不输出日志) |
| Long Press | locator, duration=1000 | 长按元素指定时间 |
| Long Press Keycode | keycode, metastate=None | 在设备上长按一个键 详情参考press keycode |
| Open Application | remote_url, alias=None, **kwargs | 在指定Appium Server上打开一个新的应用。 Andorid及iOS相关Appium Server预期功能配置请参考Appium server-args remote_url Appium server url alias 别名 示例: `Open Application |
| Page Should Contain Element | locator, loglevel=INFO | 验证当前页面包含定位符 locator指定元素，如果验证失败，则自动在日志中记录页面源码。 可以使用loglevel参数指定输出日志等级，设置为NONE关闭输出页面源码。 |
| Page Should Contain Text | text, loglevel=INFO | 验证当前页面包含text指定文本，如果验证失败，则自动在日志中记录页面源码。 可以使用loglevel参数指定输出日志等级，设置为NONE关闭输出页面源码。 |
| Page Should Not Contain Element | locator, loglevel=INFO | 验证当前页面不包含locator指定元素, 如果验证失败，则自动在日志中记录页面源码。 可以使用loglevel参数指定输出日志等级，设置为NONE关闭输出页面源码。 |
| Page Should Not Contain Text | text, loglevel=INFO | 验证当前页面不包含text指定文本，如果验证失败，则自动在日志中记录页面源码。 可以使用loglevel参数指定输出日志等级，设置为NONE关闭输出页面源码。 |
| Pinch | locator, percent=200%, steps=1 | 在指定元素出捏合指定倍速 |
| Portrait | 将设备方向设置为竖向 | |
| Press Keycode | keycode, metastate=None | 向设备发送一个按键指令，仅支持Android。 可用按键编码keycodes及元状态metastate可参考: Android官方KeyEvent。 状态state，描述诸如Shift、Ctrl和Alt键之类的键修饰符的按下状态。 Meta State是一个整数，其中设置为1的每个位代表一个按下的meta键， 例如：META_SHIFT_ON = 1META_ALT_ON = 2`metastate = 1->按下Shift metastate = 2->按下Alt按下 metastate = 3-> 按下Shift + Alt组合键-_keycode--要发送到device_metastate的键码--元键的状态 |
| Pull File | path, decode=False | 获取path指定文件的并返回其内容，仅支持Android。 path - 设备上的文件路径， decode - True/False，返回前是转为base64编码(默认为False) |
| Pull Folder | path, decode=False | 获取path指定目录，返回文件夹的zip压缩包，仅支持Android。 path - 设备上文件夹路径 decode - True/False 返回钱是否编码为base64,默认为False |
| Push File | path, data, encode=False | 上传出局到path指定文件,仅支持Android。 path - 设备的文件路径 data - 需要写人文件的数据 encode - True/False 返回前是转为base64编码(默认为False) |
| Quit Application | 退出应用但不关闭Appium会话。该关键字可以用于在用例中或用例间关闭应用。详细解释可参考Launch Application。 AppiumLibrary 1.4新功能 |
|
| Register Keyword To Run On Failure | keyword | 设置AppiumLibrary关键字执行时要执行的关键字 keyword_name 指定AppiumLibary关键字执行失败是要执行的关键字(可以来自任意库) 不支持带参数的关键字 使用关键字"Nothing"禁用此功能 初始化关键字在importing中,默认使用关键字Capture Page Screenshot 失败时截图非常有用但是注意会拖慢运行速度 该关键字返回之前注册的关键字名称,将来可以用于存储原始值 示例： # 失败时运行Log Source `Register Keyword To Run On Failure |
| Remove Application | application_id | 例如:Remove Application com.netease.qa.orangedemo |
| Reset Application | 重置应用。在Appium会话内重置打开的应用。 | |
| Scroll | start_locator, end_locator | 从一个元素滚动到另一个元素。任意元素的关键属性为id及name..。元素定位详情，可以参考介绍 |
| Scroll Down | locator | 向下滚动到元素 |
| Scroll Up | locator | 向上滚动到元素 |
| Set Appium Timeout | seconds | 设置等待关键字的超时间,单位为秒 这些等待关键字包括 Wait ...关键字使用timeout作为参数 所有timeout参数为可选参数 该关键字设置的全局超时时间对所有等待操作有效 先前的超时值由此关键字返回，可用于稍后将旧值设置回原值。 默认超时时间为5秒，但是可以再importing中修改 示例： `${orig timeout}= |
| Set Location | latitude, longitude, altitude=10 | 设置经纬度坐标 latitute 经度 longitude 维度 altitude=10 高度[可选参数],仅支持Android。 AppiumLibrary 1.5新功能给 |
| Set Network Connection Status | connectionStatus | 设置设备网络状态,仅支持Android。 可用值: 0 (None) 1 (Airplane Mode) 2(Wifi only) 4 (Data only) 6 (All network on) |
| Shake | 摇动设备 | |
| Start Activity | appPackage, appActivity, **opts | 在测试中启动任意Activity页面. 如果页面属于另一个App,则启动该App并打开指定页面，仅支持Android。 appPackage - 页面所属包名 appActivity - 启动页面名称 appWaitPackage - 启动应用后开启自动化(可选)). appWaitActivity -启动页面后开启自动化(可选) intentAction - 要启动的(可选). intentCategory - 要启动的Intent分类(可选).intentFlags - 启动intent发送的Flags(可选). optionalIntentArguments - 启动Intent可选参数(可选). dontStopAppOnReset - 不关闭App重置App(可选) |
| Start Screen Recording | timeLimit=180s, **options | 为当前应用启动异步屏幕录制.timeLimit参数用于设置录制的实际时间, iOS和Android默认录制时间为180秒即3分钟Android最长录制3分钟,iOS最长录制10分钟 Start Screen Recording和Stop Screen Recording搭配使用. 详情参考 Stop Screen Recording 示例： `Start Screen Recording |
| Stop Screen Recording | filename=None, **options | 收集从开始屏幕录制时的输出生成媒体文件,然后嵌入到log.html中(仅Andriod)需要启动和终止一个屏幕录制会话 详情参考Start Screen Recording 例如： `Start Screen Recording |
| Swipe | start_x, start_y, offset_x, offset_y, duration=1000 | 从一个点滑动到另一个点, 可选参数滑动间隔时间duration 参数： start_x - 起始点x坐标 start_y - 起始点y坐标 offset_x - 距离起始点x坐标偏移值 offset_y - 距离起始点y坐标偏移值 duration - (可选)滑动持续时间,单位毫秒. 使用方式：`Swipe |
| Swipe By Percent | start_x, start_y, end_x, end_y, duration=1000 | 从屏幕的一个百分比滑动到另一个百分比, 可选参数滑动间隔时间duration Normal swipe fails to scale for different screen resolutions, this can be avoided using percent. 参数： start_x - 起始点x屏幕百分比 start_y - 起始点y屏幕百分比 end_x - 距离起始点x距离屏幕百分比 end_y - 距离起始点y距离屏幕百分比 duration - (可选)滑动持续时间,单位毫秒 示例: `Swipe By Percent |
| Switch Application | index_or_alias | 通过index或alias别名切换应用。 index_or_alias 可以使用应用索引(整数)或别名(字符串) 应用索引来自Open Application的返回值 该关键字返回当前活动的应用索引, 可用稍后切换使用 示例： `${appium1}= |
| Switch To Context | context_name | 切换到指定上下文 |
| Tap | locator, x_offset=None, y_offset=None, count=1 | Tap element identified by locator.参数： x_offset - (可选)点击的x坐标,从屏幕左上角到元素的值.y_offset - (可选)y坐标如果设置了x坐标,则必须设置y坐标,反之亦然 count - 用于设置点击次数 |
| Text Should Be Visible | text, exact_match=False, loglevel=INFO | 验证指定元素可见 AppiumLibrary 1.4新功能 |
| Toggle Touch Id Enrollment | 在iOS Simulator上切换Touch ID的注册状态。 AppiumLibrary 1.5新功能 |
|
| Touch Id | match=True | 在iOS Simulator上模拟Touch ID match (布尔类型)模拟指纹是否有效(默认为true) AppiumLibrary 1.5新功能 |
| Wait Activity | activity, timeout, interval=1 | 等待活动：阻塞直到目标活动出现或超时，仅支持Android。 activity - target activity timeout - 最大等待时间,单位为秒 interval - sleep interval between retries, in seconds |
| Wait Until Element Is Visible | locator, timeout=None, error=None | 等待locator指定元素可见,如果在元素可见之前达到超时时间timeout则视为失败 timeout参数详细信息及默认值可参考 介绍 error用于覆盖默认的出错信息。 请参见： Wait Until Page Contains Wait Until Page Contains Element Wait For Condition 及BuiltIn关键字Wait Until Keyword Succeeds |
| Wait Until Page Contains | text, timeout=None, error=None | Waits until text appears on current page.Fails if timeout expires before the text appears. timeout参数详细信息及默认值可参考 介绍。 error用于覆盖默认的出错信息。 请参见： Wait Until Page Does Not Contain Wait Until Page Contains Element Wait Until Page Does Not Contain Element 及BuiltIn关键字Wait Until Keyword Succeeds. |
| Wait Until Page Contains Element | locator, timeout=None, error=None | 等待locator指定元素出现在当前页面上,如果超过timeout指定时间,则视为失败 timeout参数详细信息及默认值可参考 介绍。 error用于覆盖默认的出错信息。 请参见： Wait Until Page Contains Wait Until Page Does Not Contain Wait Until Page Does Not Contain Element 及BuiltIn关键字Wait Until Keyword Succeeds |
| [Wait Until Page Does Not Contain | text, timeout=None, error=None | Waits until text disappears from current page.Fails if timeout expires before the text disappears. timeout参数详细信息及默认值可参考 介绍。 error用于覆盖默认的出错信息。 请参见： Wait Until Page Contains, Wait Until Page Contains Element Wait Until Page Does Not Contain Element 及BuiltIn 关键字Wait Until Keyword Succeeds |
| Wait Until Page Does Not Contain Element | locator, timeout=None, error=None | 在当前页面上等待locator指定元素出现,如果超过timeout元素未出现则视为失败 timeout参数详细信息及默认值可参考 介绍。 error用于覆盖默认的出错信息。 请参见： Wait Until Page Contains Wait Until Page Does Not Contain Wait Until Page Contains Element 及BuiltIn关键字Wait Until Keyword Succeeds |
| Xpath Should Match X Times | xpath, count, error=None, loglevel=INFO | 验证页面是否包含由给定xpath定位的给定元素数量。在xpath表达式中不可以使用xpath=前缀 正确示例: `Xpath Should Match X Times |
| Zoom | locator, percent=200%, steps=1 | 在元素出放大指定倍数 |
共94个关键字。
