Android自动化测试AppiumLibrary库关键字

AppiumLibrary

Library version:	1.5.0.3
Library scope:	global
Named arguments:	supported

Introduction

AppiumLibrary is a Mobile App testing library for Robot Framework.

Locating or specifying elements

All keywords in AppiumLibrary that need to find an element on the page take an argument, either a locator or a webelement. locator is a string that describes how to locate an element using a syntax specifying different location strategies. webelement is a variable that holds a WebElement instance, which is a representation of the element.

Using locators

By default, when a locator is provided, it is matched against the key attributes of the particular element type. For iOS and Android, key attribute is id for all elements and locating elements is easy using just the id. For example:

Click Element    id=my_element

New in AppiumLibrary 1.4, id and xpath are not required to be specified, however xpath should start with // else just use xpath locator as explained below.

For example:

Click Element    my_element
Wait Until Page Contains Element    //*[@type="android.widget.EditText"]

Appium additionally supports some of the Mobile JSON Wire Protocol locator strategies. It is also possible to specify the approach AppiumLibrary should take to find an element by specifying a lookup strategy with a locator prefix. Supported strategies are:

Strategy	Example	Description	Note
identifier	Click Element \| identifier=my_element	Matches by @id attribute
id	Click Element \| id=my_element	Matches by @resource-id attribute
accessibility_id	Click Element \| accessibility_id=button3	Accessibility options utilize.
xpath	Click Element \| xpath=//UIATableView/UIATableCell/UIAButton	Matches with arbitrary XPath
class	Click Element \| class=UIAPickerWheel	Matches by class
android	Click Element \| android=UiSelector().description('Apps')	Matches by Android UI Automator
ios	Click Element \| ios=.buttons().withName('Apps')	Matches by iOS UI Automation
nsp	Click Element \| nsp=name=="login"	Matches by iOSNsPredicate	Check PR: #196
css	Click Element \| css=.green_button	Matches by css in webview
name	Click Element \| name=my_element	Matches by @name attribute	Only valid for Selendroid

Using webelements

Starting with version 1.4 of the AppiumLibrary, one can pass an argument that contains a WebElement instead of a string locator. To get a WebElement, use the new Get WebElements or Get WebElement keyword.

For example:

@{elements}    Get Webelements    class="UIAButton"
Click Element    @{elements}[2]

Importing

Arguments Documentation

timeout=5, run_on_failure=Capture Page Screenshot

AppiumLibrary can be imported with optional arguments.

timeout is the default timeout used to wait for all waiting actions. It can be later set with Set Appium Timeout.

run_on_failure specifies the name of a keyword (from any available libraries) to execute when a AppiumLibrary keyword fails.

By default Capture Page Screenshot will be used to take a screenshot of the current page. Using the value No Operation will disable this feature altogether. See Register Keyword To Run On Failure keyword for more information about this functionality.

Examples:

Library	AppiumLibrary	10	# Sets default timeout to 10 seconds
Library	AppiumLibrary	timeout=10	run_on_failure=No Operation	# Sets default timeout to 10 seconds and does nothing on failure

Shortcuts

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 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 · 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 · Swipe · Swipe By Direction · 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

Keywords

Keyword Arguments Documentation

Background App

seconds=5

Puts the application in the background on the device for a certain duration.

Capture Page Screenshot

filename=None

Takes a screenshot of the current page and embeds it into the log.

filename argument specifies the name of the file to write the screenshot into. If no filename is given, the screenshot is saved into file appium-screenshot-<counter>.png under the directory where the Robot Framework log file is written into. The filename is also considered relative to the same directory, if it is not given in absolute format.

css can be used to modify how the screenshot is taken. By default the bakground color is changed to avoid possible problems with background leaking when the page layout is somehow broken.

Clear Text

locator

Clears the text field identified by locator.

See introduction for details about locating elements.

Click A Point

x=0, y=0, duration=100

Click on a point

Click Button

index_or_name

Click button

Click Element

locator

Click element identified by locator.

Key attributes for arbitrary elements are index and name. See introduction for details about locating elements.

Click Element At Coordinates

coordinate_X, coordinate_Y

click element at a certain coordinate

Click Text

text, exact_match=False

Click text identified by text.

By default tries to click first text involves given text, if you would like to click exactly matching text, then set exact_match to True.

If there are multiple use of text and you do not want first one, use locator with Get Web Elements instead.

Close All Applications

Closes all open applications.

This keyword is meant to be used in test or suite teardown to make sure all the applications are closed before the test execution finishes.

After this keyword, the application indices returned by Open Application are reset and start from 1.

Close Application

Closes the current application and also close webdriver session.

Element Attribute Should Match

locator, attr_name, match_pattern, regexp=False

Verify that an attribute of an element matches the expected criteria.

The element is identified by locator. See introduction for details about locating elements. If more than one element matches, the first element is selected.

The attr_name is the name of the attribute within the selected element.

The match_pattern is used for the matching, if the match_pattern is

boolean or 'True'/'true'/'False'/'false' String then a boolean match is applied
any other string is cause a string match

The regexp defines whether the string match is done using regular expressions (i.e. BuiltIn Library's Should Match Regexp or string pattern match (i.e. BuiltIn Library's Should Match)

Examples:

Element Attribute Should Match	xpath = //*[contains(@text,'foo')]	text	*foobar
Element Attribute Should Match	xpath = //*[contains(@text,'foo')]	text	f.*ar	regexp = True
Element Attribute Should Match	xpath = //*[contains(@text,'foo')]	enabled	True

1. is a string pattern match i.e. the 'text' attribute should end with the string 'foobar'
2. is a regular expression match i.e. the regexp 'f.*ar' should be within the 'text' attribute
3. is a boolead match i.e. the 'enabled' attribute should be True

NOTE: On Android the supported attribute names are hard-coded in the AndroidElement Class's getBoolAttribute() and getStringAttribute() methods. Currently supported (appium v1.4.11): contentDescription, text, className, resourceId, enabled, checkable, checked, clickable, focusable, focused, longClickable, scrollable, selected, displayed

NOTE: Some attributes can be evaluated in two different ways e.g. these evaluate the same thing:

Element Attribute Should Match	xpath = //*[contains(@text,'example text')]	name	txt_field_name
Element Name Should Be	xpath = //*[contains(@text,'example text')]	txt_field_name

Element Name Should Be locator, expected

Element Should Be Disabled

locator, loglevel=INFO

Verifies that element identified with locator is disabled.

Key attributes for arbitrary elements are id and name. See introduction for details about locating elements.

Element Should Be Enabled

locator, loglevel=INFO

Verifies that element identified with locator is enabled.

Key attributes for arbitrary elements are id and name. See introduction for details about locating elements.

Element Should Be Visible

locator, loglevel=INFO

Verifies that element identified with locator is visible.

Key attributes for arbitrary elements are id and name. See introduction for details about locating elements.

New in AppiumLibrary 1.4.5

Element Should Contain Text

locator, expected, message=

Verifies element identified by locator contains text expected.

If you wish to assert an exact (not a substring) match on the text of the element, use Element Text Should Be.

Key attributes for arbitrary elements are id and xpath. message can be used to override the default error message.

New in AppiumLibrary 1.4.

Element Should Not Contain Text

locator, expected, message=

Verifies element identified by locator does not contain text expected.

message can be used to override the default error message. See Element Should Contain Text for more details.

Element Text Should Be

locator, expected, message=

Verifies element identified by locator exactly contains text expected.

In contrast to Element Should Contain Text, this keyword does not try a substring match but an exact match on the element identified by locator.

message can be used to override the default error message.

New in AppiumLibrary 1.4.

Element Value Should Be locator, expected

Execute Async Script

script

Inject a snippet of Async-JavaScript into the page for execution in the context of the currently selected frame (Web context only).

The executed script is assumed to be asynchronous and must signal that is done by invoking the provided callback, which is always provided as the final argument to the function.

The value to this callback will be returned to the client.

New in AppiumLibrary 1.5

Execute Script

script

Inject a snippet of JavaScript into the page for execution in the context of the currently selected frame (Web context only).

The executed script is assumed to be synchronous and the result of evaluating the script is returned to the client.

New in AppiumLibrary 1.5

Get Activity

Retrieves the current activity on the device.

Android only.

Get Appium SessionId

Returns the current session ID as a reference

Get Appium Timeout

Gets the timeout in seconds that is used by various keywords.

See Set Appium Timeout for an explanation.

Get Capability

capability_name

Return the desired capability value by desired capability name

Get Contexts

Get available contexts.

Get Current Context

Get current context.

Get Element Attribute

locator, attribute

Get element attribute using given attribute: name, value,...

Examples:

Get Element Attribute	locator	name
Get Element Attribute	locator	value

Get Element Location

locator

Get element location

Key attributes for arbitrary elements are id and name. See introduction for details about locating elements.

Get Element Size

locator

Get element size

Key attributes for arbitrary elements are id and name. See introduction for details about locating elements.

Get Matching Xpath Count

xpath

Returns number of elements matching xpath

One should not use the xpath= prefix for 'xpath'. XPath is assumed.

Correct:
${count}	Get Matching Xpath Count	//android.view.View[@text='Test']
Incorrect:
${count}	Get Matching Xpath Count	xpath=//android.view.View[@text='Test']

If you wish to assert the number of matching elements, use Xpath Should Match X Times.

New in AppiumLibrary 1.4.

Get Network Connection Status

Returns an integer bitmask specifying the network connection type.

Android only.

See set network connection status for more details.

Get Source

Returns the entire source of the current page.

Get Text

locator

Get element text (for hybrid and mobile browser use xpath locator, others might cause problem)

Example:

${text}

Get Text

//*[contains(@text,'foo')]

New in AppiumLibrary 1.4.

Get Webelement

locator

Returns the first WebElement object matching locator.

Example:

${element}	Get Webelement	id=my_element
Click Element	${element}

New in AppiumLibrary 1.4.

Get Webelements

locator

Returns list of WebElement objects matching locator.

Example:

@{elements}	Get Webelements	id=my_element
Click Element	@{elements}[2]

This keyword was changed in AppiumLibrary 1.4 in following ways:

Name is changed from Get Elements to current one.
Deprecated argument fail_on_error, use Run Keyword and Ignore Error if necessary.

New in AppiumLibrary 1.4.

Get Window Height

Get current device height.

Example:

${width}	Get Window Height
${height}	Get Window Height
Click A Point	${width	${height}

New in AppiumLibrary 1.4.5

Get Window Width

Get current device width.

Example:

${width}	Get Window Height
${height}	Get Window Height
Click A Point	${width	${height}

New in AppiumLibrary 1.4.5

Go Back

Goes one step backward in the browser history.

Go To Url

url

Opens URL in default web browser.

Example:

Open Application	http://localhost:4755/wd/hub	platformName=iOS	platformVersion=7.0	deviceName='iPhone Simulator'	browserName=Safari
Go To URL	http://m.webapp.com

Hide Keyboard

key_name=None

Hides the software keyboard on the device. (optional) In iOS, use key_name to press a particular key, ex. Done. In Android, no parameters are used.

Input Password

locator, text

Types the given password into text field identified by locator.

Difference between this keyword and Input Text is that this keyword does not log the given password. See introduction for details about locating elements.

Input Text

locator, text

Types the given text into text field identified by locator.

See introduction for details about locating elements.

Input Value

locator, text

Sets the given value into text field identified by locator. This is an IOS only keyword, input value makes use of set_value

See introduction for details about locating elements.

Install App

app_path, app_package

Install App via Appium

Android only.

app_path - path to app
app_package - package of install app to verify

Landscape

Set the device orientation to LANDSCAPE

Launch Application

Launch application. Application can be launched while Appium session running. This keyword can be used to launch application during test case or between test cases.

This keyword works while Open Application has a test running. This is good practice to Launch Application and Quit Application between test cases. As Suite Setup is Open Application, Test Setup can be used to Launch Application

Example (syntax is just a representation, refer to RF Guide for usage of Setup/Teardown):

[Setup Suite]
	Open Application	http://localhost:4723/wd/hub	platformName=Android	deviceName=192.168.56.101:5555	app=${CURDIR}/demoapp/OrangeDemoApp.apk
[Test Setup]
	Launch Application
		<<<test execution>>>
		<<<test execution>>>
[Test Teardown]
	Quit Application
[Suite Teardown]
	Close Application

See Quit Application for quiting application but keeping Appium sesion running.

New in AppiumLibrary 1.4.6

Lock

seconds=5

Lock the device for a certain period of time. iOS only.

Log Source

loglevel=INFO

Logs and returns the entire html source of the current page or frame.

The loglevel argument defines the used log level. Valid log levels are WARN, INFO (default), DEBUG, TRACE and NONE (no logging).

Long Press

locator, duration=1000

Long press the element with optional duration

Long Press Keycode

keycode, metastate=None

Sends a long press of keycode to the device.

Android only.

See press keycode for more details.

Open Application

remote_url, alias=None, **kwargs

Opens a new application to given Appium server. Capabilities of appium server, Android and iOS, Please check https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/server-args.md

Option	Man.	Description
remote_url	Yes	Appium server url
alias	no	alias

Examples:

Open Application	http://localhost:4723/wd/hub	alias=Myapp1	platformName=iOS	platformVersion=7.0	deviceName='iPhone Simulator'	app=your.app
Open Application	http://localhost:4723/wd/hub	platformName=Android	platformVersion=4.2.2	deviceName=192.168.56.101:5555	app=${CURDIR}/demoapp/OrangeDemoApp.apk	appPackage=com.netease.qa.orangedemo	appActivity=MainActivity

Page Should Contain Element

locator, loglevel=INFO

Verifies that current page contains locator element.

If this keyword fails, it automatically logs the page source using the log level specified with the optional loglevel argument. Giving NONE as level disables logging.

Page Should Contain Text

text, loglevel=INFO

Verifies that current page contains text.

If this keyword fails, it automatically logs the page source using the log level specified with the optional loglevel argument. Giving NONE as level disables logging.

Page Should Not Contain Element

locator, loglevel=INFO

Verifies that current page not contains locator element.

If this keyword fails, it automatically logs the page source using the log level specified with the optional loglevel argument. Giving NONE as level disables logging.

Page Should Not Contain Text

text, loglevel=INFO

Verifies that current page not contains text.

If this keyword fails, it automatically logs the page source using the log level specified with the optional loglevel argument. Giving NONE as level disables logging.

Pinch

locator, percent=200%, steps=1

Pinch in on an element a certain amount.

Portrait

Set the device orientation to PORTRAIT

Press Keycode

keycode, metastate=None

Sends a press of keycode to the device.

Android only.

Possible keycodes & meta states can be found in http://developer.android.com/reference/android/view/KeyEvent.html

Meta state describe the pressed state of key modifiers such as Shift, Ctrl & Alt keys. The Meta State is an integer in which each bit set to 1 represents a pressed meta key.

For example

META_SHIFT_ON = 1
META_ALT_ON = 2

metastate=1 --> Shift is pressed
metastate=2 --> Alt is pressed
metastate=3 --> Shift+Alt is pressed

_keycode- - the keycode to be sent to the device
_metastate- - status of the meta keys

Pull File

path, decode=False

Retrieves the file at path and return it's content.

Android only.

path - the path to the file on the device
decode - True/False decode the data (base64) before returning it (default=False)

Pull Folder

path, decode=False

Retrieves a folder at path. Returns the folder's contents zipped.

Android only.

path - the path to the folder on the device
decode - True/False decode the data (base64) before returning it (default=False)

Push File

path, data, encode=False

Puts the data in the file specified as path.

Android only.

path - the path on the device
data - data to be written to the file
encode - True/False encode the data as base64 before writing it to the file (default=False)

Quit Application

Quit application. Application can be quit while Appium session is kept alive. This keyword can be used to close application during test case or between test cases.

See Launch Application for an explanation.

New in AppiumLibrary 1.4.6

keyword

Sets the keyword to execute when a AppiumLibrary keyword fails.

keyword_name is the name of a keyword (from any available libraries) that will be executed if a AppiumLibrary keyword fails. It is not possible to use a keyword that requires arguments. Using the value "Nothing" will disable this feature altogether.

The initial keyword to use is set in importing, and the keyword that is used by default is Capture Page Screenshot. Taking a screenshot when something failed is a very useful feature, but notice that it can slow down the execution.

This keyword returns the name of the previously registered failure keyword. It can be used to restore the original value later.

Example:

Register Keyword To Run On Failure	Log Source	# Run Log Source on failure.
${previous kw}=	Register Keyword To Run On Failure	Nothing	# Disables run-on-failure functionality and stores the previous kw name in a variable.
Register Keyword To Run On Failure	${previous kw}	# Restore to the previous keyword.

This run-on-failure functionality only works when running tests on Python/Jython 2.4 or newer and it does not work on IronPython at all.

Remove Application

application_id

Removes the application that is identified with an application id

Example:

Remove Application

com.netease.qa.orangedemo

Reset Application

Reset application. Open Application can be reset while Appium session is kept alive.

Scroll

start_locator, end_locator

Scrolls from one element to another Key attributes for arbitrary elements are id and name. See introduction for details about locating elements.

Scroll Down

locator

Scrolls down to element

Scroll Up

locator

Scrolls up to element

Set Appium Timeout

seconds

Sets the timeout in seconds used by various keywords.

There are several Wait ... keywords that take timeout as an argument. All of these timeout arguments are optional. The timeout used by all of them can be set globally using this keyword.

The previous timeout value is returned by this keyword and can be used to set the old value back later. The default timeout is 5 seconds, but it can be altered in importing.

Example:

${orig timeout} =	Set Appium Timeout	15 seconds
Open page that loads slowly
Set Appium Timeout	${orig timeout}

Set Location

latitude, longitude, altitude=10

Set location

latitute
longitude
altitude = 10 [optional]

Android only. New in AppiumLibrary 1.5

Set Network Connection Status

connectionStatus

Sets the network connection Status.

Android only.

Possible values:

Value	Alias	Data	Wifi	Airplane Mode
0	(None)	0	0	0
1	(Airplane Mode)	0	0	1
2	(Wifi only)	0	1	0
4	(Data only)	1	0	0
6	(All network on)	1	1	0

Shake

Shake the device

Start Activity

appPackage, appActivity, **opts

Opens an arbitrary activity during a test. If the activity belongs to another application, that application is started and the activity is opened.

Android only.

appPackage - The package containing the activity to start.
appActivity - The activity to start.
appWaitPackage - Begin automation after this package starts (optional).
appWaitActivity - Begin automation after this activity starts (optional).
intentAction - Intent to start (opt_ional).
intentCategory - Intent category to start (optional).
intentFlags - Flags to send to the intent (optional).
optionalIntentArguments - Optional arguments to the intent (optional).
stopAppOnReset - Should the app be stopped on reset (optional)?

Swipe

start_x, start_y, offset_x, offset_y, duration=1000

Swipe from one point to another point, for an optional duration.

Args:

start_x - x-coordinate at which to start
start_y - y-coordinate at which to start
offset_x - x-coordinate distance from start_x at which to stop
offset_y - y-coordinate distance from start_y at which to stop
duration - (optional) time to take the swipe, in ms.

Usage:

Swipe

500

100

1000

NOTE: Android 'Swipe' is not working properly, use offset_x and offset_y as if these are destination points.

Swipe By Direction

direction

swipe by given direction: left, right, down, up.

Swipe By Percent

start_x, start_y, end_x, end_y, duration=1000

Swipe from one percent of the screen to another percent, for an optional duration. Normal swipe fails to scale for different screen resolutions, this can be avoided using percent.

Args:

start_x - x-percent at which to start
start_y - y-percent at which to start
end_x - x-percent distance from start_x at which to stop
end_y - y-percent distance from start_y at which to stop
duration - (optional) time to take the swipe, in ms.

Usage:

Swipe By Percent

# Swipes screen from right to left.

NOTE: This also considers swipe acts different between iOS and Android.

New in AppiumLibrary 1.4.5

Switch Application

index_or_alias

Switches the active application by index or alias.

index_or_alias is either application index (an integer) or alias (a string). Index is got as the return value of Open Application.

This keyword returns the index of the previous active application, which can be used to switch back to that application later.

Example:

${appium1}=	Open Application	http://localhost:4723/wd/hub	alias=MyApp1	platformName=iOS	platformVersion=7.0	deviceName='iPhone Simulator'	app=your.app
${appium2}=	Open Application	http://localhost:4755/wd/hub	alias=MyApp2	platformName=iOS	platformVersion=7.0	deviceName='iPhone Simulator'	app=your.app
Click Element	sendHello	# Executed on appium running at localhost:4755
Switch Application	${appium1}	# Switch using index
Click Element	ackHello	# Executed on appium running at localhost:4723
Switch Application	MyApp2	# Switch using alias
Page Should Contain Text	ackHello Received	# Executed on appium running at localhost:4755

Switch To Context

context_name

Switch to a new context

Tap

locator, x_offset=None, y_offset=None, count=1

Tap element identified by locator.

Args:

x_offset - (optional) x coordinate to tap, relative to the top left corner of the element.
y_offset - (optional) y coordinate. If y is used, x must also be set, and vice versa
count - can be used for multiple times of tap on that element

Text Should Be Visible

text, exact_match=False, loglevel=INFO

Verifies that element identified with text is visible.

New in AppiumLibrary 1.4.5

Toggle Touch Id Enrollment

Toggle Touch ID enrolled state on iOS Simulator

New in AppiumLibrary 1.5

Touch Id

match=True

Simulate Touch ID on iOS Simulator

match (boolean) whether the simulated fingerprint is valid (default true)

New in AppiumLibrary 1.5