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

java.lang.Object
  extended by com.ibm.team.fvt.tests.web.WebBrowserElement

public class WebBrowserElement
extends java.lang.Object

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, SearchContext context, By by)
          Create a web browser element using the given search mechanism in the given search context.
WebBrowserElement(WebBrowser browser, WebBrowserFrame webFrame, SearchContext context, By by)
          Create a web browser element using the given search mechanism in the given search context and frame.
WebBrowserElement(WebBrowser browser, WebBrowserFrame webFrame, SearchContext context, By by, 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.
 void executeScript(java.lang.String script)
          Execute the given script on the current web element.
 WebBrowserElement findElement(By findBy)
          
 WebBrowserElement findElement(By findBy, boolean recovery)
          Perform the WebElement#findElement(By) operation.
 WebBrowserElement findElement(By findBy, WebBrowserFrame webFrame, boolean recovery)
          Perform the WebElement#findElement(By) operation.
 java.util.List<WebElement> findElements(By findBy)
          
 java.util.List<WebElement> findElements(By findBy, boolean recovery)
          Perform the WebElement#findElements(By) operation.
 java.util.List<WebElement> findElements(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)
          
 By getBy()
          Return the search mechanism to find the current element.
 Coordinates getCoordinates()
          
 java.lang.String getCssValue(java.lang.String propertyName)
          
 WebBrowserFrame getFrame()
          Return the element frame.
 java.lang.String getFullXpath()
          Return the full xpath for the current element.
static java.util.List<WebBrowserElement> getList(java.util.List<WebElement> elements)
          Return a list of WebBrowserElement assuming the given list *is* a list of this kind of WebElement.
 Point getLocation()
          
 Point getLocationOnScreenOnceScrolledIntoView()
          
 WebBrowserElement getParent()
          Return the parent of the current element.
 Dimension getSize()
          
 java.lang.String getTagName()
          
 java.lang.String getText()
          
 java.lang.String getText(boolean recovery)
          Perform the WebElement#getText() operation.
 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(By[] findBys, int timeout)
          Wait until have found one of element using the given search mechanisms.
 WebBrowserElement waitForElement(By findBy, int timeout)
          Wait until have found the element using given search mechanism.
 WebBrowserElement waitForElement(By findBy, int timeout, boolean displayed, boolean single)
          Wait until have found the element using given search mechanism.
 java.util.List<WebBrowserElement> waitForElements(By findBy, int timeout)
          Wait until have found at least one element using the given search mechanism.
 java.util.List<WebBrowserElement> waitForElements(By findBy, int timeout, boolean displayed)
          Wait until have found at least one element using the given search mechanism.
 
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,
                         SearchContext context,
                         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,
                         SearchContext context,
                         By by,
                         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,
                         SearchContext context,
                         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<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.


click

public void click()

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


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 void executeScript(java.lang.String script)
Execute the given script on the current web element.

Parameters:
script - The script to execute

findElement

public WebBrowserElement findElement(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.


findElement

public WebBrowserElement findElement(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(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<WebElement> findElements(By findBy)

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


findElements

public java.util.List<WebElement> findElements(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<WebElement> findElements(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.


getBy

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

Returns:
The search mechanism as a By.

getCoordinates

public Coordinates getCoordinates()

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


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.


getFrame

public WebBrowserFrame getFrame()
Return the element frame.

Returns:
The frame as a WebBrowserFrame.

getFullXpath

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

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

getLocation

public Point getLocation()

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


getLocationOnScreenOnceScrolledIntoView

public Point getLocationOnScreenOnceScrolledIntoView()

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


getParent

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

Returns:
The web element parent as a WebBrowserElement.

getSize

public Dimension getSize()

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


getTagName

public java.lang.String getTagName()

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


getText

public java.lang.String getText()

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


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 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.


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.


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.


sendKeys

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

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


submit

public void submit()

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


toString

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

waitForElement

public WebBrowserElement waitForElement(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(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(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(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(By[] findBys,
                                        int timeout)
Wait until have found one of element using the given search mechanisms.

Fail if: