Finding WebElements

When writing SenseTalk scripts for testing based on Selenium WebDriver connections, much of your effort is likely to be based around interacting with various HTML elements in the Document Object Model (DOM) of the pages you're testing. These elements in the DOM are often referred to as WebElement objects.

SenseTalk includes several commands and functions that provide you with different ways to locate WebElements within your pages so that you can take some action, find information, or perform verification against those elements.

WebElement Identifiers

To access a WebElement within the DOM, such as when using the FindElement() function or the Click command with a WebDriver connection, you have several ways to specify the element you want to interact with. The following WebElement Identifiers can be used to locate elements in the DOM:

• 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.
• webTagName: Use this property to locate an element whose HTML tag is equal to the given value.
• webClassName: Use this property to locate an element by the value of its Class attribute.
• webLinkText: Use this property to locate a link whose text is equal to the indicated value.
• webPartialLinkText: Use this property to locate a link whose text contains the indicated value.
• webCssSelector: Use this property to locate an element using the indicated CSS selector expression.
• 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.

WebElement Objects

A successful WebElement search creates a WebElement object. The object contains a property list with information about the element that was found. A WebElement object can include any properties from the following list, but not all properties will necessarily return values. The specific WebElement type determines which properties have useful values.

• Text: The visible text contained in the element that is displayed in the browser.
• tagName: The HTML tag name of the element.
• Name: The value of the Name attribute of the element.
• ID: The value of the ID attribute of the element.
• Class: The value of the Class attribute of the element.
• Attribute(): Returns the value of a specific attribute of the element, or is empty if that attribute is not present.
• isSelected: Returns True or False to indicate whether the element is selected in the browser.
• isEnabled: Returns True or False to indicate whether the element is enabled in the browser.
• isDisplayed: Returns True or False to indicate whether the element is displayed in the browser.
• Origin: Returns a webLocation property list of the element's origin (top left corner) within the page. For example:

    (objectType:"webLocation", x:"262", y:"323")

• Size: Returns the size (width, height) of the element within the page.
• Rectangle: Returns the rectangle (x1, y1, x2, y2) of the element within the page. Note that these are browser coordinates, not screen coordinates.
• cssProperty: Returns the value of the specified CSS property of the element.
• WebDriver: Returns the WebDriverConnection object for the WebDriver connection containing the element.
• WebContext: Returns either the WebDriverConnection object for the WebDriver connection containing the element, or the WebElement object within which the given element was found.

WebElement objects can display in either long or short formats when they are called, i.e., in the results log of a run. The long format is the default, and automatically displays the values of several properties. Note that the long format requires additional requests to the WebDriver server each time the WebElement object displays.

Change the webElementDisplay global property to short to display WebElements using the short format. Note that if an element is not available in the current page context, the WebElement object displays in short format even if the WebElementDisplay is set to long.

FindElement, FindElements Commands and Functions

Behavior: FindElement can be called as either a command or a function. It locates a specific element within a page or within another element. You can call FindElement on either the WebDriverConnection object or on a WebElement object that has been returned by an earlier call to FindElement or the ActiveElement property. You also can call FindElement without a reference to a WebDriverConnection object or to a WebElement object; in that case, FindElement uses the active WebDriver connection.

FindElements, either as a command or function, works identically to FindElement, but instead of returning the first matching element, it returns a list containing all matching elements that are found.

When FindElement is called as a command, the variable it is set to the WebElement object—or to a list of WebElement objects, in the case of FindElements.

Parameters: A property list containing an optional WebDriverConnection object and a required WebElement Identifier. If no WebDriverConnection is specified, the active connection is used.

Command Syntax:
FindElement {WebDriver: webDriverName , } IdentifierType: value
FindElements {WebDriver: webDriverName , } IdentifierType: value

Function Syntax:
FindElement( {WebDriver: webDriverName , } IdentifierType: value )
FindElements( {WebDriver: webDriverName , } IdentifierType: value )

Returns: The value returned is a WebElement object for FindElement or a list of WebElement objects for FindElements.

Example:

get FindElement(WebXPath:"//a[@class='search icon-search']") // Locates the first WebElement on the page that matches the specified WebXPath identifier

Example:

get FindElements (WebTagName:"input") // Locates all WebElements on the page that have the HTML tag name 'input'

Example:

FindElement (WebXPath:"//a[@class='search icon-search']") // Locates the first WebElement on the page that matches the specified WebXPath identifier

Example:

FindElements (WebTagName:"input") // Locates all WebElements on the page that have the HTML tag name 'input'

Example:

set NarrowSearch to FindElement(WebID:"narrow-search") // Assigns the WebElement object to variable 'NarrowSearch'

Example:

FindElement (WebXPath:"//a[@class='search icon-search']")
put it into myElement // Stores the found WebElement object into variable 'myElement'

Example:

FindElement (WebLinkText:"Guides and References")
MoveTo it // Scrolls the WebElement object found by FindElement into view in the browser
WaitFor 3, "GuidesandReferences_Link_Highlighted" // Uses an image search to confirm the link text appears as expected and is highlighted
Click it // Clicks the WebElement object

Example:

put FindElement(WebID:"s") into SearchField
assert that SearchField's attribute("placeholder") contains "search" considering case with warning // Performs a case-sensitive validation of whether the placeholder attribute of the found WebElement contains 'search'

Example:

put findelement(webID: "twotabsearchtextbox") into SearchBox
click SearchBox
sendkeys "Roger Rabbit"
submit

Example:

FindElement (WebID:"s")
set SearchField to it // Assigns the WebElement object created by the FindElement() function to variable 'SearchField'
log SearchField's tagName // Logs the HTML tag name of the element. For example 'input'
assert that SearchField's origin's x is less than 100 // Validates that the top left corner of the WebElement object is located less than 100 pixels down the browser's coordinate plane
SendKeys SearchField, "network emulation"

Example:

get FindElements(webTagName:"h3")
log "There are" && the number of items of it && "h3 elements." // Logs a message indicating the number of WebElement objects created by FindElements(). For example: 'There are 6 h3 elements.'

Example:

set elementsList to FindElements(webTagName:"h3") // Stores a list of all located WebElement objects with HTML tag name 'h3'
repeat with each element in elementsList // Iterates through each WebElement object stored in variable 'elementsList'
  if element's text contains "Mummies" then
    MoveTo element // Automatically scrolls the WebElement object that contains text 'Mummies' into view on the browser
    WaitFor 2, "MummiesHeader" // Uses an image search to confirm that the Mummies h3 element looks as expected
    exit repeat
  end if
end repeat

WebElementFound Function

Behavior: Searches for the given WebElement in the DOM. The function returns true if the element is found, and false if the element is not found.

Parameters: A property list that includes a required WebElement Identifier and an optional WaitFor property to set the amount of time to wait for the element to appear.

Syntax:
WebElementFound( identifierType: value {, waitFor: duration} )

Example:

put webElementFound (WebID:"gsri_ok0") // Returns 'true' if the WebElement is found on the page and 'false' if it is not

Example:

put WebElementFound(WebClassName:"bb-nav-touts",waitFor:30) // Spends up to 30 seconds for the WebElement to become available in the DOM. Returns 'true' if the element is available before the timeout and 'false' if it is not.

Example:

if webElementFound(webID:"jkQ") then log "Expected result"

Example:

assert that webElementFound(webLinkText:"Request a demo") // Throws an exception if the web element cannot be found on the page

Example:

if webElementFound(webLinkText:"Request a demo") and imageFound(text:"Request a demo") then // Checks that the link text is present in the DOM and visible on the page
  LogSuccess "'Request a demo' checkpoint has passed. The link text is correct in the DOM and the text appears on the UI."
else
  LogError "'Request a demo' checkpoint has failed."
end if

WaitFor Command

note

This code definition explains the use of the WaitFor command for WebDriver connections. For information about using this command for image-based scripting, see Image and OCR Searches: WaitFor Command.

Behavior: Halts the next line of script execution until the WebElement is found in the DOM. If the element isn't found within the specified wait time, an exception is thrown.

Parameters: A wait time, and one or more WebElement Identifiers. The default unit of wait time is seconds.

Syntax:
WaitFor duration, WebElement

Example:

WaitFor 10, (WebID:"narrow_search") // Waits up to 10 seconds for the specified ID to be available in the DOM

Example:

WaitFor 1 minute, WebLinkText:"Privacy" // Waits up to one minute for the specified link text to be available in the DOM

Example:

WaitFor 10, (WebID:"narrow_search"), (WebID:"twotabsearchtextbox") // Waits up to 10 seconds for either of two specified WebElements to be accessible in the DOM

Example:

WaitFor 10, (WebXPath:"//strong[@data-ng-bin='vm.formatLocationName(location)']"), (image:"LocationBasedHeader") // Waits up to 10 seconds for either the specified WebElement to be accessible in the DOM or for the image to be found on the SUT

FoundWebElement Function

Behavior: This function provides information about the last WebElement found.

Parameters: None; refers to the last WebElement found.

Syntax:
FoundWebElement()
the FoundWebElement

Returns: A WebElement object, which contains a property list with information about the WebElement that was found. Note that not every WebElement type returns a value for every WebElement object property.

Example:

put foundwebelement()

Example:

put the foundWebElement

Example:

set myFoundElement to FoundWebElement()

Example:

WaitFor 10, webName: "q"
put the foundwebelement's tagName // Returns the HTML tag name of the web element. For example: 'input'
put the foundwebelement's class // Returns the class attribute of the web element

Example:

click (WebLinkText:"Gmail",WaitFor:10)
set GmailLink to FoundWebElement()
log GmailLink's tagName // Logs the HTML tag name of the web element. For example: 'a'

Example:

WaitFor 10, (WebID:"twotabsearchtextbox")
log foundwebelement()'s class

Example:

set LinkList to ("About","Store","Gmail","Images")
repeat with each Link of LinkList
  WaitFor 5, WebLinkText:Link // Confirms the expected WebElement is present in the DOM based on its link text
  assert that foundWebElement()'s rectangle's height is 15 with warning // Validates whether the current WebElement object's height is 15 pixels
end repeat

FoundWebLocation Function

Behavior: This function returns information about the WebElement's location in the browser.

Parameters: None; refers to the last WebElement found.

Syntax:
FoundWebLocation()
the FoundWebLocation

Returns: A webLocation property list, which contains objectType, x, and y properties. The objectType is always webLocation, and the x and y properties represent the coordinates of a point on the web page where the WebElement was found. For example:

(objectType:"webLocation", x:"476", y:"83")

Example:

put foundWebLocation()

Example:

put the foundWebLocation

Example:

WaitFor 10, (WebID:"twotabsearchtextbox")
log foundweblocation() // Logs the webLocation property list of the previously found WebElement. For example: '(objectType:"webLocation", x:"463", y:"340")'

Example:

WaitFor 10, webName:"q"
set YCoord to the foundWebLocation's y // Stores the y-coordinate of the browser location of the WebElement in variable 'YCoord'

Example:

If WebElementFound(webName:"q") then // Checks whether the specified WebElement is accessible in the DOM
  Click the foundWebLocation // If the WebElement is accessible, then clicks it
end if