mob

Provides methods for mobile automation.

Locators:

Native application locators for
  • /XPATH - Locates element using an XPath 1.0 expression.
  • id=ID - Locates element by its id.
  • class=CLASS - Locates element by its class.
  • text=TEXT - Locates element by its visible text.
  • text-contains=TEXT - Locates element whose visible text contains the specified string.
  • desc=DESCRIPTION - Locates element by its description.
  • desc-contains=DESCRIPTION - Locates element whose description contains the specified string.
  • scrollable - Locates elements that are scrollable.

Native application locators for
  • /XPATH - Locates element using an XPath 1.0 expression.
  • id=ID - Locates element by its ID.
  • ~ACCESSIBILITY_ID - Locates element by its Accessibility Id.
Hybridand Webapplication locators for
  • /XPATH - Locates element using an XPath 1.0 expression.
  • id=ID - Locates element by its id.
  • name=NAME - Locates element by its name attribute.
  • link=TEXT - Locates anchor element whose text matches the given string.
  • link-contains=TEXT - Locates anchor element whose text contains the given string.
  • css=CSS_SELECTOR - Locates element using a CSS selector.


Pattern arguments:

Commands which expect a string matching pattern in their arguments, support following patterns unless specified otherwise:
  • regex:PATTERN - Match using regular expression.
  • PATTERN - Verbatim matching.

Methods

getCaps()→ {Object}

Returns currently defined device capabilities.

Returns:
Object - capabilities - Current capabilities object.

init(caps, host, port)

Initializes a new Appium session.

Parameters:
Name Type Description
caps String= optionalDesired capabilities. If not specified capabilities will be taken from suite definition.
host String= optionalAppium server host name or Selenium Grid full URL (default: localhost).
port Number= optionalAppium server port (default: 4723). If full URL is specified in the host parameter, port parameter must not be specified.

transaction(name)

Opens new transaction.

The transaction will persist till a new one is opened. Transaction names must be unique.

Parameters:
Name Type Description
name String The transaction name.

dispose()

Ends the current session.

alertAccept()

Accepts currently displayed alert.

alertDismiss()

Dismisses currently displayed alert.

assertText(locator, pattern, message)

Asserts element's inner text.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
pattern String Assertion text or pattern.
message String= optionalMessage to generate in case of assert failure.

assertTitle(pattern, message)

Asserts the page title.

Parameters:
Name Type Description
pattern String Assertion text or pattern.
message String= optionalMessage to generate in case of assert failure.

assertValue(locator, pattern, message)

Asserts element's value.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
pattern String Assertion text or pattern.
message String= optionalMessage to generate in case of assert failure.

back()

Navigate backwards in the browser history or simulates back button on Android device.

clear(locator)

Clears element's value or content

Parameters:
Name Type Description
locator (String|WebElement) Element locator.

click(locator)

Clicks on an element.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.

clickHidden(locator, clickParent)

Clicks hidden element.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
clickParent Boolean= optionalIf true, then parent of the element is clicked.

clickLong(locator, duration)

Performs a long click/touch on an element.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
duration Number Touch duration in milliseconds.

clickMultipleTimes(locator, taps)

Performs tap on an element multiple times in quick succession.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
taps Number Number of taps.

dragAndDrop(locator, xoffset, yoffset)

Tap on an element, drag by the specified offset, and release.

Parameters:
Name Type Description
locator (String|WebElement) Element locator on which to perform the initial tap.
xoffset Number Horizontal offset. Positive for right direction; Negative for left.
yoffset Number Vertical offset. Negative for up direction; Positive for down.

enableNetwork(wifi, data)

Enable or disable wifi or data.

Parameters:
Name Type Description
wifi Boolean Enable (true) or disable (false) wifi.
data Boolean Enable (true) or disable (false) data.

execute(script, arg)→ {Object}

Executes JavaScript in the context of the currently selected frame or window.

If return value is null or there is no return value, null is returned.

Parameters:
Name Type Description
script (String|Function) The JavaScript to execute.
arg ...Object optionalOptional script arguments.
Returns:
Object - The return value.

findElement(locator, parent)→ {WebElement}

Finds an element.

Parameters:
Name Type Description
locator String Element locator.
parent Object= optionalOptional parent element for relative search.
Returns:
WebElement - A WebElement object.

findElements(locator, parent)→ {Array.<WebElement>}

Finds elements.

Parameters:
Name Type Description
locator String Element locator.
parent Object= optionalOptional parent element for relative search.
Returns:
Array.<WebElement> - Collection of WebElement JSON objects.

alertText()→ {String}

Gets alert text.

Returns:
String - Alert's text.

getLocation(locator)

Get element's location.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.

getSource()→ {String}

Gets the source code of the page.

Returns:
String - HTML in case of web or hybrid application or XML in case of native.

getText(locator)→ {String}

Gets element's text.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
Returns:
String - Element's text.

getValue(locator)→ {String}

Gets element's value.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
Returns:
String - Element's value.

hideKeyboard(strategy)

Hides device keyboard.

Parameters:
Name Type Description
strategy String= optionalStrategy to use for closing the keyboard - `tapOutside` or `pressDone`. Default is `tapOutside`.

isCheckable(locator)→ {Boolean}

Determines if checkbox or radio element is checkable.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
Returns:
Boolean - true if element is checkable. false otherwise.

isChecked(locator)→ {Boolean}

Determines if checkbox or radio element is checked.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
Returns:
Boolean - true if element is checked. false otherwise.

isClickable(locator)→ {Boolean}

Determines if an element is clickable.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
Returns:
Boolean - true if element is clickable. false otherwise.

isExist(locator, wait)→ {Boolean}

Wait for an element to become available.

The element is not necessary needs to be visible.

Parameters:
Name Type Description
locator String Element locator.
wait Number= optionalTime in milliseconds to wait for the element. Default is 60 seconds.
Returns:
Boolean - true if the element exists. false otherwise.

isSelected(locator)→ {Boolean}

Determines if an element is selected.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
Returns:
Boolean - true if element is selected. false otherwise.

isVisible(locator, timeout)→ {Boolean}

Checks if element is present and visible. Returns false if element was not found or wasn't visible within the specified timeout.

Parameters:
Name Type Description
locator (String|WebElement) An element locator.
timeout Number= optionalTimeout in milliseconds to wait for element to appear. Default is 60 seconds.
Returns:
Boolean - True if element was found and it was visible. False otherwise.

isWebViewContext()→ {Boolean}

Checks if the current context is of WebView type.

Returns:
Boolean - true if the context name is WEBVIEW or CHROMIUM.

open(url)

Opens an URL.

Parameters:
Name Type Description
url String The URL to open.

pause(ms)

Pauses test execution for given amount of milliseconds.

Parameters:
Name Type Description
ms Number milliseconds to pause the execution.

scrollIntoElement(scrollElmLocator, findElmLocator, xoffset, yoffset, retries)

Scrolls the view element until a specified target element inside the view is found.

Parameters:
Name Type Description
scrollElmLocator String View element to scroll.
findElmLocator String Target element to find in the view.
xoffset Number= optionalIndicates the size in pixels of the horizontal scroll step (positive - scroll right, negative - scroll left). Default is 0.
yoffset Number= optionalIndicates the size in pixels of the vertical scroll step (positive - scroll up, negative - scroll down). Default is -30.
retries Number= optionalIndicates the number of scroll retries before giving up if element not found. Default is 50.

scrollIntoView(locator, alignToTop)

Scrolls the element into the visible area of the browser window.

Parameters:
Name Type Description
locator String Element locator.
alignToTop Boolean= optionalIndicates whether to align the element to the top. Element is centered otherwise.

selectFrame(frameLocator)

Selects a frame or an iframe within the current window.

Available frame locators:

  • 'parent' - Select parent frame.
  • 'top' - Select top window.
  • NUMBER - Select frame by its 0-based index.
  • LOCATOR - Locator identifying the frame (relative to the top window). Multiple locators can be passed in order to switch between nested frames.
Parameters:
Name Type Description
frameLocator ...(String|Number) optionalA locator identifying the frame or iframe. Or a series of locators.

sendKeys(value)

Send a sequence of key strokes to the active window or element.

Refer to Key Codes for the list of supported raw keyboard key codes.

Parameters:
Name Type Description
value String Sequence of key strokes to send.

setAutoWait(enable)

Specifies whether commands should automatically wait till element appear before executing.

By default automatic waiting is enabled. This setting affects all commands which expect to perform some action on elements, except wait*, assert*, is* and other commands which receive optional timeout parameter.

Parameters:
Name Type Description
enable Boolean true to enable automatic waiting, false to disable.

setContext(context)

Sets a specific context (NATIVE_APP, WEBVIEW, etc.).

Parameters:
Name Type Description
context String The context name.

setNativeContext()

Sets context to NATIVE_APP.

setWebViewContext()

Sets context to the first available WEBVIEW or CHROMIUM (Crosswalk WebView) view.

shake()

Perform shake action on the device

Supported on Android and iOS 9 or earlier versions.

smsClickLink(wait)

Clicks SMS message URL.

SMSPopup application must be installed and running on the device to use this command. https://github.com/oxygenhq/android-smspopup/releases

Parameters:
Name Type Description
wait Number= optionalTime in milliseconds to wait for sms popup. Default is 60 seconds.

smsGetText(wait)→ {String}

Gets SMS text on Android phone.

SMSPopup application must be installed and running on the device to use this command. https://github.com/oxygenhq/android-smspopup/releases

Parameters:
Name Type Description
wait Number= optionalTime in milliseconds to wait for sms popup. Default is 60 seconds.
Returns:
String - SMS text.

swipe(locator, xoffset, yoffset, speed)

Perform a swipe on the screen or an element.

Parameters:
Name Type Description
locator String= optionalLocator of the element to swipe on.
xoffset Number Horizontal offset.
yoffset Number Vertical offset. Negative value indicates swipe down and positive indicates swipe up direction.
speed Number= optionalThe speed of swiping in pixels per second. Default is 30.

takeScreenshot()→ {String}

Take a screenshot of the current page or screen and return it as base64 encoded string.

Returns:
String - Screenshot image encoded as a base64 string.

tap(x, y)

Perform tap at the specified coordinate.

Parameters:
Name Type Description
x Number x offset.
y Number y offset.

type(locator, value)

Send a sequence of key strokes to an element (clears value before).

Refer to Key Codes for the list of supported raw keyboard key codes.


Example of typing a sequence of characters and pressing Enter afterwards.

mob.type('id=someElement', 'hello world\uE007');
Parameters:
Name Type Description
locator (String|WebElement) An element locator.
value String The value to type.

unlockPattern(locator, cols, rows, pattern)

Unlocks a pattern lock


1 2 3
4 5 6
7 8 9
a b c
Parameters:
Name Type Description
locator String Element locator for the pattern lock.
cols Number Number of columns in the pattern.
rows Number Number of rows in the pattern.
pattern String Pattern sequence. Pins are hexadecimal and case sensitive. See example.

verifyText(locator, pattern, message)

Verifies element's inner text.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
pattern String Assertion text or pattern.
message String= optionalMessage to generate in case of verification failure.

verifyTitle(pattern, message)

Verifies the page title.

Parameters:
Name Type Description
pattern String Assertion text or pattern.
message String= optionalMessage to generate in case of verification failure.

verifyValue(locator, pattern, message)

Verifies element's value.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
pattern String Assertion text or pattern.
message String= optionalMessage to generate in case of verification failure.

waitForExist(locator, wait)

Wait for an element for the provided amount of milliseconds to be present.

The element is not necessary needs to be visible.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
wait Number= optionalTime in milliseconds to wait for the element. Default is 60 seconds.

waitForVisible(locator, wait)

Wait for an element for the provided amount of milliseconds to be visible.

Parameters:
Name Type Description
locator (String|WebElement) Element locator.
wait Number= optionalTime in milliseconds to wait for the element. Default is 60 seconds.