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
orFalse
to indicate whether the element is selected in the browser. - isEnabled: Returns
True
orFalse
to indicate whether the element is enabled in the browser. - isDisplayed: Returns
True
orFalse
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: valueFunction 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.