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

java.lang.Object
  extended by com.ibm.team.fvt.tests.web.WebBrowser
Direct Known Subclasses:
FirefoxBrowser, GoogleChromeBrowser, InternetExplorerBrowser

public abstract class WebBrowser
extends java.lang.Object

Abstract class to handle information of browser used to run FVT Selenium tests.

Currently supported browsers are:

By default, the browser used when running a scenario is Firefox 10. To change it, use the following parameters:

This class is also responsible to access the Selenium WebDriver. This new Selenium API deals with WebElement but due to web page script execution a web element found at some point might become stale a few seconds after. Hence, current class implements the SearchContext and instantiates internal WebBrowserElement which has the ability to recover itself when such failure occurs.


Field Summary
static java.lang.String BROWSER_KIND_ID
           
static java.util.List<WebBrowserElement> NO_BROWSER_ELEMENT_FOUND
           
static java.util.List<WebElement> NO_ELEMENT_FOUND
           
 
Method Summary
 void back()
          Move back a single "item" in the browser's history.
 boolean check(WebBrowserElement element, int toggle, boolean validate)
          Set, unset or toggle the given element assuming this is a check-box.
 WebBrowserElement clickButton(WebBrowserElement button, int timeout, boolean validate)
          Click on the given element and might validate whether it turns disabled after the operation (e.g.
 void close()
          Close the browser which closes every associated window.
static WebBrowser createInstance()
          Create the instance of browser corresponding of the defined parameters.
 WebBrowserElement findElement(By findBy)
          Find an element in the current browser page for the given locator.
 WebBrowserElement findElement(By findBy, boolean recovery)
          Find an element in the current browser page for the given mechanism.
 WebBrowserElement findElement(By findBy, WebBrowserFrame webFrame, boolean recovery)
          Find an element in the current browser page for the given mechanism.
 WebBrowserElement findElementInFrames(By findBy)
          Find an element in the current browser page for the given mechanism.
 java.util.List<WebElement> findElements(By findBy)
          Find elements in the current browser page for the given mechanism.
 java.util.List<WebElement> findElements(By findBy, boolean recovery)
          Find elements in the current browser page for the given mechanism.
 java.util.List<WebElement> findElements(By findBy, boolean displayed, boolean recovery)
          Find elements in the current browser page for the given mechanism.
 void get(java.lang.String pageLocation)
          Get the web page content at the given URL.
 java.lang.String getCurrentUrl()
          Get the current page URL.
 boolean hasSeveralWindows()
          Tells whether several windows are currently opened.
abstract  boolean isFirefox()
          Tells whether the current browser is Firefox or not.
abstract  boolean isGoogleChrome()
          Tells whether the current browser is Google Chrome or not.
abstract  boolean isInternetExplorer()
          Tells whether the current browser is Internet Explorer or not.
 void maximize()
          Maximize the browser window.
 void mouseOver(WebBrowserElement element)
          Move the mouse over the given element.
 void purgeAlert(UnhandledAlertException exception, java.lang.String action, int count)
          Purge the given alert by accepting them before executing the given action.
 int purgeAlerts(java.lang.String action)
          Purge alerts by accepting them before executing the given action.
 void refresh()
          Refresh the current page content.
 void resetFrame()
          Reset the current browser frame.
 void scrollPageTo(WebBrowserElement element)
          Scroll the page to the given element.
 void scrollPageTop()
          Scroll the page to top.
 WebBrowserElement[] select(WebBrowserElement listElement, By entriesBy, java.lang.String[] expected, boolean fail)
          Select items in elements list got from the given list element and the given mechanism to find its children.
 void selectFrame(int index)
          Set the current browser frame to the given index.
 void selectFrame(java.lang.String frameName, boolean force)
          Set the current browser frame to the given name.
 void selectFrame(WebBrowserElement frameElement)
          Set the current browser frame to the given web element.
 void selectFrame(WebBrowserElement frameElement, boolean force)
          Set the current browser frame to the given web element.
 void selectLastFrame()
          Select the last frame
 boolean selectVisibleFrame(int timeout, boolean force)
          Select the current visible browser frame.
 void switchBackToCurrentWindow()
          Switch back to current window.
 void switchToNextWindow()
          Switch to next window.
 void takeFailureSnapshot(java.lang.String message, java.lang.String fileName, java.lang.String testName)
          Deprecated. Use takeSnapshotFailure(String) instead
 void takeSnapshot(java.lang.String title, java.lang.String testName)
          Deprecated. Use takeSnapshotInfo(String) instead
 void takeSnapshotFailure(java.lang.String fileName)
          Takes a failure snapshot.
 void takeSnapshotInfo(java.lang.String fileName)
          Takes an information snapshot.
 void takeSnapshotWarning(java.lang.String fileName)
          Takes a warning snapshot.
 java.lang.String toString()
           
 void typeText(WebBrowserElement element, java.lang.String text, Keys key, boolean clear, int timeout)
          Type a text in an input element.
 WebBrowserElement waitForElement(WebBrowserElement parentElement, By[] findBys, boolean fail, int timeout)
          Wait until have found one of element using the given search mechanisms.
 WebBrowserElement waitForElement(WebBrowserElement parentElement, By findBy, boolean fail, int timeout, boolean displayed, boolean single)
          Wait until have found the element using given mechanism.
 java.util.List<WebBrowserElement> waitForElements(WebBrowserElement parentElement, By findBy, boolean fail, int timeout, boolean displayed)
          Wait until have found one or several elements using given mechanism.
 WebBrowserElement[] waitForMultipleElements(WebBrowserElement parentElement, By[] findBys, boolean fail, int timeout)
          Wait until at least one element is found using each of the given mechanism.
 java.lang.String waitForText(WebBrowserElement element, boolean fail, int timeout, java.lang.String... texts)
          Returns the text for the given element if it matches one of the given ones or null if none matches before the given timeout.
 WebBrowserElement waitForTextPresent(WebBrowserElement parentElement, boolean fail, int timeout, boolean displayed, boolean single, int kind, java.lang.String... texts)
          Returns whether one of the given text is present in the current displayed page content.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

BROWSER_KIND_ID

public static final java.lang.String BROWSER_KIND_ID
See Also:
Constant Field Values

NO_ELEMENT_FOUND

public static final java.util.List<WebElement> NO_ELEMENT_FOUND

NO_BROWSER_ELEMENT_FOUND

public static final java.util.List<WebBrowserElement> NO_BROWSER_ELEMENT_FOUND
Method Detail

createInstance

public static WebBrowser createInstance()
Create the instance of browser corresponding of the defined parameters.

Returns:
A specialized instance of WebBrowser.

back

public void back()
Move back a single "item" in the browser's history.

See Also:
WebDriver.Navigation#back()

check

public boolean check(WebBrowserElement element,
                     int toggle,
                     boolean validate)
Set, unset or toggle the given element assuming this is a check-box.

Parameters:
element - The check-box in the current page
toggle - Tells whether it should be toggled (0), set "on" (1) or set "off" (-1). For all other values than 0, 1 or -1, 0 will be used.
validate - Validate whether the check-box value is well set.
Returns:
trueIf the check-box value has been changed, false otherwise.

clickButton

public WebBrowserElement clickButton(WebBrowserElement button,
                                     int timeout,
                                     boolean validate)
Click on the given element and might validate whether it turns disabled after the operation (e.g. for save buttons...)

Parameters:
button - The button to click on
timeout - The time in seconds to wait before failing if the button never turns enable.
validate - Validate whether the button turns disabled after having been clicked.

close

public void close()
Close the browser which closes every associated window.


findElement

public WebBrowserElement findElement(By findBy)
Find an element in the current browser page for the given locator.

Note that this method allow recovery while trying to find the element (see findElement(By, boolean) for details on recovery). So, if an exception occurs during the operation it will retry it ScenarioUtils.MAX_RECOVERY_TRIES times before giving up and actually raise the exception...

The element is searched in the current browser frame.

Parameters:
findBy - The way to find the element in the page (see By).
Returns:
The found element as WebBrowserElement.

findElement

public WebBrowserElement findElement(By findBy,
                                     boolean recovery)
Find an element in the current browser page for the given mechanism.

If recovery is allowed, WebDriverException exceptions are caught and the operation is retried again until maximum of allowed retries is reached.

If recovery is not allowed, null is returned when a WebDriverException occurs...

The element is searched in the current browser frame.

Parameters:
findBy - The mechanism to find the element in the page.
recovery - Tells whether recovery is allowed when searching the element.
Returns:
The found element as WebBrowserElement or null.

findElement

public WebBrowserElement findElement(By findBy,
                                     WebBrowserFrame webFrame,
                                     boolean recovery)
Find an element in the current browser page for the given mechanism.

If recovery is allowed, WebDriverException exceptions are caught and the operation is retried again until maximum of allowed retries is reached.

If recovery is not allowed, null is returned when a WebDriverException occurs...

Parameters:
findBy - The mechanism to find the element in the page.
webFrame - The expected frame where the element should be searched
recovery - Tells whether recovery is allowed when searching the element.
Returns:
The found element as WebBrowserElement or null. TODO Add the ability not to throw ScenarioFailedError when not found (ie. add fail argument..)

findElementInFrames

public WebBrowserElement findElementInFrames(By findBy)
Find an element in the current browser page for the given mechanism.

The strategy to look for the element is to select in order the following frames and return the first element found:

  1. current frame
  2. no frame
  3. each previous frame from current one until no frame
  4. each next frame from current one until no more frame is available

If an element is found in one of this frame, it becomes the current browser frame.

Note that this method allow recovery while trying to find the element (see findElements(By, boolean) for details on recovery). So, if an exception occurs during the operation it will retry it ScenarioUtils.MAX_RECOVERY_TRIES times before giving up and actually raise the exception...

Parameters:
findBy - The mechanism to find the element in the page (see By).
Returns:
The found element as WebBrowserElement. TODO Try to get rid off this method. Frame should be explicitly handled...

findElements

public java.util.List<WebElement> findElements(By findBy)
Find elements in the current browser page for the given mechanism.

Note that this method allow recovery while trying to find the element (see findElements(By, boolean) for details on recovery). So, if an exception occurs during the operation it will retry it ScenarioUtils.MAX_RECOVERY_TRIES times before giving up and actually raise the exception...

Parameters:
findBy - The mechanism to find the element in the page.
Returns:
The list of found elements as List. Note that each element of the list is a WebBrowserElement.

findElements

public java.util.List<WebElement> findElements(By findBy,
                                               boolean recovery)
Find elements in the current browser page for the given mechanism.

Parameters:
findBy - The mechanism to find the element in the page
recovery - Tells whether the research should try to workaround safely or return null right away if any WebDriverException exception occurs.
Returns:
The list of found elements as List. Each element of the list is a WebBrowserElement.

findElements

public java.util.List<WebElement> findElements(By findBy,
                                               boolean displayed,
                                               boolean recovery)
Find elements in the current browser page for the given mechanism.

Parameters:
findBy - The mechanism to find the element in the page
recovery - Tells whether the research should try to workaround safely or return null right away if any WebDriverException exception occurs.
Returns:
The list of found elements as List. Each element of the list is a WebBrowserElement.

get

public final void get(java.lang.String pageLocation)
Get the web page content at the given URL.

This is a no-op if either the browser url or the driver url are already at the given page url.

This method already handles the InternetExplorer certificate, no needs to add specific after this call to manage it.

Alerts opened at the page opening are also handled by this method and purged as workarounds.

Parameters:
pageLocation - The page location
See Also:
WebDriver#get(String)

getCurrentUrl

public final java.lang.String getCurrentUrl()
Get the current page URL.

Returns:
The page URL as a String.
See Also:
WebDriver#getCurrentUrl()

hasSeveralWindows

public boolean hasSeveralWindows()
Tells whether several windows are currently opened.

Returns:
true if several windows are currently opened, false otherwise.

isFirefox

public abstract boolean isFirefox()
Tells whether the current browser is Firefox or not.

Returns:
true if the current browser is FF, false otherwise.

isGoogleChrome

public abstract boolean isGoogleChrome()
Tells whether the current browser is Google Chrome or not.

Returns:
true if the current browser is GC, false otherwise.

isInternetExplorer

public abstract boolean isInternetExplorer()
Tells whether the current browser is Internet Explorer or not.

Returns:
true if the current browser is IE, false otherwise.

maximize

public void maximize()
Maximize the browser window.


mouseOver

public void mouseOver(WebBrowserElement element)
Move the mouse over the given element.

This is the equivalent method of the old Selenium RC1 API... and allow to trigger rich hover if any.

Parameters:
element - The web element to move to
See Also:
Actions#moveToElement(WebElement)

purgeAlert

public void purgeAlert(UnhandledAlertException exception,
                       java.lang.String action,
                       int count)
Purge the given alert by accepting them before executing the given action.

Parameters:
exception - The alert exception

purgeAlerts

public int purgeAlerts(java.lang.String action)
Purge alerts by accepting them before executing the given action.

Parameters:
action - The action message

refresh

public void refresh()
Refresh the current page content.


resetFrame

public void resetFrame()
Reset the current browser frame.


scrollPageTo

public void scrollPageTo(WebBrowserElement element)
Scroll the page to the given element.


scrollPageTop

public void scrollPageTop()
Scroll the page to top.


select

public WebBrowserElement[] select(WebBrowserElement listElement,
                                  By entriesBy,
                                  java.lang.String[] expected,
                                  boolean fail)
Select items in elements list got from the given list element and the given mechanism to find its children.

If several items are to be selected, hold the Keys#CONTROL key to perform a multi-selection. Of course, that works only if the list web element allow multiple selection.

Parameters:
listElement - The element which children are the elements list to consider for selection.
entriesBy - The way to find the children
expected - The items to select in the list, assuming that text matches
fail - Tells whether to fail (ie. raise a ScenarioFailedError when no all items could be selected. In case not, then the returned array might have null slots.
Returns:
The array of the selected elements as WebBrowserElement. Might have empty slots if not all elements to select were found before the timeout and asked not to fail
Throws:
ScenarioFailedError - if not all elements to select were found before the timeout and asked to fail

selectFrame

public void selectFrame(int index)
Set the current browser frame to the given index.

Parameters:
index - The index of the frame to select.

selectFrame

public void selectFrame(java.lang.String frameName,
                        boolean force)
Set the current browser frame to the given name.

Note that nothing happen if the given frame is null. To reset the frame, caller has to use the explicit method resetFrame().

Parameters:
frameName - The name of the frame to select. That can be either a real name for the frame or an index value.
force - Force the frame selection. If not set and the browser frame is the same than the given one, then nothing is done.
Throws:
NoSuchFrameException - If the given frame name or index does not exist in the web page content.

selectFrame

public void selectFrame(WebBrowserElement frameElement)
Set the current browser frame to the given web element.

Parameters:
frameElement - The frame element to select.
See Also:
WebDriver.TargetLocator#frame(WebElement)

selectFrame

public void selectFrame(WebBrowserElement frameElement,
                        boolean force)
Set the current browser frame to the given web element.

Parameters:
frameElement - The frame element to select.
force - Tells whether the frame should be set even if it's already the current browser one
See Also:
WebDriver.TargetLocator#frame(WebElement)

selectLastFrame

public void selectLastFrame()
Select the last frame


selectVisibleFrame

public boolean selectVisibleFrame(int timeout,
                                  boolean force)
Select the current visible browser frame.

Do nothing if the browser has no visible frame.

Parameters:
timeout - Timeout to find the visible frame
force - Force to select the frame even if it's already the current one.
Returns:
true if there was a visible frame in the browser and becomes the current one, false otherwise.

switchBackToCurrentWindow

public void switchBackToCurrentWindow()
Switch back to current window.


switchToNextWindow

public void switchToNextWindow()
Switch to next window.


takeFailureSnapshot

@Deprecated
public void takeFailureSnapshot(java.lang.String message,
                                           java.lang.String fileName,
                                           java.lang.String testName)
Deprecated. Use takeSnapshotFailure(String) instead

Capture snapshots when a failure occurs while running tests.

Parameters:
message - The failure message, null when the failure is not expected.
fileName - The file suffix, prefix is always the test case in which the failure occurs.
testName - The name of the test case requesting the snapshot.

takeSnapshot

@Deprecated
public void takeSnapshot(java.lang.String title,
                                    java.lang.String testName)
Deprecated. Use takeSnapshotInfo(String) instead

Takes a non-failure snapshot.

Parameters:
title - The title to print in the console.
testName - The name of the test case requesting the snapshot.

takeSnapshotFailure

public void takeSnapshotFailure(java.lang.String fileName)
Takes a failure snapshot.

Parameters:
fileName - The name of the snapshot file.

takeSnapshotInfo

public void takeSnapshotInfo(java.lang.String fileName)
Takes an information snapshot.

Parameters:
fileName - The name of the snapshot file.

takeSnapshotWarning

public void takeSnapshotWarning(java.lang.String fileName)
Takes a warning snapshot.

Parameters:
fileName - The name of the snapshot file.

toString

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

typeText

public void typeText(WebBrowserElement element,
                     java.lang.String text,
                     Keys key,
                     boolean clear,
                     int timeout)
Type a text in an input element.

Note that to raise the corresponding javascript even, an additional Keys#TAB is hit after having entered the text.

Parameters:
element - The input field.
text - The text to type
key - The key to hit after having entered the text in the input field
clear - Tells whether the input field needs to be cleared before putting the text in.
timeout - The timeout before giving up if the text is not enabled
Throws:
ScenarioFailedError - if the input is not enabled before the timeout

waitForElement

public WebBrowserElement waitForElement(WebBrowserElement parentElement,
                                        By findBy,
                                        boolean fail,
                                        int timeout,
                                        boolean displayed,
                                        boolean single)
Wait until have found the element using given mechanism.

Only fail if specified and after having waited the given timeout.

Parameters:
parentElement - The element from where the search must start. If null then element is expected in the current page.
findBy - Mechanism to find the element in the current page.
fail - Tells whether to fail if none of the locators is find before timeout
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 and asked not to fail
Throws:
ScenarioFailedError - if no element was found before the timeout and asked to fail or several elements are found and only single one was expected

waitForElement

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

Fail only if specified and after having waited the given timeout.

Parameters:
parentElement - The element from where the search must start. If null then element is expected in the current page.
findBys - Search mechanisms of the expected elements.
fail - Tells whether to fail if none of the locators is find before timeout
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 and asked not to fail
Throws:
ScenarioFailedError - if no element was found before the timeout and asked to fail or several elements are found and only single one was expected

waitForElements

public java.util.List<WebBrowserElement> waitForElements(WebBrowserElement parentElement,
                                                         By findBy,
                                                         boolean fail,
                                                         int timeout,
                                                         boolean displayed)
Wait until have found one or several elements using given mechanism.

Only fail if specified and after having waited the given timeout.

Parameters:
parentElement - The element from where the search must start. If null then element is expected in the current page.
findBy - Mechanism to find the element in the current page.
fail - Tells whether to fail if none of the locators is find before timeout
timeout - The time to wait before giving up the research
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 and asked not to fail
Throws:
ScenarioFailedError - if no element was found before the timeout and asked to fail

waitForMultipleElements

public WebBrowserElement[] waitForMultipleElements(WebBrowserElement parentElement,
                                                   By[] findBys,
                                                   boolean fail,
                                                   int timeout)
Wait until at least one element is found using each of the given mechanism.

That method stores each found element using the given mechanisms in the the returned array, hence it may have more than one non-null slot.

Note that the method stop to search as soon as at least one element is found. Hence, when several elements are found and returned in the array, that means they have been found in the same loop. The timeout is only reached when no element is found...

Note also that only displayed elements are returned.

Parameters:
parentElement - The parent element where to start to search from, if null, then search in the entire page content
findBys - List of mechanisms to use to find the elements in the current page.
fail - Tells whether to fail if none of the locators is find before timeout
timeout - The time to wait before giving up the research
Returns:
An array with one non-null slot per element found before timeout occurs or null if none was found and it has been asked not to fail.
Throws:
ScenarioFailedError - if no element is found before the timeout occurs and it has been asked to fail.

waitForText

public java.lang.String waitForText(WebBrowserElement element,
                                    boolean fail,
                                    int timeout,
                                    java.lang.String... texts)
Returns the text for the given element if it matches one of the given ones or null if none matches before the given timeout.

Parameters:
element - The web element to get the text from
fail - Tells whether to fail if element text does not match any of the given ones before timeout occurs
timeout - The time to wait before giving up
texts - Several possible texts for the given element text.
Returns:
The matching text as a String if one matches before after having waited the given timeout or null when it's asked not to fail.
Throws:
ScenarioFailedError - If the text never matches before timeout occurs and if it's asked to fail.

waitForTextPresent

public WebBrowserElement waitForTextPresent(WebBrowserElement parentElement,
                                            boolean fail,
                                            int timeout,
                                            boolean displayed,
                                            boolean single,
                                            int kind,
                                            java.lang.String... texts)
Returns whether one of the given text is present in the current displayed page content.

Parameters:
texts - List of the text to find in the page
Returns:
The found web element where text matches one of the given one or null if not asked to fail