Appium

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

Arguments

• seconds=5

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

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

Arguments

• 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.

Clears the text field identified by `locator`.

Arguments

• locator

Clears the text field identified by locator.

See introduction for details about locating elements.

Click on a point

Arguments

• x=0
• y=0
• duration=100

Click on a point

Click button

Arguments

• index_or_name

Click button

Click element identified by `locator`.

Arguments

• 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 a certain coordinate

Arguments

• coordinate_X
• coordinate_Y

click element at a certain coordinate

Click text identified by ``text``.

Arguments

• 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.

Closes all open applications.

Arguments

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.

Closes the current application and also close webdriver session.

Arguments

Closes the current application and also close webdriver session.

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

Arguments

• 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:

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:

Arguments

• locator
• expected

Verifies that element identified with locator is disabled.

Arguments

• 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.

Verifies that element identified with locator is enabled.

Arguments

• 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.

Verifies that element identified with locator is visible.

Arguments

• 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

Verifies element identified by ``locator`` contains text ``expected``.

Arguments

• 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.

Verifies element identified by ``locator`` does not contain text ``expected``.

Arguments

• 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.

Verifies element identified by ``locator`` exactly contains text ``expected``.

Arguments

• 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.

Arguments

• locator
• expected

Execute ADB shell commands

Arguments

• command
• *args

Execute ADB shell commands

Android only.

• command - The ABD shell command
• args - Arguments to send to command

Returns the exit code of ADB shell.

Requires server flag --relaxed-security to be set on Appium server.

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

Arguments

• 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

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

Arguments

• 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

Retrieves the current activity on the device.

Arguments

Retrieves the current activity on the device.

Android only.

Returns the current session ID as a reference

Arguments

Returns the current session ID as a reference

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

Arguments

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

See Set Appium Timeout for an explanation.

Return the desired capability value by desired capability name

Arguments

• capability_name

Return the desired capability value by desired capability name

Get available contexts.

Arguments

Get available contexts.

Get current context.

Arguments

Get current context.

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

Arguments

• locator
• attribute

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

Examples:

Get element location

Arguments

• locator

Get element location

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

Get element size

Arguments

• locator

Get element size

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

Returns number of elements matching ``xpath``

Arguments

• xpath

Returns number of elements matching xpath

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

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

New in AppiumLibrary 1.4.

Returns an integer bitmask specifying the network connection type.

Arguments

Returns an integer bitmask specifying the network connection type.

Android only.

See set network connection status for more details.

Returns the entire source of the current page.

Arguments

Returns the entire source of the current page.

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

Arguments

• locator

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

Example:

New in AppiumLibrary 1.4.

Returns the first [http://selenium-python.readthedocs.io/api.html#module-selenium.webdriver.remote.webelement|WebElement] object matching ``locator``.

Arguments

• locator

Returns the first WebElement object matching locator.

Example:

New in AppiumLibrary 1.4.

Returns list of [http://selenium-python.readthedocs.io/api.html#module-selenium.webdriver.remote.webelement|WebElement] objects matching ``locator``.

Arguments

• locator

Returns list of WebElement objects matching locator.

Example:

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 current device height.

Arguments

Get current device height.

Example:

New in AppiumLibrary 1.4.5

Get current device width.

Arguments

Get current device width.

Example:

New in AppiumLibrary 1.4.5

Goes one step backward in the browser history.

Arguments

Goes one step backward in the browser history.

Opens URL in default web browser.

Arguments

• url

Opens URL in default web browser.

Example:

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.

Arguments

• 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.

Types the given password into text field identified by `locator`.

Arguments

• 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.

Types the given `text` into text field identified by `locator`.

Arguments

• locator
• text

Types the given text into text field identified by locator.

See introduction for details about locating elements.

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

Arguments

• 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 via Appium

Arguments

• app_path
• app_package

Install App via Appium

Android only.

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

Return true if Android keyboard is displayed or False if not displayed No parameters are used.

Arguments

Return true if Android keyboard is displayed or False if not displayed No parameters are used.

Set the device orientation to LANDSCAPE

Arguments

Set the device orientation to LANDSCAPE

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.

Arguments

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):

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

New in AppiumLibrary 1.4.6

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

Arguments

• seconds=5

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

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

Arguments

• 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 the element with optional duration

Arguments

• locator
• duration=1000

Long press the element with optional duration

Sends a long press of keycode to the device.

Arguments

• keycode
• metastate=None

Sends a long press of keycode to the device.

Android only.

See press keycode for more details.

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 |

Arguments

• 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

Examples:

Verifies that current page contains `locator` element.

Arguments

• 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.

Verifies that current page contains `text`.

Arguments

• 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.

Verifies that current page not contains `locator` element.

Arguments

• 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.

Verifies that current page not contains `text`.

Arguments

• 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 in on an element a certain amount.

Arguments

• locator
• percent=200%
• steps=1

Pinch in on an element a certain amount.

Set the device orientation to PORTRAIT

Arguments

Set the device orientation to PORTRAIT

Sends a press of keycode to the device.

Arguments

• 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

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

Arguments

• 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)

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

Arguments

• 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)

Puts the data in the file specified as `path`.

Arguments

• 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. 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.

Arguments

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

Sets the keyword to execute when a AppiumLibrary keyword fails.

Arguments

• 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:

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.

Removes the application that is identified with an application id

Arguments

• application_id

Removes the application that is identified with an application id

Example:

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

Arguments

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

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

Arguments

• 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.

Scrolls down to element

Arguments

• locator

Scrolls down to element

Scrolls up to element

Arguments

• locator

Scrolls up to element

Sets the timeout in seconds used by various keywords.

Arguments

• 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:

Set location

Arguments

• latitude
• longitude
• altitude=10

Set location

• latitute
• longitude
• altitude = 10 [optional]

Android only. New in AppiumLibrary 1.5

Sets the network connection Status.

Arguments

• connectionStatus

Sets the network connection Status.

Android only.

Possible values:

Shake the device

Arguments

Shake the device

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

Arguments

• 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).
• dontStopAppOnReset - Should the app be stopped on reset (optional)?

Starts a asynchronous Screen Recording for the current open application.

Arguments

• timeLimit=180s
• **options

Starts a asynchronous Screen Recording for the current open application.

timeLimit sets the actual time limit of the recorded video.

• The default value for both iOS and Android is 180 seconds (3 minutes).
• The maximum value for Android is 3 minutes.
• The maximum value for iOS is 10 minutes.

Start Screen Recording is used hand in hand with Stop Screen Recording. See Stop Screen Recording for more details. Example:

Gathers the output from the previously started screen recording to a media file, then embeds it to the log.html(only on Android).

Arguments

• filename=None
• **options

Gathers the output from the previously started screen recording to a media file, then embeds it to the log.html(only on Android).

Requires an active or exhausted Screen Recording Session. See Start Screen Recording for more details.

Example:

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

Arguments

• 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:

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

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.

Arguments

• 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:

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

New in AppiumLibrary 1.4.5

Switches the active application by index or alias.

Arguments

• 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:

Switch to a new context

Arguments

• context_name

Switch to a new context

Tap element identified by ``locator``.

Arguments

• 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

Verifies that element identified with text is visible.

Arguments

• text
• exact_match=False
• loglevel=INFO

Verifies that element identified with text is visible.

New in AppiumLibrary 1.4.5

Toggle Touch ID enrolled state on iOS Simulator

Arguments

Toggle Touch ID enrolled state on iOS Simulator

New in AppiumLibrary 1.5

Simulate Touch ID on iOS Simulator

Arguments

• match=True

Simulate Touch ID on iOS Simulator

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

New in AppiumLibrary 1.5

Wait for an activity: block until target activity presents or time out.

Arguments

• activity
• timeout
• interval=1

Wait for an activity: block until target activity presents or time out.

Android only.

• activity - target activity
• timeout - max wait time, in seconds
• interval - sleep interval between retries, in seconds

Waits until element specified with `locator` is visible.

Arguments

• locator
• timeout=None
• error=None

Waits until element specified with locator is visible.

Fails if timeout expires before the element is visible. See introduction for more information about timeout and its default value.

error can be used to override the default error message.

See also Wait Until Page Contains, Wait Until Page Contains Element, Wait For Condition and BuiltIn keyword Wait Until Keyword Succeeds.

Waits until `text` appears on current page.

Arguments

• text
• timeout=None
• error=None

Waits until text appears on current page.

Fails if timeout expires before the text appears. See introduction for more information about timeout and its default value.

error can be used to override the default error message.

See also Wait Until Page Does Not Contain, Wait Until Page Contains Element, Wait Until Page Does Not Contain Element and BuiltIn keyword Wait Until Keyword Succeeds.

Waits until element specified with `locator` appears on current page.

Arguments

• locator
• timeout=None
• error=None

Waits until element specified with locator appears on current page.

Fails if timeout expires before the element appears. See introduction for more information about timeout and its default value.

error can be used to override the default error message.

See also Wait Until Page Contains, Wait Until Page Does Not Contain Wait Until Page Does Not Contain Element and BuiltIn keyword Wait Until Keyword Succeeds.

Waits until `text` disappears from current page.

Arguments

• text
• timeout=None
• error=None

Waits until text disappears from current page.

Fails if timeout expires before the text disappears. See introduction for more information about timeout and its default value.

error can be used to override the default error message.

See also Wait Until Page Contains, Wait Until Page Contains Element, Wait Until Page Does Not Contain Element and BuiltIn keyword Wait Until Keyword Succeeds.

Waits until element specified with `locator` disappears from current page.

Arguments

• locator
• timeout=None
• error=None

Waits until element specified with locator disappears from current page.

Fails if timeout expires before the element disappears. See introduction for more information about timeout and its default value.

error can be used to override the default error message.

See also Wait Until Page Contains, Wait Until Page Does Not Contain, Wait Until Page Contains Element and BuiltIn keyword Wait Until Keyword Succeeds.

Verifies that the page contains the given number of elements located by the given ``xpath``.

Arguments

• xpath
• count
• error=None
• loglevel=INFO

Verifies that the page contains the given number of elements located by the given xpath.

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

error can be used to override the default error message.

See Log Source for explanation about loglevel argument.

New in AppiumLibrary 1.4.

Zooms in on an element a certain amount.

Arguments

• locator
• percent=200%
• steps=1

Zooms in on an element a certain amount.