Appium keywords

Observations

Mandatory keyword arguments are shown in bold font.
All keywords listed in this page are found in the package org.getopentest.appium, so you must prefix their names with this package name when calling them. For example, to call the Tap action, use this syntax:
```
- description: Tap the submit button
  action: org.getopentest.appium.Tap
  args:
    locator: { id: submit }
```
If you have some basic familiarity with the Java language and would like to know more about how a certain keyword is implemented, please take a peek at the source code.

UI element locators

Since most Appium keywords act on a particular UI element, they need to be given a way to identify that element. This is done by providing a locator argument. Locator arguments are simply objects that must contain the information necessary to identify a UI element using one of the following methods supported by Appium: id, css, name, class, tag, text, linkText, partialLinkText or xpath. Some examples:

locator: {id: element1}
locator: {name: name1}
locator: {class: class1}
locator: {xpath: "//android.widget.TextView[@text='Submit']"}

And some locators specific to web views:

locator: {css: #container div.class1}
locator: {linkText: Submit the form}
locator: {partialLinkText: Submit}
locator: {tag: button}

Note

In most cases, the values specified in locator arguments do not need to be enclosed in double quotes (courtesy of the YAML format). However, most xPath expressions must be enclosed in double quotes because they contain the square brackets characters "[" and "]", which in YAML are special characters used to represent an array value.

When doing mobile testing, it is a very common scenario to have to perform one or more swipe gestures in a scroll container in order to find a UI element we are looking to interact with. OpenTest makes this easy and automatic by enabling certain keywords with the ability to perform the scroll whenever necessary. All test actions that need to interact with a UI element have this capability.

The following test action arguments are available for all swipe-enabled actions:

swipe

The direction to swipe towards. Valid values are: up, down, left, right, none. Default: none. Please note that the value up means that we need to swipe so that we move upwards in the scroll container. The value up does not indicate the direction of the swipe gesture itself. Default: none.

swipeContainer

The locator of the UI element that the swipe gesture will be executed into. All coordinate calculations are going to be performed relative to the position and size of this container element. Default: null.

swipeDurationMs

The duration of the swipe gesture, in milliseconds. If more than one swipe is necessary to reach the target element, each one of the swipes will have this duration. Default: 1000.

maxSwipes

The maximum number of swipe gestures allowed in search of the target element (or edge) before we give up. Default: 20.

swipeOffsetTop

The percentage of the swipe container height that the swipe gesture will start or end at, from the top side of the container. Default: 0.1 when a swipe container is provided in the swipeContainer argument and 0.2 otherwise.

swipeOffsetBottom

The percentage of the swipe container height that the swipe gesture will start or end at, from the bottom side of the container. Default: 0.1 when a swipe container is provided in the swipeContainer argument and 0.2 otherwise.

swipeOffsetLeft

The percentage of the swipe container width that the swipe gesture will start or end at, from the right side of the container. Default: 0.1.

swipeOffsetRight

The percentage of the swipe container width that the swipe gesture will start or end at, from the left side of the container. Default: 0.1.

swipeMaxEdgeCheckRetries

The maximum number of times we will check to verify that we reached the end of the page (by examining the page source). We normally need one single check, but in some scenarios the elements on the screen can look the same between two consecutive swipes, so we need to check multiple times to make sure we reached the edge. Default: 1.

Example 1:

- description: Find "product1" by swiping down and tap on it
  action: org.getopentest.appium.Tap
  args:
    locator: { id: product1 }
    swipe: down

Example 2:

- description: |
    Find "product1" by swiping down in the "products" scroll view
    and validate its text contains the word "Gillette"
  action: org.getopentest.appium.AssertElementText
  args:
    locator: { id: product1 }
    textContains: Gillette
    swipe: down
    swipeContainer: { id: products }
    swipeOffsetTop: 0.3

A substring that we expect to be present anywhere in the UI element.

caseInsensitive

Specifies whether the text comparison operations will be carried out case-insensitive. Default: false.

swipe +

This is a swipe-enabled action, which supports all of the swipe-related keyword arguments.

Example:

- description: Verify that the "product" textbox contains "MacBook"
  action: org.getopentest.appium.AssertElementText
  args:
    locator: { id: product }
    textContains: MacBook

AssertElementVisible

Verifies that a UI element is visible on the screen.

Arguments:

locator

The locator of the UI element.

swipe +

This is a swipe-enabled action, which supports all of the swipe-related keyword arguments.

Example:

- description: Verify that the submit button is visible
  action: org.getopentest.appium.AssertElementVisible
  args:
    locator: { id: submit }

CloseApp

Closes the application. Internally uses the AppiumDriver.closeApp() method.

Example:

- description: Close the application.
  action: org.getopentest.appium.CloseApp

HideKeyboard

Hides the keyboard, if it is showing. On iOS, there are multiple strategies for hiding the keyboard. Defaults to the "tapOutside" strategy (taps outside the keyboard). Try passing the argument keyName: Done, if this doesn’t work.

Arguments:

keyName

The button pressed by the mobile driver to attempt hiding the keyboard. Only used for iOS.

Example:

- description: Hide the keyboard
  action: org.getopentest.appium.HideKeyboard
  args:
    keyName: Done

InitAppium

Creates and initializes the Appium driver instance. It is not necessary to call this action yourself, since the test actor will create the driver automatically the first time you attempt run any Appium test action. The InitAppium action is only necessary for advanced use cases, when you need more control over the way the Appium driver instance is created (e.g. you need to override one or more desired capabilities or you want to use a custom Appium URL for the duration of one single test).

Arguments:

url

The Appium server URL. If not specified, it will be read from the "appium.appiumServerUrl" parameter in the test actor’s configuration file.

desiredCapabilities

A hashmap containing name-value pairs of capabilities to pass when creating the driver. These capabilities will override the ones in the actor’s configuration file.

Example:

- description: Initializes the Appium driver
  action: org.getopentest.appium.InitAppium
    args:
        desiredCapabilities:
            app: /Users/username/myapp-v2-qa.app

LaunchApp

Launches the app that was provided the in desired capabilities. Internally uses the AppiumDriver.launchApp() method.

Example:

- description: Launch the mobile app
  action: org.getopentest.appium.LaunchApp

LongPress

Performs a long press gesture at the center of a UI element for the specified duration.

Arguments:

locator

The locator of the UI element.

durationMs

The duration of the long press, in milliseconds. Default: null. If the duration argument is not specified it will be determined by the default Appium behavior.

swipe +

This is a swipe-enabled action, which supports all of the swipe-related keyword arguments.

Example:

- description: Long press on product 1
  action: org.getopentest.appium.LongPress
  args:
    locator: { id: product1 }

NavigateBack

Moves back to the previous screen.

Example:

- description: Go back
  action: org.getopentest.appium.NavigateBack

ReadElementAspect

Reads the position and size of a UI element.

Arguments:

locator

The locator of the UI element.

swipe +

This is a swipe-enabled action, which supports all of the swipe-related keyword arguments.

Output values:

x

The X coordinate of the UI element.

y

The Y coordinate of the UI element.

width

The width of the UI element.

height

The height of the UI element.

Example:

- description: Read the position and size of the red box
  action: org.getopentest.appium.ReadElementAspect
  args:
    locator: { id: red }

- description: Log the element position and size
  script: |
    $log($format(
      "The element aspect is {0},{1},{2},{3}",
      $output.x,
      $output.y,
      $output.width,
      $output.height));

ReadElementAttribute

Reads the value of the specified attribute on a UI element.

Arguments:

locator

The locator of the UI element.

attribute

The name of the attribute.

swipe +

This is a swipe-enabled action, which supports all of the swipe-related keyword arguments.

Output values:

value

The value of the attribute.

Example:

- description: Read the "focusable" attribute of the "name" textbox
  action: org.getopentest.appium.ReadElementAttribute
  args:
    locator: { id: name }
    $localData:
        focusable: $output.value


- description: Log the element position and size
  script: |
    $log("The focusable attribute's value is" + $localData("focusable"));

ReadElementText

Reads the visible text of this element, including sub-elements, without any leading or trailing whitespace.

Arguments:

locator

The locator of the UI element.

swipe +

This is a swipe-enabled action, which supports all of the swipe-related keyword arguments.

Output values:

text

The text content of the element.

Example:

- description: Read the text content of product 1
  action: org.getopentest.appium.ReadElementText
  args:
    locator: { id: product1 }
    $localData:
        productName: $output.text

- description: Log the product name
  script: |
    $log("The product name is " + $localData("productName"));

ReadPageSource

Get the XML source of the last loaded page.

Output values:

pageSource

The page source in XML format.

Example:

- description: Read the page source
  action: org.getopentest.appium.ReadPageSource
  args:
    $localData:
        pageSource: $output.pageSource

- description: Log the page source
  script: |
    $log("The page source is " + $localData("pageSource"));

ReadScreenSize

Reads the screen size of the device we are currently running on.

Output values:

screenWidth

The width of the screen.

screenHeight

The height of the screen.

Example:

- description: Read the screen size
  action: org.getopentest.appium.ReadScreenSize
  args:
    $localData:
        screenWidth: $output.screenWidth
        screenHeight: $output.screenHeight

- description: Log the screen size
  script: |
    $log($format("The screen size is ({0}, {1})",
      $localData("screenWidth"),
      $localData("screenWidth"));

ResetApp

Reset the currently running app for this session. Internally it calls the Appium driver.resetApp() API.

Example:

- description: Reset the app
  action: org.getopentest.appium.ResetApp

RunAppInBackground

Runs the current app as a background app for the number of seconds requested. The test action will finish executing after the specified time interval is over and the app has been returned to the foreground.

Arguments:

seconds

The number of seconds to run as a background app.

Example:

- description: Run the app in background for 10 seconds
  action: org.getopentest.appium.RunAppInBackground
  args:
    seconds: 10

SendKeys

Simulates typing into an element, which may set its value (depending on the type of UI element).

Arguments:

locator

The UI element to type in.

text

The text to type.

clearContent

Instructs the action to clear the content of the element before typing in the new one. Default: false.

hideKeyboard

Instructs the action to attempt hiding the keyboard after it finishes typing.

useKeyboardService

Determines what API will be used when doing the typing. When using the keyboard service, the driver.getKeyboard().sendKeys() API will be used. Otherwise, we will use element.sendKeys(). Default: false.

swipe +

This is a swipe-enabled action, which supports all of the swipe-related keyword arguments.

Example:

- description: Type "John Doe" in the name text box
  action: org.getopentest.appium.SendKeys
  args:
    locator: { id: name }
    text: John Doe

Swipe

Performs one or more swipe gestures.

Arguments:

direction

The direction to swipe in (up, down, left, right).

target

The UI element that we are looking to find as we are swiping. The swipe will stop as soon as the element has been found.

durationMs

The duration of the swipe gesture, in milliseconds. Default: 1000.

swipeContainer

The locator of the UI element the swipe will be executed into. All coordinate calculations are going to be performed relative to the position and size of the swipe container element. When the swipe container is not specified, it defaults to the entire screen.

swipeToEdge

When true, causes the swipe to continue until it reaches the edge of the swipe container.

maxSwipes

The maximum number of swipe gestures allowed in search of the target element (or edge) before we give up.

offsetBottom

The percentage of the swipe container height that the swipe gesture will start or end at, from the bottom side of the container. Default: 0.1 when swipe container is provided, and 0.2 otherwise.

offsetLeft

The percentage of the swipe container width that the swipe gesture will start or end at, from the left side of the container. Default: 0.1.

offsetRight

The percentage of the swipe container width that the swipe gesture will start or end at, from the right side of the container. Default: 0.1.

offsetTop

The percentage of the swipe container height that the swipe gesture will start or end at, from the top side of the container. Default: 0.1 when swipe container is provided, and 0.2 otherwise.

Example:

- description: Swipe towards the right in search of the delete button
  action: org.getopentest.appium.Swipe
  args:
    direction: right
    target: { id: delete }

SwitchContext

Switch the focus of future commands to the context with the given name. This is necessary in order to perform test actions inside a web view control (WebView in Android or UIWebView in iOS).

Arguments:

context

The context name. This is typically either NATIVE_APP to switch to the native UI, or WEBVIEW_1, WEBVIEW_2 and so on, to target the web view controls in the current screen.

Example:

- description: Switch context to the first web view on the screen
  action: org.getopentest.appium.SwitchContext
  args:
    context: WEBVIEW_1

SwitchToFrame

Switches the focus of future commands to the specified iframe element.

Arguments:

frameName

The frame’s name. At least one of the frameName ,frameIndex or the locator arguments must be provided.

locator

The frame element’s locator.

frameIndex

The frame’s index (first frame in the page has index 0).

Example 1:

- description: Switch to the "products" frame (by name)
  action: org.getopentest.appium.SwitchToFrame
  args:
    frameName: products

Example 2:

- description: Switch to the "products" frame (by CSS)
  action: org.getopentest.appium.SwitchToFrame
  args:
    locator: { css: "iframe[name='products']" }

TakeScreenshot

Captures a screenshot of the mobile device’s display. The image is saved in the test actor working directory and is sent asynchronously to the OpenTest server so it can be presented in the web-based test execution report.

Example:

- description: Take a screenshot
  action: org.getopentest.appium.TakeScreenshot

Tap

Performs a tap (click) at the center of the specified element.

Arguments:

locator

The locator of the UI element.

xOffset

The offset on the X axis from the top-left corner of the UI element identified by the locator argument. It should be noted that, if either the xOffset or the yOffset argument is present, the location of the click is relative to the top-left corner of the UI element. Otherwise, the tap will happen at the center of the element.

yOffset

The offset on the Y axis from the top-left corner of the UI element identified by the locator argument.

x

The absolute X coordinate to tap at.

y

The absolute Y coordinate to tap at.

swipe +

This is a swipe-enabled action, which supports all of the swipe-related keyword arguments.

Example 1 - tap the center of a UI element:

- description: Tap on first product
  action: org.getopentest.appium.Tap
  args:
    locator: { id: product1 }

Example 2 - tap a UI element after swiping down to find the element, as necessary:

- description: Swipe and tap on first product
  action: org.getopentest.appium.Tap
  args:
    locator: { id: product1 }
    swipe: down

Example 3 - tap at coordinates (20,20) from the top-left corner of the UI element:

- description: Tap on first product
  action: org.getopentest.appium.Tap
  args:
    locator: { id: product1 }
    xOffset: 20
    yOffset: 20

Example 4 - tap the screen at (200, 200) in absolute screen coordinates:

- description: Tap at screen coordinates (200,200)
  action: org.getopentest.appium.Tap
  args:
    x: 200
    y: 200

Docs

Reference

Tutorials

Appium keywords

Observations

UI element locators

Keyword list

AssertElementChecked

AssertElementEnabled

AssertElementNotChecked

AssertElementNotEnabled

AssertElementNotVisible

AssertElementText

AssertElementVisible

CloseApp

HideKeyboard

InitAppium

LaunchApp

LongPress

NavigateBack

ReadElementAspect

ReadElementAttribute

ReadElementText

ReadPageSource

ReadScreenSize

ResetApp

RunAppInBackground

SendKeys

Swipe

SwitchContext

SwitchToFrame

TakeScreenshot

Tap

Docs

Reference

Tutorials

Appium keywords

Observations

UI element locators

Swipe-related keyword arguments

Keyword list

AssertElementChecked

AssertElementEnabled

AssertElementNotChecked

AssertElementNotEnabled

AssertElementNotVisible

AssertElementText

AssertElementVisible

CloseApp

HideKeyboard

InitAppium

LaunchApp

LongPress

NavigateBack

ReadElementAspect

ReadElementAttribute

ReadElementText

ReadPageSource

ReadScreenSize

ResetApp

RunAppInBackground

SendKeys

Swipe

SwitchContext

SwitchToFrame

TakeScreenshot

Tap