WebDriver Commands and Functions for Mobile Device Testing

You can use WebDriver commands and functions to automate both iOS and Android mobile devices. The free iOS Gateway is required to automate iOS devices. For Android testing, you can use the free Android Gateway.

Important: You must have Faster Screen Updates enabled in order to accurately click WebElements when doing WebDriver testing on iOS devices.

In mobile WebDriver testing, connections are made to a specific app rather than to a browser on your system under test (SUT). Testing with WebDriver is based around interacting with various elements in the app you're testing.

On this page:

WebElement Identifiers

To access a WebElement within the app you're testing, such as when using the FindElement() function or the Click command with a WebDriver connection, you must specify the element you want to interact with. The following WebElement Identifiers can be used to locate elements on a mobile device:

  • webID: Use this property to locate an element by the value of its ID attribute.
  • webName: Use this property to locate an element by the value of its Name attribute.
  • webClassName: Use this property to locate an element by the value of its Class attribute.
  • webXPath: Use this property to locate an element by using an XPath expression. For information about XPath and XPath expressions, see XPath in Selenium WebDriver: Complete Tutorial.
  • webAccessibilityID: Use this property to locate an element by the value of its Accessibility ID attribute.

WebConnect Command

Note: This code definition explains the use of the WebConnect command for mobile WebDriver connections. For information about using this command for browser-based WebDriver connections, see WebDriver Actions: WebConnect Command.

Behavior: This command makes a connection to a specified app on a mobile device.

Parameters: The WebConnect command can take the following parameters:

  • browser: Optional.
  • host: Required. For mobile device connections, this is always localhost.
  • port: Required. The port number over which to create a mobile WebDriver connection. The default port for iOS connections is 8100. The default port for Android connections is 4723.
  • name: Optional. A name to use for referring to this connection. This is the name that appears in the Eggplant Functional Connection List. If this is specified, the script will pull the browser, host, port, and platformName (if mobile) for that connection. Any of those properties provided to the WebConnect command will override those set in the Connection List. If no connection with the specified name exists in the Eggplant Functional Connection List, then a new connection will be created and saved with the information provided.
  • platformName: Mobile Only. Required. The operating system of the mobile device.
  • bundleId: iOS only. Required. The identifier of the mobile app you want to open and test. This parameter is case-sensitive.
  • device: Android only. Required. The ID number of the device. This can be found by entering adb devices in the command line.
  • appPackage: Android only. Required. The identifier of the mobile app you want to open and test. This parameter is case-sensitive.
  • appActivity: Android only. Required. The screen in the app that you want the app to open on. This parameter is case-sensitive.
  • automationName: Android only. Required. The automation engine to use to test the device.

Syntax:

WebConnect connectionProperties

connectionProperties can include:

{browser: browserName,}

{host: hostAddress,}

{port: portName,}

{url: pageURL,}

{name: connectionName,}

{desiredCapabilities: {capabilitiesPropertyList},}

{platformName: NameofPlatform,}

{bundleId: bundleIDNumber}

ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Note: In the case of desiredCapabilities, the curly braces are a part of the required syntax, as they are used when communicating with SauceLabs connections.

Example:

WebConnect host:"localhost", port:"8100", platformName: "iOS", bundleId: "com.apple.Maps"

Example:

WebConnect host: "localhost", port: "4723", platformName: "Android", device: "04157df49c1d0533", deviceName: "Android", appPackage: "com.google.android.apps.maps", appActivity: "com.google.android.maps.MapsActivity", automationName: "UIAutomator2"

WebDisconnect Command

Note: This code definition explains the use of the WebDisconnect command for mobile WebDriver connections. For information about using this command for browser-based WebDriver connections, see WebDriver Actions: WebDisconnect Command.

Behavior: This command disconnects WebDriver connections.

Parameters: None, a connection name, or All. If you do not specify any parameters, the active WebDriver disconnects. Use WebDisconnect with a specific connection name to close that connection, or use All to close all active connections.

Syntax:

WebDisconnect {connectionName | All}
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

WebDisconnect // Disconnects the active WebDriver connection

Example:

WebDisconnect All // Disconnects all WebDriver connections

Example:

webDisconnect "iphone7"// Disconnects the WebDriver connection named "iphone7"

WebDriver Function

Note: This code definition explains the use of the WebDriver() function for mobile WebDriver connections. For information about using this function for browser-based WebDriver connections, see WebDriver Actions: WebDriver() Function.

Behavior: By default, the function returns properties for the active WebDriver connection (if there is one). You can include parameters as specified below to switch to a different open connection (if available) or open a new connection.

When opening a new connection or switching the active connection, the WebDriver() function performs the same actions as the WebConnect command.

Parameters: The WebDriver() function can take the following parameters:

  • host: (Required) For mobile device connections, this is always localhost.
  • port: (Required) The port number over which to create a mobile WebDriver connection. The default port for iOS connections is 8100. The default port for Android connections is 4723.
  • name: (Optional) A name to use for referring to this connection. If specified, this is the name that appears in the Connection List.
  • platformName: (Required) The operating system of the mobile device.
  • bundleId: (iOS only. Required.) The identifier of the mobile app you want to open and test. This parameter is case-sensitive.
  • device: (Android only. Required.) The ID number of the device. This can be found by entering adb devices in the command line.
  • appPackage: (Android only. Required.) The identifier of the mobile app you want to open and test. This parameter is case-sensitive.
  • appActivity: (Android only. Required.) The screen in the app that you want the app to open on. This parameter is case-sensitive.
  • automationName: (Android only. Required.) The automation engine to use to test the device.

Syntax:

WebDriver (host: hostAddress, port: port, {name: "connectionName"} {, name: "value"} {, platformName: "value"} {, bundleId: "value"} {, device: "value"} {, appPackage: "value"} {, appActivity: "value"} {, automationName: "value"} )
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Returns: If you call the WebDriver() function without parameters, it returns the WebDriverConnection object of the active WebDriver connection.

If you open a WebDriver connection with the WebDriver() function, it returns the WebDriverConnection object for the newly created WebDriver connection.

Example:

put WebDriver() // Returns information about the active WebDriver connection: <WebDriverConnection with Name:"iphone6plus", PlatformName:"iOS", Host:"localhost", BundleID:"com.testplant.YetAnotherSampleApp">

Example:

set driver to WebDriver(host:"localhost", port: "8100", platformName: "iOS", bundleId: "com.testplant.YetAnotherSampleApp")

Example:

set driver to WebDriver(host: "localhost", port: "4723", platformName: "Android", appPackage:"com.google.android.apps.maps", appActivity:"com.google.android.maps.MapsActivity", automationName:"UIAutomator2")

FindElement Function

Note: This code definition explains the use of the FindElement() function for mobile WebDriver connections. For information about using this function for browser-based WebDriver connections, see Finding WebElements: FindElement() Function.

Behavior: This command locates a specific WebElement that you can interact with.

Parameters: The WebElement Identifier of the element that you want to find.

Syntax:

FindElement (IdentifierType: "Value")
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

set textField to findElement (webName: "Enter Text Field") // Creates the variable textField containing the element with the WebName "Enter Text Field"

SwipeDown, SwipeLeft, SwipeRight, SwipeUp Commands

Note: This code definition explains the use of the Swipe commands for mobile WebDriver connections. For information about using this function for other mobile connections, see Mobile Control and Touch Events: Swipe Commands.

Behavior: These commands execute a directional swipe on the specified element.

Parameters: The WebElement Identifier of the element to execute the swipe on.

Syntax:

SwipeDown (identifierType: "value")

SwipeDown (identifierType: "value")

SwipeLeft (identifierType: "value")

SwipeRight (identifierType: "value")

ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

SwipeUp (webClassName: "XCUIElementTypeMap")

ClearKeys Command

Note: This code definition explains the use of the ClearKeys command for mobile WebDriver connections. For information about using this function for browser-based WebDriver connections, see WebDriver Mouse and Keyboard Events: ClearKeys Command.

Behavior: This command clears the text entered in the specified WebElement.

Parameters: The WebElement Identifier of the element to clear.

Syntax:

ClearKeys (identifierType: "value")
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

ClearKeys (webName: "Enter Text Field") // Clears text from the element with the webName "Enter Text Field"

Example:

set textField to findElement(webName: "Enter Text Field") // Puts the name of a WebElement into a variable

ClearKeys textField // Clears text from the WebElement

SendKeys Command

Note: This code definition explains the use of the SendKeys command for mobile WebDriver connections. For information about using this function for browser-based WebDriver connections, see WebDriver Mouse and Keyboard Events: SendKeys Command.

Behavior: This command sends keystrokes to an element on the mobile device.

Parameters: A text string enclosed in quotation marks. If you need to include quote characters in your text string, you can enclose the text in double angle brackets (<<>>).

Syntax:

SendKeys {"text" | <<text>>}
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

SendKeys "Hello World!" // Sends text to the active element

Example:

set textField to findElement (webName: "Enter Text Field") // Puts the name of a WebElement into a variable

SendKeys textField, "A nod's as good as a wink to a blind bat" // Uses the variable to make the WebElement active, then sends the keystrokes to type: "A nod's as good as a wink to a blind bat"

Tap Command

Note: This code definition explains the use of the Tap command for mobile WebDriver connections. For information about using this function for other mobile connections, see Mobile Control and Touch Events: Tap Command.

Behavior: The Tap command locates an element within the DOM and simulates a tap event at the found location.

Parameters: The WebElement Identifier of the element to tap.

Syntax:

Tap (identifierType: "value")
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

Tap (webName: "Map") // Locates the "Map" element and executes a tap

DoubleTap Command

Note: This code definition explains the use of the DoubleTap command for mobile WebDriver connections. For information about using this function for other mobile connections, see Mobile Control and Touch Events: DoubleTap Command.

Behavior: The DoubleTap command locates an element within the DOM and simulates a double-tap event at the found location.

Parameters: The WebElement Identifier of the element to double-tap.

Syntax:

DoubleTap (identifierType: "value")
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

DoubleTap (webClassName: "XCUIElementTypeMap") // Locates the element with class name "XCUIElementTypeMap" and executes a double-tap

WebScreenshot Command

Note: This code definition explains the use of the WebScreenshot command for mobile WebDriver connections. For information about using this function for browser-based WebDriver connections, see WebDriver Actions: WebScreenshot Command.

Behavior: This command takes a screenshot of the mobile device with the active WebDriver connection and saves it according to the specified file name or full file path.

Parameters: A required file name that can optionally include the full file path of the desired save location. If no file path is included in the filename parameter, the screenshot is saved into the user's documents directory.

Syntax:

WebScreenshot {"webDriverName",} "fileName"
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

WebScreenshot "shot1" // Captures a WebDriver screenshot for the active WebDriverConnection and saves it with the name 'shot1'

Example:

WebScreenshot "/Users/admin/Desktop/shot5" // Saves a screenshot to the Desktop with name 'shot5'

GetDeviceOrientation Function

Note: This code definition explains the use of the GetDeviceOrientation() function for mobile WebDriver connections. For information about using this function for other mobile connections, see Mobile SUT Information: GetDeviceOrientation Function.

Behavior: This function returns the current rotation of the screen of the device with the active WebDriver connection.

Parameters: None.

Syntax:

GetDeviceOrientation()
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Returns: The possible values are the same as the parameters for the setDeviceOrientation command: Landscape, LandscapeRight, Portrait, PortraitUpsideDown.

Example:

put GetDeviceOrientation() // Returns the orientation of the device screen

Example:

put "Device rotated to " & GetDeviceOrientation() // Returns "Device rotated to" the orientation of the device screen

Related:

SetDeviceOrientation Command

Note: This code definition explains the use of the SetDeviceOrientation command for mobile WebDriver connections. For information about using this function for other mobile connections, see Mobile Control and Touch Events: SetDeviceOrientation Command.

Behavior: Changes the orientation of the device with the active WebDriver connection to what you specify with the parameter. The different orientations work only if the active app and operating system support them.

Parameters: The device orientation that you want to set. Options are Portrait, PortraitUpsideDown, Landscape, LandscapeRight. Note that Android devices accept only Portrait and Landscape. If the requested orientation isn't supported by the operating system or app, no error is returned and the screen remains in its previous orientation.

Syntax:

SetDeviceOrientation value
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

SetDeviceOrientation LandscapeRight

Related:

TouchAction Command

Behavior: Combines with other commands to simulate touch actions on a device. When used with moveTo, simulates dragging across a screen on a mobile device, like you might when using a maps app.

Parameters: An array of dictionaries that defines which action to simulate and any coordinates required by that action. Commands that work in touchAction dictionaries are: longPress, moveTo, press, wait. You can also set a duration for the touch action.

Syntax:

touchAction ([(command: (parameters))])
ClosedReading Syntax Definitions

Syntax definitions for language elements follow these formatting guidelines:

  • boldface: Indicates words and characters that must be typed exactly
  • italic: Indicates expressions or other variable elements
  • {} (curly braces): Indicate optional elements.
  • [] (square brackets) separated by | (vertical pipes): Indicate alternative options where one or the other can be used, but not both.

Example syntax:

In this example, "open file" is required and must be typed exactly. "fileName" is a variable element; it is the path to and name of the file being opened. The following expression is optional and indicates why the file is being opened. If this expression is added, "for" is required and must be typed exactly. One of the following must be included, but only one, and they also must be typed exactly: "reading", "writing", "readwrite", "appending", or "updating".

open file fileName { for [reading | writing | readwrite | appending | updating] }
Note: SenseTalk is not case-sensitive.

Example:

touchAction( [ (longPress: (x: 500, y: 500)), (moveTo: (x: 500, y: 250)) ] )

Example:

touchAction( [(longPress:(x:250,y:500)),(moveTo:(x:500,y:250)),(duration:2)] ) // Gives the dragging action between the two points a duration of two seconds

 

This topic was last updated on August 19, 2021, at 03:30:51 PM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2022 Eggplant