AppiumLibrary Skill for Robot Framework

适用于Robot Framework的AppiumLibrary Skill

Quick Reference

快速参考

AppiumLibrary enables mobile app testing on iOS and Android using Appium automation.

AppiumLibrary 借助Appium自动化技术，支持在iOS和Android平台上进行移动应用测试。

Installation

安装

bash

undefined

bash

undefined

Install the library

pip install robotframework-appiumlibrary

Install Appium server (requires Node.js)

npm install -g appium

Install platform drivers

appium driver install uiautomator2 # Android appium driver install xcuitest # iOS

undefined

appium driver install uiautomator2 # Android appium driver install xcuitest # iOS

undefined

Appium Server

Appium 服务器

Appium server must be running before tests:

bash

appium                    # Start with defaults
appium server             # Alternative
appium --port 4724        # Custom port

Default URL:

http://127.0.0.1:4723

在运行测试前必须启动Appium服务器：

bash

appium                    # Start with defaults
appium server             # Alternative
appium --port 4724        # Custom port

默认URL：

http://127.0.0.1:4723

Library Import

库导入

robotframework

*** Settings ***
Library    AppiumLibrary

robotframework

*** Settings ***
Library    AppiumLibrary

Android Quick Start

Android 快速入门

Open Android App

打开Android应用

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=Android
...    platformVersion=13
...    deviceName=emulator-5554
...    automationName=UiAutomator2
...    app=${CURDIR}/app.apk

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=Android
...    platformVersion=13
...    deviceName=emulator-5554
...    automationName=UiAutomator2
...    app=${CURDIR}/app.apk

Android Locators (Priority Order)

Android 定位器（优先级顺序）

robotframework

undefined

robotframework

undefined

1. accessibility_id (RECOMMENDED - stable)

Click Element accessibility_id=login_button

2. id (resource-id)

Click Element id=com.example:id/login_button Click Element id=login_button # Short form if unique

3. xpath

Click Element xpath=//android.widget.Button[@text='Login']

4. android UIAutomator2 selector

Click Element android=new UiSelector().text("Login")

5. class name

Click Element class=android.widget.Button

undefined

Click Element class=android.widget.Button

undefined

iOS Quick Start

iOS 快速入门

Open iOS App

打开iOS应用

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=iOS
...    platformVersion=17.0
...    deviceName=iPhone 15
...    automationName=XCUITest
...    app=${CURDIR}/MyApp.app
...    udid=auto                                    # For real devices

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=iOS
...    platformVersion=17.0
...    deviceName=iPhone 15
...    automationName=XCUITest
...    app=${CURDIR}/MyApp.app
...    udid=auto                                    # For real devices

iOS Locators (Priority Order)

iOS 定位器（优先级顺序）

robotframework

undefined

robotframework

undefined

1. accessibility_id (RECOMMENDED - stable)

Click Element accessibility_id=loginButton

2. name

Click Element name=Login

3. ios predicate string

Click Element ios=type == 'XCUIElementTypeButton' AND name == 'Login'

4. ios class chain (fast) - NOTE: use chain= prefix for class chains

Click Element chain=**/XCUIElementTypeButton[

name == 'Login'

]

Click Element chain=**/XCUIElementTypeButton[

name == 'Login'

]

5. xpath

Click Element xpath=//XCUIElementTypeButton[@name='Login']

6. class name

Click Element class=XCUIElementTypeButton

undefined

Click Element class=XCUIElementTypeButton

undefined

Essential Keywords

核心关键字

Element Interaction

元素交互

robotframework

Click Element           locator
Click Text              visible_text
Input Text              locator    text_to_enter
Clear Text              locator
Tap                     locator    duration=0:00:01    # Long press (replaces removed Long Press)

robotframework

Click Element           locator
Click Text              visible_text
Input Text              locator    text_to_enter
Clear Text              locator
Tap                     locator    duration=0:00:01    # Long press (replaces removed Long Press)

Getting Element Content

获取元素内容

robotframework

${text}=    Get Text              locator
${attr}=    Get Element Attribute    locator    attribute_name
${count}=   Get Matching Xpath Count    //android.widget.Button

robotframework

${text}=    Get Text              locator
${attr}=    Get Element Attribute    locator    attribute_name
${count}=   Get Matching Xpath Count    //android.widget.Button

Waits

等待操作

robotframework

Wait Until Element Is Visible       locator    timeout=10s
Wait Until Page Contains            text       timeout=10s
Wait Until Page Contains Element    locator    timeout=10s

robotframework

Wait Until Element Is Visible       locator    timeout=10s
Wait Until Page Contains            text       timeout=10s
Wait Until Page Contains Element    locator    timeout=10s

Verification

验证操作

robotframework

Element Should Be Visible       locator
Element Should Be Enabled       locator
Page Should Contain Text        expected_text
Page Should Contain Element     locator
Element Text Should Be          locator    expected_text

robotframework

Element Should Be Visible       locator
Element Should Be Enabled       locator
Page Should Contain Text        expected_text
Page Should Contain Element     locator
Element Text Should Be          locator    expected_text

Screenshots

截图

robotframework

Capture Page Screenshot    filename.png
Capture Page Screenshot    ${OUTPUT_DIR}/screenshots/screen.png

robotframework

Capture Page Screenshot    filename.png
Capture Page Screenshot    ${OUTPUT_DIR}/screenshots/screen.png

Get Page Source (View Hierarchy)

获取页面源码（视图层级）

Useful for finding locators and debugging:

robotframework

${source}=    Get Source
Log    ${source}

该功能有助于查找定位器和调试：

robotframework

${source}=    Get Source
Log    ${source}

Basic Gestures

基础手势操作

robotframework

undefined

robotframework

undefined

Scroll (locator is the element to scroll to/within)

Scroll Down locator Scroll Up locator

Swipe (start_x, start_y, end_x, end_y, duration as timedelta)

Swipe start_x=500 start_y=1500 end_x=500 end_y=500 duration=0:00:01 # Swipe up

Long press (use Tap with duration; Long Press was removed in v3.2.0)

Tap locator duration=0:00:02

Tap at coordinates

Tap With Positions 500 800

undefined

Tap With Positions 500 800

undefined

Android Scroll to Element (UIAutomator2)

Android 滚动到元素（UIAutomator2）

robotframework

undefined

robotframework

undefined

Automatically scrolls to find element!

Click Element android=new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text("Settings"))

undefined

Click Element android=new UiScrollable(new UiSelector().scrollable(true)).scrollIntoView(new UiSelector().text("Settings"))

undefined

Context Switching (Hybrid Apps)

上下文切换（混合应用）

robotframework

undefined

robotframework

undefined

Check current context

${context}= Get Current Context Log Current: ${context}

List all contexts

@{contexts}= Get Contexts Log Many @{contexts}

Switch to webview

Switch To Context WEBVIEW_com.example.app

Switch back to native

Switch To Context NATIVE_APP

undefined

Switch To Context NATIVE_APP

undefined

Mobile Browser Testing

移动浏览器测试

Android Chrome

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=Android
...    deviceName=emulator-5554
...    automationName=UiAutomator2
...    browserName=Chrome

Go To Url    https://example.com
Input Text    id=username    admin
Click Element    css=button[type='submit']

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=Android
...    deviceName=emulator-5554
...    automationName=UiAutomator2
...    browserName=Chrome

Go To Url    https://example.com
Input Text    id=username    admin
Click Element    css=button[type='submit']

iOS Safari

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=iOS
...    deviceName=iPhone 15
...    automationName=XCUITest
...    browserName=Safari

Go To Url    https://example.com

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=iOS
...    deviceName=iPhone 15
...    automationName=XCUITest
...    browserName=Safari

Go To Url    https://example.com

Session Management

会话管理

robotframework

undefined

robotframework

undefined

Close app and end session

Close Application

Background/foreground

Background Application 5 # Background for 5 seconds

NOTE: Quit Application was removed in v3.0.0 - use Close Application instead

NOTE: Reset Application was removed in v3.2.0 - use Close Application + Open Application instead

undefined

undefined

W3C Capabilities Format (Appium 2.x)

W3C 能力配置格式（Appium 2.x）

Appium 2.x uses W3C capabilities with the

appium:

vendor prefix for non-standard capabilities:

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=Android
...    appium:automationName=UiAutomator2
...    appium:app=/path/to/app.apk
...    appium:deviceName=emulator-5554
...    appium:autoGrantPermissions=true

Only

platformName

is standard W3C. All other Appium-specific capabilities need the

appium:

prefix. AppiumLibrary will typically add the prefix automatically, but explicitly using it is recommended for clarity.

Appium 2.x 使用带

appium:

厂商前缀的W3C能力配置来标识非标准能力：

robotframework

Open Application    http://127.0.0.1:4723
...    platformName=Android
...    appium:automationName=UiAutomator2
...    appium:app=/path/to/app.apk
...    appium:deviceName=emulator-5554
...    appium:autoGrantPermissions=true

只有

platformName

是标准W3C能力。所有其他Appium专属能力都需要添加

appium:

前缀。 AppiumLibrary通常会自动添加该前缀，但为了清晰起见，建议显式使用。

Cloud Testing (BrowserStack / Sauce Labs)

云测试（BrowserStack / Sauce Labs）

BrowserStack

robotframework

Open Application    http://hub-cloud.browserstack.com/wd/hub
...    platformName=Android
...    appium:deviceName=Google Pixel 7
...    appium:platformVersion=13.0
...    appium:app=bs://your_app_hash
...    bstack:options={"userName": "${BS_USERNAME}", "accessKey": "${BS_ACCESS_KEY}"}

robotframework

Open Application    http://hub-cloud.browserstack.com/wd/hub
...    platformName=Android
...    appium:deviceName=Google Pixel 7
...    appium:platformVersion=13.0
...    appium:app=bs://your_app_hash
...    bstack:options={"userName": "${BS_USERNAME}", "accessKey": "${BS_ACCESS_KEY}"}

Sauce Labs

robotframework

Open Application    https://ondemand.us-west-1.saucelabs.com:443/wd/hub
...    platformName=iOS
...    appium:deviceName=iPhone 14
...    appium:platformVersion=16
...    appium:app=storage:filename=MyApp.ipa
...    sauce:options={"username": "${SAUCE_USERNAME}", "accessKey": "${SAUCE_ACCESS_KEY}"}

robotframework

Open Application    https://ondemand.us-west-1.saucelabs.com:443/wd/hub
...    platformName=iOS
...    appium:deviceName=iPhone 14
...    appium:platformVersion=16
...    appium:app=storage:filename=MyApp.ipa
...    sauce:options={"username": "${SAUCE_USERNAME}", "accessKey": "${SAUCE_ACCESS_KEY}"}

Removed Keywords and Alternatives

已移除的关键字及替代方案

Several keywords were removed in AppiumLibrary v3.x:

Removed Keyword	Version Removed	Alternative
`Long Press`	v3.2.0	`Tap locator duration=0:00:01`
`Click A Point`	v3.0.0	`Tap With Positions x y`
`Zoom`	v3.2.0	Use W3C Actions via Execute Script
`Pinch`	v3.0.0	Use W3C Actions via Execute Script
`Reset Application`	v3.2.0	`Close Application` then `Open Application`
`Quit Application`	v3.0.0	`Close Application`
`Background App`	v3.0.0	`Background Application`
`Get Window Size`	N/A	`Get Window Width` / `Get Window Height`

AppiumLibrary v3.x版本中移除了多个关键字：

已移除关键字	移除版本	替代方案
`Long Press`	v3.2.0	`Tap locator duration=0:00:01`
`Click A Point`	v3.0.0	`Tap With Positions x y`
`Zoom`	v3.2.0	通过Execute Script使用W3C Actions
`Pinch`	v3.0.0	通过Execute Script使用W3C Actions
`Reset Application`	v3.2.0	先执行 `Close Application` 再执行 `Open Application`
`Quit Application`	v3.0.0	`Close Application`
`Background App`	v3.0.0	`Background Application`
`Get Window Size`	N/A	`Get Window Width` / `Get Window Height`

W3C Actions for Zoom/Pinch

用于缩放/捏合的W3C Actions

Zoom and Pinch gestures require W3C Actions in AppiumLibrary v3.x. These can be performed using multi-touch sequences via the Appium driver directly if needed:

robotframework

undefined

在AppiumLibrary v3.x中，缩放和捏合手势需要使用W3C Actions。如果需要，可通过Appium驱动直接执行多点触控序列：

robotframework

undefined

Example: Use Execute Script to perform pinch/zoom via driver

Execute Script mobile: pinchOpen {"elementId": "${element_id}", "percent": 0.75}

undefined

Execute Script mobile: pinchOpen {"elementId": "${element_id}", "percent": 0.75}

undefined

When to Load Additional References

何时加载更多参考文档

Reference files for deeper guidance (planned):

Need	Reference File
Android locator strategies	`references/locators-android.md`
iOS locator strategies	`references/locators-ios.md`
Device capabilities setup	`references/device-capabilities.md`
Gestures and scrolling	`references/gestures-touch.md`
iOS-specific features	`references/ios-specific.md`
Android-specific features	`references/android-specific.md`
Complete keyword list	`references/keywords-reference.md`
Common issues and solutions	`references/troubleshooting.md`

以下是用于深入指导的参考文件（规划中）：

需求	参考文件
Android定位器策略	`references/locators-android.md`
iOS定位器策略	`references/locators-ios.md`
设备能力配置	`references/device-capabilities.md`
手势与滚动操作	`references/gestures-touch.md`
iOS专属功能	`references/ios-specific.md`
Android专属功能	`references/android-specific.md`
完整关键字列表	`references/keywords-reference.md`
常见问题与解决方案	`references/troubleshooting.md`

robotframework-appium-skill

Original

Translation

AppiumLibrary Skill for Robot Framework

适用于Robot Framework的AppiumLibrary Skill

Quick Reference

快速参考

Installation

安装

Install the library

Install the library

Install Appium server (requires Node.js)

Install Appium server (requires Node.js)

Install platform drivers

Install platform drivers

Appium Server

Appium 服务器

Library Import

库导入

Android Quick Start

Android 快速入门

Open Android App

打开Android应用

Android Locators (Priority Order)

Android 定位器（优先级顺序）

1. accessibility_id (RECOMMENDED - stable)

1. accessibility_id (RECOMMENDED - stable)

2. id (resource-id)

2. id (resource-id)

3. xpath

3. xpath

4. android UIAutomator2 selector

4. android UIAutomator2 selector

5. class name

5. class name

iOS Quick Start

iOS 快速入门

Open iOS App

打开iOS应用

iOS Locators (Priority Order)

iOS 定位器（优先级顺序）

1. accessibility_id (RECOMMENDED - stable)

1. accessibility_id (RECOMMENDED - stable)

2. name

2. name

3. ios predicate string

3. ios predicate string

4. ios class chain (fast) - NOTE: use chain= prefix for class chains

4. ios class chain (fast) - NOTE: use chain= prefix for class chains

5. xpath

5. xpath

6. class name

6. class name

Essential Keywords

核心关键字

Element Interaction

元素交互

Getting Element Content

获取元素内容

Waits

等待操作

Verification

验证操作

Screenshots

截图

Get Page Source (View Hierarchy)

获取页面源码（视图层级）

Basic Gestures

基础手势操作

Scroll (locator is the element to scroll to/within)

Scroll (locator is the element to scroll to/within)

Swipe (start_x, start_y, end_x, end_y, duration as timedelta)

Swipe (start_x, start_y, end_x, end_y, duration as timedelta)

Long press (use Tap with duration; Long Press was removed in v3.2.0)

Long press (use Tap with duration; Long Press was removed in v3.2.0)

Tap at coordinates

Tap at coordinates

Android Scroll to Element (UIAutomator2)

Android 滚动到元素（UIAutomator2）

Automatically scrolls to find element!