WebDriver Actions

When writing SenseTalk scripts for testing based on Selenium WebDriver connections, you use WebDriver actions to connect to web browsers or mobile devices, navigate through the pages or mobile apps included in your tests, and perform actions on these pages or apps. SenseTalk includes several commands and functions that let you perform such actions on the web pages being tested.

WebDriver Connections

To use WebDriver actions, you must create an active connection to a web browser. The type of the connection depends on whether you plan to self-host your browsers on your IT infrastructure or whether you plan to use Sauce Labs browser-as-a-service infrastructure.

If you plan to self-host your browsers, you need to use Eggplant Functional's explicit WebDriver connection. A WebDriver connection is similar to the VNC or RDP connection you use for image-based scripting with Eggplant Functional. There are several ways to create a WebDriver connection:

• Use the WebConnect Command.
• Use the WebDriver Function.
• Configure a WebDriver connection through the Connection List in Eggplant Functional.

If you plan to utilize Sauce Labs connections, you should understand that a single Sauce Labs connection logically exposes both a VNC connection and a WebDriver connection. The WebDriver connection is created automatically when the Sauce Labs connection is created and it cannot be managed independently of the VNC connection. Hence, the WebConnect command cannot be used to manage a Sauce Labs connection.

There are several ways to create a Sauce Labs connection:

• Use the Connect Command.
• Configure a the connection through the Connection List in Eggplant Functional.

Once you have a Sauce Labs connection, you can send the Sauce Labs connection WebDriver commands using the exact same syntax as you would for an explicit WebDriver connection.

WebDriverConnection Object Properties

When you create a connection to a web browser by using one of the above approaches, SenseTalk creates a WebDriverConnection object that has a number of properties that provide information about the connection. The following list shows the WebDriverConnection object properties:

• url: The URL of the page that is currently displayed in the browser. Setting the URL property of a WebDriverConnection object tells the browser to navigate to the specified URL.

• title: The title (i.e., the value of the Title tag) of the page that is currently displayed in the browser. You cannot change this property.

• pageSource: The entire HTML source of the page that is currently displayed in the browser. You cannot change this property.

• alertText: The text of an alert message, if any, that is currently displayed in the browser. You cannot change this property.

• activeElement: This property is a WebElement object for the active element in the browser. For information about the properties that might be returned, see WebElement Objects. You cannot change this property.

• cookies: A list of all the cookies associated with the page that is currently displayed in the browser. Each cookie is a property list that includes name, value, and other properties associated with the cookie.

  You can review the cookies contained in the property:

    put the webdriver's cookies // Displays all the cookies
    put each item of the webdriver's cookies whose domain is ".testplant.com" // Displays only the specified cookies

  You can add cookies to the list. When adding cookies, you must provide a name and value:

    insert (Name:"addition1", value:"my secret stuff") into the webdriver's cookies

  You can delete cookies from the list:

    set the webdriver's cookies to each item of the webdriver's cookies whose domain is not ".testplant.com" // Deletes cookies with a domain other than .testplant.com
    set the webdriver's cookies to empty // Deletes all cookies

• windowHandle: This property is a unique identifier for the current browser window. When the browser has more than one window, you can set the windowHandle property to a different value to switch the window focus.

• allWindowHandles: This list shows a unique windowHandle identifier for each of the windows that are open in the browser. Use these identifiers to set the windowHandle property to switch focus to a different window. You cannot change this property.

• windowRectangle (or windowRect): The rectangle (x1, y1, x2, y2) of the current browser window. Setting the windowRectangle property changes the size and location of the window.

• windowSize: The size (width, height) of the current browser window. Setting the windowSize property changes the size of the window. You can change the browser window size by setting the width and height or by using max to maximize the browser size.

    set the webdriver's windowsize to "500, 1000"
    set the webdriver's windowsize to "max"

• windowOrigin (or windowLocation): The coordinates (x, y) of the origin (top-left corner) of the current browser window. Setting the windowOrigin property changes the location of the window on the screen.

• geoLocation: A property list with latitude, longitude, and optional altitude properties that represent the geolocation of the browser. For example:

    (altitude:"value", latitude:"value", longitude:"value")

  You can use this property to set the browser's geolocation:

    set the webdriver's geoLocation to (altitude: 42,latitude:33.8099601,longitude:-117.91554840000003)

  Note that not all websites leverage browser geolocation for localization.

• capabilities: A property list of the specific capabilities available through this WebDriver connection. You cannot change the values contained in this property list.

  先端

  Although you can request desired capabilities through the WebConnect command or WebDriver() function when initially opening a connection, the browser might not honor such requests. Therefore, it can be useful to request the Capabilities property list after you establish the connection if you need to be certain of the actual capabilities:

    log the webdriver's capabilities

• name: The user-assigned name of this WebDriver connection. You can specify this value when creating a WebDriver connection through the Connection List, or by using the name property when using the WebConnect command or the WebDriver function to open a connection. You cannot change this property after opening the WebDriver connection.

• browser: The browser name you specify when creating a WebDriver connection through the Connection List, or with the browser property when using the WebConnect command or the WebDriver function to open a WebDriver connection. You cannot change this property after opening the WebDriver connection.

• host: The host machine where the WebDriver server is running. You cannot change this property.

• port: The number of the port on which this WebDriver connection is communicating with the server. You cannot change this property.

WebConnect Command

ノート

This code definition explains the use of the WebConnect command for use with browsers. For information about using this command for mobile, see .WebDriver Commands and Functions for Mobile Device Testing.

ノート

If you are trying to set up a connection to a Sauce Labs browser to use for WebDriver testing, you must use the Connect Command.

When a connection is made to Sauce Labs through Eggplant functional, the Connect command establishes both a VNC connection and a WebDriver connection. You can send WebDriver commands directly to the Sauce Labs connection just as you would an explicit WebDriver connection.

Behavior: This command makes a connection to a web browser. You specify the connection by providing a server's IP address (host) and browser name (browser), or you can call a defined WebDriver connection by name from the Eggplant Functional Connection List. If Selenium is using a non-standard port, the port must be specified as well.

If there is no matching entry in the Connection List when you run the WebConnect command, Eggplant Functional adds a temporary entry to the Connection List for the connection. If a connection to that browser is already open, it is made the active WebDriver connection.

Parameters: The WebConnect command can take the following parameters:

• browser: Required. The name of the browser you want to connect to. This parameter is not required when using WebConnect for mobile testing.

ノート

You can use any browser supported by Selenium Server 2.0. Typically, you need to install a driver for each browser type you want to use. See Selenium WebDriver Testing with Eggplant Functional for information about installing the Selenium server and browser drivers.

• host: Required. A server's IP address or hostname, or the name of a WebDriver connection from the Eggplant Functional Connection List. If no host is specified, the command attempts to connect to the same host as the current VNC or RDP SUT connection. If no SUT connection is available, the command fails without a specified host.

• url: Optional. A URL for a web page you want to open in the browser.

• port: Optional; defaults to 4444. The port number over which to connect. Must be specified if a different port is being used.

• name: Optional. A name to use for referring to this connection. If specified, this is the name that appears in the Connection List.

• desiredCapabilities: Optional. Takes a property list to request desired capabilities of the WebDriver connection, which can affect the behavior or appearance of the web browser. Capability names that you can specify include but are not limited to: acceptSslCerts, applicationCacheEnabled, browserConnectionEnabled, cssSelectorsEnabled, databaseEnabled, handlesAlerts, javascriptEnabled, locationContextEnabled, nativeEvents, rotatable, takesScreenShot, and webStorageEnabled.

  Any of the desired capabilities values can be set as a Boolean, true/false, and you can include as many of them as you need. However, the WebDriver might not respect a given request. The capabilities supported depend on the driver and browser being used.

ノート

** If connecting to Selenium servers in SauceLabs environments,the username and accessKey are required. Pass the username and accessKey as desiredCapabilities, like this: desiredCapabilities: {username:"sauce_username", accessKey:"sauce_accessKey"}

(Alternately, Eggplant recommends that you utilize an explicit Sauce Labs connection, introduced in Eggplant Functional version 22.3, to get a webdriver connection to Sauce Labs. Eggplant Functional is able to store Sauce Labs credentials securely, providing enhanced security over using Capabilities. Please refer to the documentation for the Connect Command for more information on creating Sauce Labs connections via SenseTalk.)

Syntax:
WebConnect connectionProperties

connectionProperties can include: browser:browserName, {host:hostAddress,} {port:portName,} {url:pageURL,} {name:connectionName,} {desiredCapabilities:{capabilitiesPropertyList}}

ノート

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:"192.168.199.132", browser: "chrome", port: "4444", name: "Connection2", url: "http://testplant.com"

Example:

WebConnect "WindowsChrome" // Connects to a pre-configured WebDriver connection named 'WindowsChrome' in the Connection List

Example:

WebConnect host: "localhost", browser: "chrome", desiredCapabilities: (webStorageEnabled: YES, javascriptEnabled: YES, cssSelectorsEnabled: YES) // Uses the desiredCapabilities property to request specific capabilities from the WebDriver connection

Example:

set BrowserFeatures to (webStorageEnabled: YES, javascriptEnabled: YES, cssSelectorsEnabled: YES) // Puts the property list for desired capabilites into a variable
WebConnect host: "localhost", browser: "chrome", desiredCapabilities: BrowserFeatures // Uses the variable to set the desiredCapabilities property

Related:

• WebDriver Function
• WebDisconnect Command
• OpenWebConnections Function

WebDisconnect Command

ノート

This code definition explains the use of the WebDisconnect command for use with browsers. For information about using this command for mobile, see .WebDriver Commands and Functions for Mobile Device Testing.

Behavior: This command disconnects the specified WebDriver connection.

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 {webDriverName | All}

Example:

WebDisconnect // Disconnects the active WebDriver connection

Example:

WebDisconnect All // Disconnects all WebDriver connections

Example:

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

Related:

• WebConnect Command
• WebDriver Function
• OpenWebConnections Function

WebDriver Function

ノート

This code definition explains the use of the WebDriver function for use with browsers. For information about using this command for mobile, see .WebDriver Commands and Functions for Mobile Device Testing.

Behavior: This function returns the WebDriverConnection object. You can use WebDriver to access or set properties of the object. 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 as the WebConnect command.

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

• host: A server's IP address or hostname, or the name of a WebDriver connection from the Eggplant Functional Connection List. The host property is typically required. However, if you do not specify a host, the function attempts to connect to the same host as the current VNC or RDP SUT connection. If no SUT connection is available, the function fails without a specified host.

• browser: Required for web browser testing. The name of the browser you want to connect to. This parameter is not required for mobile testing.

• url: Optional. A URL for a web page you want to open in the browser.

• port: Optional; defaults to 4444. The port number over which to connect.

• name: Optional. A name to use for referring to this connection. If specified, this is the name that appears in the Connection List.

• desiredCapabilities: Optional. Takes a property list to request desired capabilities of the WebDriver connection, which can affect the behavior or appearance of the web browser. The available values are as follows: acceptSslCerts, applicationCacheEnabled, browserConnectionEnabled, cssSelectorsEnabled, databaseEnabled, handlesAlerts, javascriptEnabled, locationContextEnabled, nativeEvents, rotatable, takesScreenShot, and webStorageEnabled.

  Any of the desired capabilities values can be set as a Boolean, true/false, and you can include as many of them as you need. However, the WebDriver might not respect a given request.

• platformName: Required for all mobile testing. The operating system of the mobile device.

• bundleId: iOS only. Required. The identifier of the mobile app you want to open and test.

• device: Android only. Required. The ID number of the device. This can be found by entering adb device list in the command line.

• appPackage: Android only. Required. The identifier of the mobile app you want to open and test.

• appActivity: Android only. Required. The screen in the app that you want the app to open on.

• automationName: Android only. Required. The automation engine to use for testing the device.

Syntax:
WebDriver( {connectionProperties} )

Returns: If you call the WebDriver() function without parameters, it returns the WebDriverConnection object of the active WebDriver connection, or it returns no information if there is no active 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 the active WebDriverConnection object

Example:

put webDriver(host:"192.168.120.128",browser:"chrome") // Creates and returns a WebDriverConnection object with the specified properties

Example:

put WebDriver() into driver // If there is an active WebDriver connection, stores its object in variable 'driver'

Example:

set driver to WebDriver() // If there is an active WebDriver connection, stores its object in variable 'driver'

Example:

set driver to WebDriver(host:"192.168.199.132", browser: "chrome", name: "Connection2") //Creates a new WebDriverConnection object using the specified properties and stores the resulting object in variable 'driver'

Example:

log the WebDriver's activeElement's name // Logs the name attribute of the active element's WebElement object, if the name attribute is available

Example:

webconnect "WindowsChrome"
set the WebDriver's windowsize to "max"
set the WebDriver's url to "https://www.chase.com"
assert that the webdriver's title contains "Credit Card, Mortgage, Auto, Banking Services"
waitFor 20, "WelcomeMessage" // Uses an image search through a VNC or RDP connection to verify that the image appears on the screen

Example:

set the WebDriver's geoLocation to (latitude:42.9634,longitude:-85.6681)
set the WebDriver's url to "http://www.weather.com"
Click (WebXPath:"//span[@class='icon icon-font iconset-ui icon-settings']")
ExecuteJavaScript "scroll(0,400)" // Scrolling down the page is necessary on this website to force some objects to become accessible in the DOM
WaitFor 20, (WebXPath:"//strong[@data-ng-bind='vm.formatLocationName(location)']")
assert that the FoundWebElement's text is "Grand Rapids, MI"

Example:

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

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

Related:

• WebConnect Command
• WebDisconnect Command
• OpenWebConnections Function

GoBack Command

Behavior: This command tells the browser to navigate back through its history to the previous page.

Parameters: An optional WebDriver connection. The GoBack command defaults to the active connection. Include the WebDriver connection parameter to switch to a different connection. You can specify the connection by name as it appears in the Eggplant Functional Connection List or by IP address or hostname.

Syntax:
goBack {webDriverConnection}

Example:

goBack // The GoBack command is typically used on an active connection.

Example:

goBack "WindowsChrome" // This example shows that you can optionally provide a WebDriver connection.

GoForward Command

Behavior: This command tells the browser to navigate forward through its history to the next page.

Parameters: An optional WebDriver connection. The GoForward command defaults to the active connection. Include the WebDriver connection parameter to switch to a different connection. You can specify the connection by name as it appears in the Eggplant Functional Connection List or by IP address or hostname.

Syntax:
goForward {webDriverConnection}

Example:

goForward // The GoForward command is typically used on an active connection.

Example:

goForward "WindowsChrome" // This example shows that you can optionally provide a WebDriver connection.

Refresh Command

Behavior: This command tells the browser to reload the current page.

Parameters: An optional WebDriver connection. The Refresh command defaults to the active connection. Include the WebDriver connection parameter to switch to a different connection. You can specify the connection by name as it appears in the Eggplant Functional Connection List or by IP address or hostname.

Syntax:
Refresh {webDriverConnection}

Example:

Refresh// The Refresh command is typically used on an active connection.

Example:

Refresh "abc" // This example shows that you can optionally provide a WebDriver connection.

Example:

set myOpenConnections to OpenWebConnections() // Stores a list of all open WebDriverConnection objects into variable 'myOpenConnections'
repeat with each myConnection of myOpenConnections // Iterates through each object
  Refresh myConnection // Refresh the associated browser
end repeat

Submit Command

Behavior: This command submits the form containing the specified WebElement, or the active element if none is specified.

ノート

Using the Submit command is generally not recommended because it bypasses any custom JavaScript that might be expected to operate on the form submission. Therefore, as a best practice, you should locate the element that is intended to submit the form (such as a button), then execute a Click command on that element.

Parameters: None, or a WebElement Identifier. If no WebElement is specified, the command operates on the active element.

Syntax:
Submit { identifierType: value }

Example:

Submit // Submits the contents of the active WebElement

Example:

put findElement(webtagname: "textarea") into element // Puts the location of the WebElement into a variable
Sendkeys element, "Fire bad, tree pretty." // Uses the variable to access the WebElement to enter text
Submit element // Uses the variable to access the WebElement to submit the form

SwitchToFrame Command

Behavior: Switches the browser's current context to the indicated frame.

Parameters: A text string identifying a frame. This can be the name or ID value of the frame, it's ordinal number on the page (with 0 indicating the first frame), "parent" for the context that contains the current frame, or "default" (or no parameter) to return to the top-level page context.

Syntax:
SwitchToFrame frameIdentifier

Example:

Log "Switch to the found iframe element Login box and show its input elements"
switchToFrame 0 -- Switch to frame 0
waitFor 20, (webTagName:"input")
put the name of each item of findElements(webTagName:"input") -- Prints the names of all input elements found for the login box

WebScreenshot Command

Behavior: This command takes a screenshot of the browser contents and saves it according to the specified file name or full file path.

Parameters: A required file name which can optionally include the full file path of the desired save location. If WebScreenshot is run as part of a script execution and the given file name is not a full path, the command saves the screenshot in the current script results directory. If no file path is included in the filename parameter and WebScreenshot is run as a selection, the screenshot is saved into the default documents directory.

The WebScreenshot command optionally takes a WebDriverConnection object parameter to switch to a different connection. The command defaults to the active connection.

Syntax:
WebScreenshot {webDriverConnection,} fileName

Example:

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

Example:

WebScreenshot "<path>/myscreenshot" // The WebScreenshot command is typically used on an active connection.

Example:

webScreenshot "C:\Users\Carrie\Desktop\MainPage" // Saves the screenshot onto the Desktop with name 'MainPage'

Example:

WebScreenshot "myWebDriverConnectionName", "<path>/myscreenshot" // This example shows that you can optionally provide a WebDriver connection.

ExecuteJavaScript Command and ExecuteJavaScript Function

Behavior: This command directs the browser to execute the given JavaScript code in the current context.

Parameters: The JavaScript code that you want to execute is the only required parameter. Optionally, you can pass one or more parameter values to the JavaScript. You can also accept any value that is returned by the JavaScript code by putting it into a variable.

The ExecuteJavaScript command optionally takes a WebDriverConnection object parameter to switch to a different connection. The command defaults to the active connection.

Syntax:
ExecuteJavaScript {webDriverName,} javascriptCommands
ExecuteJavaScript({webDriverName,} javaScriptCommands {, optionalParam1, optionalParam2})
ExecuteJavaScript {webDriverConnection,} javascriptCommands
ExecuteJavaScript( {webDriverConnection,} javascriptCommands {, optionalParam1, optionalParam2, ...} )

Example:

ExecuteJavaScript "alert('openConnection')" // Directs the browser to execute the specified JavaScript

Example:

ExecuteJavaScript "Connection2","alert('openConnection')"// Shows that you can optionally provide a WebDriver connection

Example:

ExecuteJavaScript "scroll(0,200)" // Scrolls the browser the specified amount

Example:

put ExecuteJavaScript("return document.getElementsByClassName(arguments[0]);", "gsfi lst-d-f") into myVariable // Passes a single parameter to the JavaScript code, then puts the return value into a variable
put myVariable // Outputs the returned value from the executed JavaScript

Example:

put ExecuteJavaScript("return dataLayer;") into DataLayer
log DataLayer

OpenWebConnections Function

Behavior: This function returns a list of WebDriverConnection objects for all open WebDriver connections.

Parameters: None.

Syntax:
OpenWebConnections()
the OpenWebConnections

Example:

put the openwebconnections

Example:

put the url of each item of OpenWebConnections() // Displays the URL of each open WebDriver connection

Example:

set myOpenConnections to the OpenWebConnections // Stores a list of all open WebDriverConnection objects into variable 'myOpenConnections'
repeat with each myConnection of myOpenConnections // Iterates through each object
  Log myConnection's title // Logs the page title
end repeat

Related:

• WebConnect Command
• WebDriver Function
• WebDisconnect Command