com.ibm.team.fvt.tests.web
Class WebBrowserElement

java.lang.Object
  extended by com.ibm.team.fvt.tests.web.WebBrowserElement
All Implemented Interfaces:
org.openqa.selenium.internal.Locatable, org.openqa.selenium.SearchContext, org.openqa.selenium.WebElement

public class WebBrowserElement
extends java.lang.Object
implements org.openqa.selenium.WebElement, org.openqa.selenium.internal.Locatable

A web browser element found in a WebBrowser page content.

This class implements the WebElement interface to be as most compatible as possible with Selenium behavior.

This object is instantiated while finding element through SearchContext interface. As WebBrowser and WebBrowserElement implement this interface, they only produce this kind of object when finding element in the current web page content.

The main functionality of this specific web element is to be able to self recover when a StaleElementReferenceException occurs while trying to execute any of the WebElement interface operations.

The recovery uses the stored context from which the initial WebElement has been found and the mechanism to find it (ie. By). When an exception occurs, it's caught and the element is searched again (ie. SearchContext.findElement(By) or SearchContext.findElements(By)).

This recovery is retried several times before given up if maximum of retries (MAX_RECOVERY_ATTEMPTS) is reached.

When searching the web element for the first time, the browser, the frame and the index of the elements in the parent's list are also stored to have the precise context used for the initial research and then be sure to find the same element when recovering.

Additionally to the WebElement methods, this class also provide some useful functionalities as:


Field Summary
static int MAX_RECOVERY_ATTEMPTS
          The maximum of attempts when recovering the current web element.
 
Constructor Summary
WebBrowserElement(WebBrowser browser, org.openqa.selenium.SearchContext context, org.openqa.selenium.By by)
          Create a web browser element using the given search mechanism in the given search context.
WebBrowserElement(WebBrowser browser, WebBrowserFrame webFrame, org.openqa.selenium.SearchContext context, org.openqa.selenium.By by)
          Create a web browser element using the given search mechanism in the given search context and frame.
WebBrowserElement(WebBrowser browser, WebBrowserFrame webFrame, org.openqa.selenium.SearchContext context, org.openqa.selenium.By by, org.openqa.selenium.WebElement element, int size, int index)
          Create a web browser element using the given search mechanism in the given search context.
 
Method Summary
 void clear()
          
 void click()
          
 void click(boolean recovery)
          Perform the WebElement.click() operation.
 java.lang.Object executeScript(java.lang.String script)
          Execute the given script on the current web element.
 WebBrowserElement findElement(org.openqa.selenium.By findBy)
          
 WebBrowserElement findElement(org.openqa.selenium.By findBy, boolean recovery)
          Perform the WebElement.findElement(By) operation.
 WebBrowserElement findElement(org.openqa.selenium.By findBy, WebBrowserFrame webFrame, boolean recovery)
          Perform the WebElement.findElement(By) operation.
 java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy)
          
 java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy, boolean recovery)
          Perform the WebElement.findElements(By) operation.
 java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy, boolean displayed, boolean recovery)
          Perform the WebElement.findElements(By) operation.
 WebBrowserElement getAncestor(int depth)
          Return the ancestor of the current element.
 java.lang.String getAttribute(java.lang.String name)
          
 org.openqa.selenium.By getBy()
          Return the search mechanism to find the current element.
 java.util.List<WebBrowserElement> getChildren()
          Return all children of the current element.
 java.util.List<WebBrowserElement> getChildren(java.lang.String tag)
          Return specific children of the current element.
 org.openqa.selenium.interactions.internal.Coordinates getCoordinates()
          
 java.lang.String getCssValue(java.lang.String propertyName)
          
 WebBrowserFrame getFrame()
          Return the element frame.
 java.lang.String getFullPath()
          Return the full xpath for the current element.
static java.util.List<WebBrowserElement> getList(java.util.List<org.openqa.selenium.WebElement> elements)
          Return a list of WebBrowserElement assuming the given list *is* a list of this kind of WebElement.
 org.openqa.selenium.Point getLocation()
          
 org.openqa.selenium.Point getLocationOnScreenOnceScrolledIntoView()
          Deprecated. Use getCoordinates() instead.
 WebBrowserElement getParent()
          Return the parent of the current element.
 org.openqa.selenium.Dimension getSize()
          
 java.lang.String getTagName()
          
 java.lang.String getText()
          
 java.lang.String getText(boolean recovery)
          Perform the WebElement.getText() operation.
 org.openqa.selenium.WebElement getWebElement()
          Return the wrapped WebElement.
 boolean isDisplayed()
          
 boolean isDisplayed(boolean recovery)
          Perform the WebElement.isDisplayed() operation.
 boolean isEnabled()
          
 boolean isEnabled(boolean recovery)
          Perform the WebElement.isEnabled() operation.
 boolean isSelected()
          
 void sendKeys(java.lang.CharSequence... keysToSend)
          
 void submit()
          
 java.lang.String toString()
           
 WebBrowserElement waitForElement(org.openqa.selenium.By[] findBys, int timeout)
          Wait until have found one of element using the given search mechanisms.
 WebBrowserElement waitForElement(org.openqa.selenium.By findBy, int timeout)
          Wait until have found the element using given search mechanism.
 WebBrowserElement waitForElement(org.openqa.selenium.By findBy, int timeout, boolean displayed, boolean single)
          Wait until have found the element using given search mechanism.
 java.util.List<WebBrowserElement> waitForElements(org.openqa.selenium.By findBy, int timeout)
          Wait until have found at least one element using the given search mechanism.
 java.util.List<WebBrowserElement> waitForElements(org.openqa.selenium.By findBy, int timeout, boolean displayed)
          Wait until have found at least one element using the given search mechanism.
 boolean waitWhileDisplayed(int seconds)
          Wait while the current web element is displayed in the page.
 boolean waitWhileDisplayed(int seconds, boolean fail)
          Wait while the current web element is displayed in the page.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MAX_RECOVERY_ATTEMPTS

public static final int MAX_RECOVERY_ATTEMPTS
The maximum of attempts when recovering the current web element.

See Also:
Constant Field Values
Constructor Detail

WebBrowserElement

public WebBrowserElement(WebBrowser browser,
                         WebBrowserFrame webFrame,
                         org.openqa.selenium.SearchContext context,
                         org.openqa.selenium.By by)
Create a web browser element using the given search mechanism in the given search context and frame.

The browser is stored to allow recovery.

Note that this constructor is typically used when search for a single element.

Parameters:
browser - The browser where web element is displayed.
webFrame - The frame in which the element is supposed to be
context - The context to search for the element
by - The mechanism to use to search for the element

WebBrowserElement

public WebBrowserElement(WebBrowser browser,
                         WebBrowserFrame webFrame,
                         org.openqa.selenium.SearchContext context,
                         org.openqa.selenium.By by,
                         org.openqa.selenium.WebElement element,
                         int size,
                         int index)
Create a web browser element using the given search mechanism in the given search context.

The browser is stored to allow recovery.

Note that this constructor is typically used when search for a single element.

Parameters:
browser - The browser where web element is displayed.
webFrame - The index of the frame in which the element is supposed to be
context - The context to search for the element
by - The mechanism to use to search for the element
element - The element wrapped by the created instance. If this argument is used, then the search mechanism will be ignored.
size - The size of the parent element children list. This argument is used when searching for several element (see findElements(By, boolean, boolean))
index - The index in the parent element children list. This argument is used when searching for several element (see findElements(By, boolean, boolean))

WebBrowserElement

public WebBrowserElement(WebBrowser browser,
                         org.openqa.selenium.SearchContext context,
                         org.openqa.selenium.By by)
Create a web browser element using the given search mechanism in the given search context.

The browser is stored to allow recovery.

Note that this constructor is typically used when search for a single element.

Parameters:
browser - The browser where web element is displayed.
context - The context to search for the element
by - The mechanism to use to search for the element
Method Detail

getList

public static java.util.List<WebBrowserElement> getList(java.util.List<org.openqa.selenium.WebElement> elements)
Return a list of WebBrowserElement assuming the given list *is* a list of this kind of WebElement.

Parameters:
elements - The list of WebElement.
Returns:
The list of WebBrowserElement.
Throws:
java.lang.IllegalArgumentException - If one of the element of the given list is not a WebBrowserElement.

clear

public void clear()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
clear in interface org.openqa.selenium.WebElement

click

public void click()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
click in interface org.openqa.selenium.WebElement

click

public void click(boolean recovery)
Perform the WebElement.click() operation.

If recovery is allowed, then catch any WebDriverException (except InvalidSelectorException and UnreachableBrowserException) and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Parameters:
recovery - Tells whether try to recover is a WebDriverException occurs
See Also:
WebElement.click()

executeScript

public java.lang.Object executeScript(java.lang.String script)
Execute the given script on the current web element.

Parameters:
script - The script to execute
Returns:
One of Boolean, Long, String, List or WebElement. Or null.

findElement

public WebBrowserElement findElement(org.openqa.selenium.By findBy)

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

The search is performed in the current frame.

Specified by:
findElement in interface org.openqa.selenium.SearchContext
Specified by:
findElement in interface org.openqa.selenium.WebElement

findElement

public WebBrowserElement findElement(org.openqa.selenium.By findBy,
                                     boolean recovery)
Perform the WebElement.findElement(By) operation.

If recovery is allowed, then catch any WebDriverException (except InvalidSelectorException and UnreachableBrowserException) and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

The search is performed in the current frame.

Parameters:
recovery - Tells whether try to recover is a WebDriverException occurs
See Also:
WebElement.findElement(By)

findElement

public WebBrowserElement findElement(org.openqa.selenium.By findBy,
                                     WebBrowserFrame webFrame,
                                     boolean recovery)
Perform the WebElement.findElement(By) operation.

If recovery is allowed, then catch any WebDriverException (except InvalidSelectorException and UnreachableBrowserException) and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

If recovery is not allowed and an exception occurred, then it's still caught but null is returned instead of retrying.

The search is performed in the current frame.

Parameters:
recovery - Tells whether try to recover is a WebDriverException occurs
See Also:
TODO Add the ability not to throw {@link ScenarioFailedError} when not found (ie. add fail argument..)

findElements

public java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy)

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
findElements in interface org.openqa.selenium.SearchContext
Specified by:
findElements in interface org.openqa.selenium.WebElement

findElements

public java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy,
                                                                   boolean recovery)
Perform the WebElement.findElements(By) operation.

If recovery is allowed, then catch any WebDriverException (except InvalidSelectorException and UnreachableBrowserException) and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

If recovery is not allowed and an exception occurs, then it's still caught but an empty list is returned instead of retrying.

Note that only displayed elements are added to the returned list.

Parameters:
recovery - Tells whether try to recover is a WebDriverException occurs
See Also:
WebElement.findElements(By)

findElements

public java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy,
                                                                   boolean displayed,
                                                                   boolean recovery)
Perform the WebElement.findElements(By) operation.

If recovery is allowed, then catch any WebDriverException (except InvalidSelectorException and UnreachableBrowserException) and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

If recovery is not allowed and an exception occurs, then it's still caught but an empty list is returned instead of retrying.

Parameters:
displayed - Tells whether the element needs to be displayed or not
recovery - Tells whether try to recover is a WebDriverException occurs
See Also:
WebElement.findElements(By)

getAncestor

public WebBrowserElement getAncestor(int depth)
Return the ancestor of the current element.

Parameters:
depth - The depth in the ancestor hierarchy. Must be positive, if 0 then return the current instance.
Returns:
The web element ancestor as a WebBrowserElement.

getAttribute

public java.lang.String getAttribute(java.lang.String name)

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
getAttribute in interface org.openqa.selenium.WebElement

getBy

public org.openqa.selenium.By getBy()
Return the search mechanism to find the current element.

Returns:
The search mechanism as a By.

getChildren

public java.util.List<WebBrowserElement> getChildren()
Return all children of the current element.

Returns:
The list of web element children as a List of WebBrowserElement.

getChildren

public java.util.List<WebBrowserElement> getChildren(java.lang.String tag)
Return specific children of the current element.

Returns:
The list of web element children as a List of WebBrowserElement.

getCoordinates

public org.openqa.selenium.interactions.internal.Coordinates getCoordinates()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
getCoordinates in interface org.openqa.selenium.internal.Locatable

getCssValue

public java.lang.String getCssValue(java.lang.String propertyName)

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
getCssValue in interface org.openqa.selenium.WebElement

getFrame

public WebBrowserFrame getFrame()
Return the element frame.

Returns:
The frame as a WebBrowserFrame.

getFullPath

public java.lang.String getFullPath()
Return the full xpath for the current element.

Returns:
The full xpath as a String or null if the search mechanism was not found By.ByXPath one.

getLocation

public org.openqa.selenium.Point getLocation()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
getLocation in interface org.openqa.selenium.WebElement

getLocationOnScreenOnceScrolledIntoView

@Deprecated
public org.openqa.selenium.Point getLocationOnScreenOnceScrolledIntoView()
Deprecated. Use getCoordinates() instead.

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
getLocationOnScreenOnceScrolledIntoView in interface org.openqa.selenium.internal.Locatable

getParent

public WebBrowserElement getParent()
Return the parent of the current element.

Returns:
The web element parent as a WebBrowserElement.

getSize

public org.openqa.selenium.Dimension getSize()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
getSize in interface org.openqa.selenium.WebElement

getTagName

public java.lang.String getTagName()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
getTagName in interface org.openqa.selenium.WebElement

getText

public java.lang.String getText()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
getText in interface org.openqa.selenium.WebElement

getText

public java.lang.String getText(boolean recovery)
Perform the WebElement.getText() operation.

If recovery is allowed, then catch any WebDriverException (except InvalidSelectorException and UnreachableBrowserException) and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made. In the latter case, no exception is raised, but an empty string is returned.

If recovery is not allowed and an exception occurs, then it's still caught but an empty string is returned instead of retrying.

Parameters:
recovery - Tells whether try to recover is a WebDriverException occurs
See Also:
WebElement.getText()

getWebElement

public org.openqa.selenium.WebElement getWebElement()
Return the wrapped WebElement.

Returns:
The wrapped web element as a WebElement.

isDisplayed

public boolean isDisplayed()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
isDisplayed in interface org.openqa.selenium.WebElement

isDisplayed

public boolean isDisplayed(boolean recovery)
Perform the WebElement.isDisplayed() operation.

If recovery is allowed, then catch any WebDriverException (except InvalidSelectorException and UnreachableBrowserException) and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made. In the latter case, no exception is raised, but an false is returned.

If recovery is not allowed and an exception occurs, then it's still caught but false is returned instead of retrying.

Parameters:
recovery - Tells whether try to recover is a WebDriverException occurs
See Also:
WebElement.isDisplayed()

isEnabled

public boolean isEnabled()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
isEnabled in interface org.openqa.selenium.WebElement

isEnabled

public boolean isEnabled(boolean recovery)
Perform the WebElement.isEnabled() operation.

If recovery is allowed, then catch any WebDriverException (except InvalidSelectorException and UnreachableBrowserException) and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made. In the latter case, no exception is raised, but a false is returned.

If recovery is not allowed and an exception occurs, then it's still caught but false is returned instead of retrying.

Parameters:
recovery - Tells whether try to recover if a WebDriverException occurs
See Also:
WebElement.isEnabled()

isSelected

public boolean isSelected()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
isSelected in interface org.openqa.selenium.WebElement

sendKeys

public void sendKeys(java.lang.CharSequence... keysToSend)

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
sendKeys in interface org.openqa.selenium.WebElement

submit

public void submit()

Catch WebDriverException and retry the operation until success or MAX_RECOVERY_ATTEMPTS attempts has been made.

Specified by:
submit in interface org.openqa.selenium.WebElement

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

waitForElement

public WebBrowserElement waitForElement(org.openqa.selenium.By findBy,
                                        int timeout)
Wait until have found the element using given search mechanism.

Note that hidden element are not returneded by this method.

Parameters:
findBy - Mechanism to find the element in the current page.
timeout - The time to wait before giving up the research
Returns:
The web element as WebBrowserElement or null if no element was found before the timeout
Throws:
ScenarioFailedError - If there are several found elements although only one was expected.

waitForElement

public WebBrowserElement waitForElement(org.openqa.selenium.By findBy,
                                        int timeout,
                                        boolean displayed,
                                        boolean single)
Wait until have found the element using given search mechanism.

Parameters:
findBy - Mechanism to find the element in the current page.
timeout - The time to wait before giving up the research
displayed - Tells whether the element needs to be displayed or not
single - Tells whether a single element is expected
Returns:
The web element as WebBrowserElement or null if no element was found before the timeout
Throws:
ScenarioFailedError - If there are several found elements although only one was expected.

waitForElements

public java.util.List<WebBrowserElement> waitForElements(org.openqa.selenium.By findBy,
                                                         int timeout)
Wait until have found at least one element using the given search mechanism.

Only displayed element are return by this method.

Parameters:
findBy - The mechanism to find the element
timeout - The time in seconds before giving up if the element is not found
Returns:
A List of web element as WebBrowserElement. Might be empty if no element was found before the timeout

waitForElements

public java.util.List<WebBrowserElement> waitForElements(org.openqa.selenium.By findBy,
                                                         int timeout,
                                                         boolean displayed)
Wait until have found at least one element using the given search mechanism.

Parameters:
findBy - The mechanism to find the element
timeout - The time in seconds before giving up if the element is not found
displayed - Tells whether the element needs to be displayed or not
Returns:
A List of web element as WebBrowserElement. Might be empty if no element was found before the timeout

waitForElement

public WebBrowserElement waitForElement(org.openqa.selenium.By[] findBys,
                                        int timeout)
Wait until have found one of element using the given search mechanisms.

Fail if:


waitWhileDisplayed

public boolean waitWhileDisplayed(int seconds)
Wait while the current web element is displayed in the page.

Parameters:
seconds - The timeout before giving up if the element is still displayed.
Throws:
WaitElementTimeoutError - If the element is still displayed after the given timeout has been reached.

waitWhileDisplayed

public boolean waitWhileDisplayed(int seconds,
                                  boolean fail)
Wait while the current web element is displayed in the page.

Parameters:
seconds - The timeout before giving up if the element is still displayed.
fail - Tells whether to return false instead throwing a WaitElementTimeoutError when the timeout is reached.
Returns:
true if the element has disappeared before the timeout is reached. Otherwise return false only if it has been asked not to fail.
Throws:
WaitElementTimeoutError - If the element is still displayed after the given timeout has been reached and it has been asked to fail.