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

java.lang.Object
  extended by com.ibm.team.fvt.tests.web.WebBrowser
All Implemented Interfaces:
org.openqa.selenium.SearchContext
Direct Known Subclasses:
FirefoxBrowser, GoogleChromeBrowser, InternetExplorerBrowser

public abstract class WebBrowser
extends java.lang.Object
implements org.openqa.selenium.SearchContext

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.


Nested Class Summary
static class WebBrowser.PopupWindowState
           
 
Field Summary
static java.lang.String BROWSER_KIND_ID
           
static java.lang.String JAVASCRIPT_ERROR_E_IS_NULL
           
static java.util.List<WebBrowserElement> NO_BROWSER_ELEMENT_FOUND
           
static java.util.List<org.openqa.selenium.WebElement> NO_ELEMENT_FOUND
           
 
Method Summary
 boolean acceptAlert(java.lang.String message)
          Accept the alert with the given message.
 void acceptInternetExplorerCertificate()
          Accepts security certificates on Internet Explorer.
 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.
 void checkConnection()
          Check whether there's a connection error or not.
 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.
 void deleteAllCookies()
          Delete all current browser cookies.
 void deleteCookieNamed(java.lang.String cookieName)
          Delete the given cookie stored in the browser.
 void doubleClick(WebBrowserElement element)
          Double-click on the given element;
 void dragAndDrop(WebBrowserElement sourceElement, WebBrowserElement targetElement)
          Drag given sourceElement and drop it to targetElement.
 void dragAndDropBy(WebBrowserElement element, int xOffset, int yOffset)
          Perform a drag and drop from the given horizontal and vertical offsets.
 java.lang.Object executeScript(java.lang.String script)
          Execute the given script on the WebBrowser Element
 WebBrowserElement findElement(org.openqa.selenium.By findBy)
          Find an element in the current browser page for the given locator.
 WebBrowserElement findElement(org.openqa.selenium.By findBy, boolean recovery)
          Find an element in the current browser page for the given mechanism.
 WebBrowserElement findElement(org.openqa.selenium.By findBy, WebBrowserFrame webFrame, boolean recovery)
          Find an element in the current browser page for the given mechanism.
 WebBrowserElement findElementInFrames(org.openqa.selenium.By findBy)
          Find an element with the given locator in the current browser page or one of its visible frame, even if there are some embedded ones.
 java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy)
          Find elements in the current browser page for the given mechanism.
 java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy, boolean recovery)
          Find elements in the current browser page for the given mechanism.
 java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy, boolean displayed, boolean recovery)
          Find elements in the current browser page for the given mechanism.
 java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy, boolean displayed, WebBrowserFrame webFrame, boolean recovery)
          Find elements in the current browser page for the given mechanism.
 java.util.List<WebBrowserElement> findElementsInFrames(org.openqa.selenium.By findBy)
          Find elements with the given locator in the current browser page or one of its visible frame, even if there are some embedded ones.
 void get(java.lang.String pageLocation)
          Get the web page content at the given URL.
 java.util.Set<org.openqa.selenium.Cookie> getCookies()
          Get the current cookies
 WebBrowserFrame getCurrentFrame()
          Return the current frame used by the browser.
 java.lang.String getCurrentUrl()
          Get the current page URL.
 java.lang.String getDowloadDir()
          Deprecated. Since 5.0.1, use getDownloadDir() instead.
 java.io.File getDownloadDir()
          Get the path of the default download directory.
 PerfManager getPerfManager()
          Return the performance manager.
 boolean hasFrame()
          Tells whether the browser has a frame or not.
 boolean hasPopupWindow()
          Tells whether a popup windows is currently opened.
 boolean hasSeveralWindows()
          Deprecated. Use hasPopupWindow() instead.
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)
          Deprecated. Use moveToElement(WebBrowserElement) instead.
 void moveToElement(WebBrowserElement element)
          Deprecated. Use WebBrowserElement.moveToElement() instead
 void moveToElement(WebBrowserElement element, boolean entirelyVisible)
          Move the mouse to the middle of the given element.
 void moveToElement(WebBrowserElement element, int xOffset, int yOffset)
          Moves the mouse to an offset from the top-left corner of the element.
 boolean newSessionPerUser()
          Return whether or not to open a new browser session per each user.
 void purgeAlert(org.openqa.selenium.WebDriverException 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 resetEmbeddedFrame()
          Reset the current browser embedded frame.
 void resetFrame()
          Reset the current browser frame.
 void resetFrame(boolean store)
          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, org.openqa.selenium.By entriesBy, boolean useControl, java.lang.String... expected)
          Select items in elements list got from the given list element and the given mechanism to find its children.
 WebBrowserElement[] select(WebBrowserElement listElement, org.openqa.selenium.By entriesBy, boolean useControl, StringComparisonCriterion[] comparisonCriteria, java.lang.String... expected)
          Select items in elements list got from the given list element and the given mechanism to find its children.
 WebBrowserElement[] select(WebBrowserElement listElement, org.openqa.selenium.By entriesBy, java.lang.String... expected)
          Select items in elements list got from the given list element and the given mechanism to find its children.
 WebBrowserElement[] select(WebBrowserElement listElement, org.openqa.selenium.By entriesBy, java.lang.String[] expected, boolean fail)
          Deprecated. Use select(WebBrowserElement, By, String...) instead.
 void selectEmbeddedFrame(WebBrowserElement frameElement, WebBrowserFrame browserFrame, boolean store)
          Set the current browser frame to the given web element.
 void selectFrame()
          Select the current stored frame.
 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 selectFrame(WebBrowserElement frameElement, boolean force, boolean store)
          Set the current browser frame to the given web element.
 void selectFrame(WebBrowserFrame webFrame)
           
 void selectFrame(WebBrowserFrame webFrame, boolean store)
           
 void selectLastFrame()
          Deprecated. Should not used as the getLastFrame() method is not working for embedded frames.
 boolean selectVisibleFrame(int timeout)
          Select the current visible browser frame.
 void setWindowSize(int width, int height)
          Set the browser window size.
 void shiftClick(WebBrowserElement destination)
          Perform shift click to do a range selection.
 void switchBackToCurrentWindow()
          Deprecated. Use switchToMainWindow() instead.
 void switchToMainWindow()
          Switch back to current window.
 void switchToNextWindow()
          Deprecated. Use switchToPopupWindow() instead.
 void switchToPopupWindow()
          Switch to popup 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
 byte[] takeSnapshotBytes()
          Takes a snapshot and return it as a bytes array.
 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, org.openqa.selenium.Keys key, boolean clear, int timeout)
          Type a text in an input element.
 void typeText(WebBrowserElement element, java.lang.String text, org.openqa.selenium.Keys key, int keyDelay, boolean clear, int timeout)
          Type a text in an input element.
 WebBrowserElement waitForElement(org.openqa.selenium.By findBy, int timeout)
          Wait until have found the element using given mechanism.
 WebBrowserElement waitForElement(WebBrowserElement parentElement, org.openqa.selenium.By[] findBys, boolean fail, int timeout)
          Wait until have found one of element using the given search mechanisms.
 WebBrowserElement waitForElement(WebBrowserElement parentElement, org.openqa.selenium.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, org.openqa.selenium.By findBy, boolean fail, int timeout, boolean displayed)
          Wait until have found one or several elements using given mechanism.
 WebBrowserElement[] waitForMultipleElements(WebBrowserElement parentElement, org.openqa.selenium.By[] findBys, boolean[] displayFlags, boolean fail, int timeout)
          Wait until at least one element is found using each of the given mechanism.
 WebBrowserElement[] waitForMultipleElements(WebBrowserElement parentElement, org.openqa.selenium.By[] findBys, boolean fail, int timeout)
          Wait until at least one element is found using each of the given mechanism.
 boolean waitForPopupWindowState(WebBrowser.PopupWindowState state, int seconds, boolean fail)
          Wait for a popup window to be opened and/or closed.
 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, ByUtils.ComparisonPattern pattern, java.lang.String... texts)
          Returns whether one of the given text is present in the current displayed page content.
 WebBrowserElement waitForTextPresent(WebBrowserElement parentElement, boolean fail, int timeout, boolean displayed, boolean single, int kind, java.lang.String... texts)
          Deprecated. Since 5.0.1, use #waitForTextPresent(WebBrowserElement, boolean, int, boolean, boolean, ComparisonPattern, String...) instead
 
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<org.openqa.selenium.WebElement> NO_ELEMENT_FOUND

NO_BROWSER_ELEMENT_FOUND

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

JAVASCRIPT_ERROR_E_IS_NULL

public static final java.lang.String JAVASCRIPT_ERROR_E_IS_NULL
See Also:
Constant Field Values
Method Detail

createInstance

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

Returns:
A specialized instance of WebBrowser.

acceptAlert

public boolean acceptAlert(java.lang.String message)
Accept the alert with the given message.

A warning is displayed in the console when the accepted alert has not the expected text.

Parameters:
message -
Returns:
true if the accepted has the correct message, false otherwise.

acceptInternetExplorerCertificate

public void acceptInternetExplorerCertificate()
Accepts security certificates on Internet Explorer. Switches to a popup window if one exists and clicks link to proceed to website. Does not switch back to main browser window if popup window is found.


back

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

Warning: This method does not modify the web pages cache, hence it should be used with caution. It would be better to use WebPage.goBack() method instead to keep browser content and pages cache synchronized.

Note that this will possible desynchronization will be fixed when pages cache is managed by the browser itself instead of WebPage class...

See Also:
"https://jazz.net/jazz/resource/itemName/com.ibm.team.workitem.WorkItem/253564", 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.


deleteAllCookies

public void deleteAllCookies()
Delete all current browser cookies.

See Also:
WebDriver.Options.deleteAllCookies()

deleteCookieNamed

public void deleteCookieNamed(java.lang.String cookieName)
Delete the given cookie stored in the browser.

Parameters:
cookieName - The name of the cookie to be deleted.
See Also:
WebDriver.Options.deleteCookieNamed(String)

doubleClick

public void doubleClick(WebBrowserElement element)
Double-click on the given element;

Parameters:
element - The web element to doubl-click on

dragAndDrop

public void dragAndDrop(WebBrowserElement sourceElement,
                        WebBrowserElement targetElement)
Drag given sourceElement and drop it to targetElement.

Parameters:
sourceElement - The web element to be dragged
targetElement - The web element over which sourceElement has to be dropped
See Also:
Actions.dragAndDrop(WebElement, WebElement)

dragAndDropBy

public void dragAndDropBy(WebBrowserElement element,
                          int xOffset,
                          int yOffset)
Perform a drag and drop from the given horizontal and vertical offsets.

Parameters:
element - The element to be dragged and dropped
xOffset - The horizontal offset for the drag
yOffset - The vertical offset for the drag

executeScript

public java.lang.Object executeScript(java.lang.String script)
Execute the given script on the WebBrowser 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)
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.

Specified by:
findElement in interface org.openqa.selenium.SearchContext
Parameters:
findBy - The way to find the element in the page (see By).
Returns:
The found element as WebBrowserElement.

findElement

public WebBrowserElement findElement(org.openqa.selenium.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(org.openqa.selenium.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(org.openqa.selenium.By findBy)
Find an element with the given locator in the current browser page or one of its visible frame, even if there are some embedded ones.

If an element is found in one of this frame, it becomes the current browser frame. In case no element is found, the browser has no frame selected when returning from this method.

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 as its has a high performance cost. Frames should be explicitly handled...

findElementsInFrames

public java.util.List<WebBrowserElement> findElementsInFrames(org.openqa.selenium.By findBy)
Find elements with the given locator in the current browser page or one of its visible frame, even if there are some embedded ones.

If elements are found in one of this frame, it becomes the current browser frame. In case no element is found, the browser has no frame selected when returning from this method.

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 as its has a high performance cost. Frames should be explicitly handled...

findElements

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

Specified by:
findElements in interface org.openqa.selenium.SearchContext
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<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.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<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.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
displayed - Tells whether the element needs to be displayed or not
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<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.By findBy,
                                                                   boolean displayed,
                                                                   WebBrowserFrame webFrame,
                                                                   boolean recovery)
Find elements in the current browser page for the given mechanism.

Parameters:
findBy - The mechanism to find the element in the page
displayed - Tells whether the element needs to be displayed or not
webFrame - The expected frame where the element should be searched
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)

getCookies

public java.util.Set<org.openqa.selenium.Cookie> getCookies()
Get the current cookies

Returns:
The current cookies in web browser
See Also:
WebDriver.Options.getCookies()

getCurrentUrl

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

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

getCurrentFrame

public WebBrowserFrame getCurrentFrame()
Return the current frame used by the browser.

Note that in case of an opened popup window, this the frame of this window which is returned.

Returns:
The frame as a WebBrowserFrame

getDowloadDir

@Deprecated
public java.lang.String getDowloadDir()
Deprecated. Since 5.0.1, use getDownloadDir() instead.

Get the path of the default download directory.

Returns:
The path of the default download directory as a String

getDownloadDir

public java.io.File getDownloadDir()
Get the path of the default download directory.

Returns:
The path of the default download directory as a File

checkConnection

public void checkConnection()
Check whether there's a connection error or not.

Throws:
BrowserConnectionError - If there's a connection error with the current page. TODO Check that the web element is the same for all browsers

getPerfManager

public PerfManager getPerfManager()
Return the performance manager.

Returns:
The performance manager as a PerfManager.

hasFrame

public boolean hasFrame()
Tells whether the browser has a frame or not.

Returns:
true if a frame is selected, false otherwise.

hasPopupWindow

public boolean hasPopupWindow()
Tells whether a popup windows is currently opened.

Returns:
true if a popup window is opened, false otherwise.

hasSeveralWindows

@Deprecated
public boolean hasSeveralWindows()
Deprecated. Use hasPopupWindow() instead.

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

@Deprecated
public void mouseOver(WebBrowserElement element)
Deprecated. Use moveToElement(WebBrowserElement) instead.

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)

moveToElement

@Deprecated
public void moveToElement(WebBrowserElement element)
Deprecated. Use WebBrowserElement.moveToElement() instead

Move the mouse to the middle of the given element.

Note that for link this action trigger the rich hover.

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

moveToElement

public void moveToElement(WebBrowserElement element,
                          boolean entirelyVisible)
Move the mouse to the middle of the given element.

Note that for link this action trigger the rich hover.

Warning: It's strongly advised to use WebBrowserElement.moveToElement(boolean) instead which is protected against StaleElementReferenceException although this method is not...

Parameters:
element - The web element to move to
entirelyVisible - Ensure that the entire web element will be visible in the browser window
See Also:
Actions.moveToElement(WebElement)

moveToElement

public void moveToElement(WebBrowserElement element,
                          int xOffset,
                          int yOffset)
Moves the mouse to an offset from the top-left corner of the element.

Parameters:
element - The web element to move to
xOffset - Offset from the top-left corner. A negative value means coordinates right from the element.
yOffset - Offset from the top-left corner. A negative value means coordinates above the element.

newSessionPerUser

public boolean newSessionPerUser()
Return whether or not to open a new browser session per each user.

Returns:
Whether or not to open a new browser session per each user as a boolean.

purgeAlert

public void purgeAlert(org.openqa.selenium.WebDriverException 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.

After this operation no frame will be selected in the browser.


resetEmbeddedFrame

public void resetEmbeddedFrame()
Reset the current browser embedded frame.

If the current browser is not an embedded frame (ie; WebEmbeddedFrame) then nothing is done on the current browser frame.


resetFrame

public void resetFrame(boolean store)
Reset the current browser frame.

WARNING: When caller used a falsevalue to not store the reset, it's strongly recommended to call selectFrame() after in order to resynchronize the browser instance with its window.

Parameters:
store - Tells whether the reset frame should be stored in the browser or not.

scrollPageTo

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

This is a no-op if the web element is already visible in the browser view.

Parameters:
element - The web element to scroll the page to

scrollPageTop

public void scrollPageTop()
Scroll the page to top.


select

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

If useControl is set to true, it holds the Keys.CONTROL key to perform a multi-selection. Of course, that works only if the list web element allow multiple selection.

If the expected entries are not found, WebBrowserElement.MAX_RECOVERY_ATTEMPTS attempts are done before raising a ScenarioFailedError. Note that a sleep of 2 seconds is done between each attempt.

Parameters:
listElement - The element which children are the elements list to consider for selection.
entriesBy - The way to find the children
useControl - should hold control while selecting multiple elements
comparisonCriteria - A list of criteria to determine how to match an item in the elements list to the expected/given option
expected - The items to select in the list, assuming that text matches
Returns:
The array of the selected elements as WebBrowserElement.
Throws:
ScenarioFailedError - if not all elements to select were found after having retried WebBrowserElement.MAX_RECOVERY_ATTEMPTS times.

select

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

All StringComparisonCriterion are used to determine how to match an item in the elements list to the expected/given option

If useControl is set to true, it holds the Keys.CONTROL key to perform a multi-selection. Of course, that works only if the list web element allow multiple selection.

If the expected entries are not found, WebBrowserElement.MAX_RECOVERY_ATTEMPTS attempts are done before raising a ScenarioFailedError. Note that a sleep of 2 seconds is done between each attempt.

Parameters:
listElement - The element which children are the elements list to consider for selection.
entriesBy - The way to find the children
useControl - should hold control while selecting multiple elements
expected - The items to select in the list, assuming that text matches
Returns:
The array of the selected elements as WebBrowserElement.
Throws:
ScenarioFailedError - if not all elements to select were found after having retried WebBrowserElement.MAX_RECOVERY_ATTEMPTS times.

select

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

If the expected entries are not found, WebBrowserElement.MAX_RECOVERY_ATTEMPTS attempts are done before raising a ScenarioFailedError. Note that a sleep of 2 seconds is done between each attempt.

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
Returns:
The array of the selected elements as WebBrowserElement.
Throws:
ScenarioFailedError - if not all elements to select were found after having retried WebBrowserElement.MAX_RECOVERY_ATTEMPTS times.

select

@Deprecated
public WebBrowserElement[] select(WebBrowserElement listElement,
                                             org.openqa.selenium.By entriesBy,
                                             java.lang.String[] expected,
                                             boolean fail)
Deprecated. Use select(WebBrowserElement, By, String...) instead.

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()
Select the current stored frame.

That can be necessary in case of desynchronization between the browser instance and the real browser...


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:
org.openqa.selenium.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)

selectFrame

public void selectFrame(WebBrowserElement frameElement,
                        boolean force,
                        boolean store)
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
store - Tells whether the new frame should be store in the browser or not. Setting this argument to false should be done cautiously as that will imply a desynchronization between the browser instance and the window.
See Also:
WebDriver.TargetLocator.frame(WebElement)

selectFrame

public void selectFrame(WebBrowserFrame webFrame)

selectFrame

public void selectFrame(WebBrowserFrame webFrame,
                        boolean store)

selectEmbeddedFrame

public void selectEmbeddedFrame(WebBrowserElement frameElement,
                                WebBrowserFrame browserFrame,
                                boolean store)
Set the current browser frame to the given web element.

Parameters:
frameElement - The frame element to select.

selectLastFrame

@Deprecated
public void selectLastFrame()
Deprecated. Should not used as the getLastFrame() method is not working for embedded frames.

Select the last frame


selectVisibleFrame

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

Do nothing if the browser has no visible frame.

Parameters:
timeout - Timeout to find the visible frame
Returns:
true if there was a visible frame in the browser and becomes the current one, false otherwise.
Throws:
ScenarioFailedError - If no visible frame has been found.

setWindowSize

public void setWindowSize(int width,
                          int height)
Set the browser window size.

Parameters:
width - The new browser window width. Should be a value between MIN_WIDTH and MAX_WIDTH, otherwise it will be ignored.
height - The new browser window height. Should be a value between MIN_HEIGHT and MAX_HEIGHT, otherwise it will be ignored.

shiftClick

public void shiftClick(WebBrowserElement destination)
Perform shift click to do a range selection.

Parameters:
destination - The last WebBrowseElment of a range selection selected by performing a shift click

switchBackToCurrentWindow

@Deprecated
public void switchBackToCurrentWindow()
Deprecated. Use switchToMainWindow() instead.

Switch back to current window.


switchToMainWindow

public void switchToMainWindow()
Switch back to current window.


switchToNextWindow

@Deprecated
public void switchToNextWindow()
Deprecated. Use switchToPopupWindow() instead.

Switch to next window.


switchToPopupWindow

public void switchToPopupWindow()
                         throws org.openqa.selenium.NoSuchWindowException
Switch to popup window.

Throws:
org.openqa.selenium.NoSuchWindowException - When popup is transient and closed before being able to switch to it.

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.

takeSnapshotBytes

public byte[] takeSnapshotBytes()
Takes a snapshot and return it as a bytes array.

Returns:
The snapshot bytes array.

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,
                     org.openqa.selenium.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

typeText

public void typeText(WebBrowserElement element,
                     java.lang.String text,
                     org.openqa.selenium.Keys key,
                     int keyDelay,
                     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.
keyDelay - Defines the waiting time before the key parameter send to the input element.
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(org.openqa.selenium.By findBy,
                                        int timeout)
Wait until have found the element using given mechanism.

Note that:

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 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,
                                        org.openqa.selenium.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,
                                        org.openqa.selenium.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,
                                                         org.openqa.selenium.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,
                                                   org.openqa.selenium.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.

waitForMultipleElements

public WebBrowserElement[] waitForMultipleElements(WebBrowserElement parentElement,
                                                   org.openqa.selenium.By[] findBys,
                                                   boolean[] displayFlags,
                                                   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.
displayFlags - List of flag telling whether the corresponding element should be displayed or not. If null, then it's assumed that all elements have to be displayed.
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.

waitForPopupWindowState

public boolean waitForPopupWindowState(WebBrowser.PopupWindowState state,
                                       int seconds,
                                       boolean fail)
                                throws ScenarioFailedError
Wait for a popup window to be opened and/or closed.

The possible state to wait for are:

Parameters:
state - The expected state for the popup window, see above for the valid values.
seconds - Timeout in seconds to wait for the expected popup window status
fail - Tells whether to fail (ie. throw a ScenarioFailedError) if the popup window state does not match the expected one
Returns:
true if the popup window behaved as expected, false otherwise when no failure is expected
Throws:
ScenarioFailedError - if the popup window does not behave as expected and failure was requested

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,
                                            ByUtils.ComparisonPattern pattern,
                                            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

waitForTextPresent

@Deprecated
public WebBrowserElement waitForTextPresent(WebBrowserElement parentElement,
                                                       boolean fail,
                                                       int timeout,
                                                       boolean displayed,
                                                       boolean single,
                                                       int kind,
                                                       java.lang.String... texts)
Deprecated. Since 5.0.1, use #waitForTextPresent(WebBrowserElement, boolean, int, boolean, boolean, ComparisonPattern, String...) instead

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