org.safs.selenium.webdriver.lib

Class SearchObject

java.lang.Object

org.safs.selenium.webdriver.lib.SearchObject

Direct Known Subclasses:

WDLibrary

public class SearchObject
extends java.lang.Object

Primary class used to find WebElements with Selenium WebDriver.

Supports various recognition string syntax, to include:

Identify the proper FRAME, if present:

     FRAMEINDEX=N;\; (1-based, 1 means the first frame)
     FRAMEID=id;\;
     FRAMENAME=name;\;
     FRAMEXPATH=//iframe[@id='frameId'];\;

     (note: parent/child elements separated by ";\;" )
     (note: FRAMEINDEX is NOT ready for using )
     (note: If there is no frame-expression in a RS, the last visited frame
            will be the frame where to find component. By default, the last visited
            frame is the main frame (the topmost html Document).
            And that is why if we specify frame for a window, then their children
            doesn't need to specify the frame information anymore. For example:
            [HelpPopup]
            HelpPopup="FRAMEID=VisualAnalyticsHubLogon_iframe;\;id=__popover8-popover"
            BtnHelpCenter="id=__item23"

            BtnHelpCenter is supposed to be found in frame 'VisualAnalyticsHubLogon_iframe'
      )
     

Identify any supported "TYPE" qualifier, if desired:

     TYPE=DOJOTabControl;
     TYPE=DOJOToolbar;
     TYPE=SAPTabControl;
     TYPE=SAPToolbar;
     (see [doclink here] for supported domain classes)

     (note: type qualifier also includes domain information, like "DOJO", "SAP")
     (note: type qualifier and attribute identifiers separated by semi-colons)
     

Identify unique element attribute identifiers like:

     ID=id;
     CLASS=class;
     NAME=name;
     TEXT=text;
     TITLE=title;
     LINK=linkInfo;
     PARTIALLINK=partialLinkInfo;
     TAG=tagname;

     (note: multiple attribute identifiers separated by semi-colons ;)
     

Identify element by multiple native attributes:

     property1=xxx;property2=yyy;property3=zzz;

     

Identify explicit XPATH or CSS recognition:

     XPATH=explicit xpath
     CSS=explicit css path
     

Identify any supported qualifier, if desired:

     INDEX=n;                             (1-based, NOT used alone, indicates the Nth matched)
     ITEMINDEX=n;                         (1-based, NOT used alone, indicates the Nth item in a List, or ComboBox etc.)
     PATH=parent->child->grandchild;      (NOT used alone, indicates the sub-item in a List, ComboBox, Menu or Tree etc.)
     PROPERTY=prop:value;                 (can be used with others to enforce search condition)
     PROPERTYCONTAINS=prop:partialValue;  (can be used with others to enforce search condition)

     (note: multiple qualifiers separated by semi-colons ;)
     (note: these "ID", "TEXT", "ITEMINDEX", "PATH" will normally be considered as qualifier, but if there is a
            prefix :PASM: infront, they will be considered as component's native properties too.
            Example:
            For "TEXT=myList;componentProperty=xxx;ITEMINDEX=n;"
            "TEXT" and "ITEMINDEX" are qualifiers, while "componentProperty" is native property
            For ":PASM:TEXT=myList;componentProperty=xxx;ITEMINDEX=n;"
            "TEXT", "ITEMINDEX" and "componentProperty" are all native properties
      )
     

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SearchObject.BrowserWindow
protected static class	SearchObject.DefaultJSEventListener A default javascript event listener. Usage example:
static class	SearchObject.DOJO Inner class to handle DOJO-specific functionality.
protected static class	SearchObject.FrameElement
static interface	SearchObject.GenericJSEventListener A generic javascript event listener interface. History: Apr 14, 2014 (Lei Wang) Initial release.
static class	SearchObject.HTML
static class	SearchObject.SAP
static class	SearchObject.SwitchFramesResults

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	assignSeparator separates type and value for one qualifier.
static java.lang.String	childSeparator separates parent/child relationships in recognition strings.
static java.lang.String	CSS_CLASS_DOJO_DIJIT_PREFIX 'dijit'
static java.lang.String	CSS_CLASS_SAP_PREFIX 'sap'
static java.lang.String	CSS_CLASS_SEPARATOR ' '
static java.lang.String	CSS_SELECTOR_BY_CLASSNAME
static java.lang.String	CSS_SELECTOR_BY_ID
static boolean	DEFAULT_IGNORE_CASE true
static int	DEFAULT_JS_EXECUTION_DELAY 0
static long	DEFAULT_JS_TIMEOUT '5000' milliseconds
static boolean	DEFAULT_PARTIAL_MATCH false
static java.lang.String	DOMAIN_DOJO DOJO
static java.lang.String	DOMAIN_HTML HTML
static java.lang.String	DOMAIN_SAP
static java.lang.Character	escapeChar the character to escape separators.
static java.lang.String[]	IGNORED_NONUI_TAGS non-ui tags to be ignored in xpath searches and xpath generation.
static int	INVALID_INDEX
protected static java.util.Map<java.lang.String,SearchObject.GenericJSEventListener>	jsEventListenerMap A map containing pairs of (listenerID, listener).
protected static java.util.Map<java.lang.String,org.safs.selenium.webdriver.lib.SearchObject.PollingRunnable>	jsEventListenerWaitingThreadMap A map containing pairs of (listenerID, PollingRunnable).
protected static SearchObject.BrowserWindow	lastBrowserWindow The last visited browser window
protected static SearchObject.FrameElement	lastFrame The frame object where the current GUI-component locate.
protected static org.openqa.selenium.JavascriptExecutor	lastJS The Selenium 'JavascriptExecutor' currently used to execute javascript on the browser.
protected static org.openqa.selenium.WebDriver	lastUsedWD The Selenium 'WebDriver' currently used to manipulate the browser.
protected static java.lang.String	lastVisitedURL The last visited URL,
static int	MATCHED_ONE_TIME 1 integer one
static int	MATCHED_ZERO_TIMES 0 integer zero
static java.lang.String	propertySeparator separates property-name and property-value.
static java.lang.String	qulifierSeparator separates multiples qualifiers.
static java.lang.String	SEARCH_CRITERIA_CLASS CLASS
static java.lang.String	SEARCH_CRITERIA_CLASS_CONTAINS CLASSCONTAINS
static java.lang.String	SEARCH_CRITERIA_CONTAINS_SUFFIX "CONTAINS"
static java.lang.String	SEARCH_CRITERIA_CSS CSS
static java.lang.String	SEARCH_CRITERIA_FRAMEID FRAMEID, it should be placed in front of normal tokens like ID, CLASS, NAME etc.
static java.lang.String	SEARCH_CRITERIA_FRAMEINDEX FRAMEINDEX, it should be placed in front of normal tokens like ID, CLASS, NAME etc.
static java.lang.String	SEARCH_CRITERIA_FRAMENAME FRAMENAME, it should be placed in front of normal tokens like ID, CLASS, NAME etc.
static java.lang.String	SEARCH_CRITERIA_FRAMEXPATH FRAMEXPATH, it should be placed in front of normal tokens like ID, CLASS, NAME etc.
static java.lang.String	SEARCH_CRITERIA_ID ID
static java.lang.String	SEARCH_CRITERIA_IFRAMEID IFRAMEID, it should be placed in front of normal tokens like ID, CLASS, NAME etc.
static java.lang.String	SEARCH_CRITERIA_INDEX INDEX
static java.lang.String	SEARCH_CRITERIA_ITEMINDEX ITEMINDEX
static java.lang.String	SEARCH_CRITERIA_LINK LINK
static java.lang.String	SEARCH_CRITERIA_NAME NAME
static java.lang.String	SEARCH_CRITERIA_PARTIALLINK PARTIALLINK
static java.lang.String	SEARCH_CRITERIA_PATH PATH
static java.lang.String	SEARCH_CRITERIA_PROPERTY PROPERTY
static java.lang.String	SEARCH_CRITERIA_PROPERTY_CONTAINS PROPERTYCONTAINS
static java.lang.String	SEARCH_CRITERIA_TAG TAG
static java.lang.String	SEARCH_CRITERIA_TEXT TEXT
static java.lang.String	SEARCH_CRITERIA_TITLE TITLE
static java.lang.String	SEARCH_CRITERIA_TYPE TYPE
static java.lang.String	SEARCH_CRITERIA_XPATH XPATH
static java.lang.String	TAG_FRAME 'frame' tag name
static java.lang.String	TAG_IFRAME 'iframe' tag name
static java.lang.String[]	TEXT_VALUE_ATTRIBUTES "value","text","placeholder".
static java.lang.String	XPATH_CHILD_SEPARATOR separates parent/child relationships in recognition strings.

Constructor Summary

Constructors

Constructor and Description
SearchObject()

Method Summary

Modifier and Type	Method and Description
protected static SearchObject.SwitchFramesResults	_switchFrames(java.lang.String recognitionString) Before doing any component search, we make sure we are in the correct frame.
static java.lang.String	addJavaScriptEventListener(org.openqa.selenium.WebElement element, java.lang.String eventName, SearchObject.GenericJSEventListener listener)
protected static org.openqa.selenium.WebDriver	addWebDriver(java.lang.String id, org.openqa.selenium.WebDriver wd) Store the WebDriver in the Hashtable by id. This also sets this WebDriver as the "current" or "lastUsed" WebDriver.
(package private) static boolean	checkCSSClassName(org.openqa.selenium.WebElement element, java.lang.String prefix, java.lang.String separator) To check if the html tag's css class name containing a certain prefix.
static void	checkNotNull(java.lang.Object object) Check that the object is not null.
static boolean	clearHighlight() clear the previous highlight of a webelement. Note:The webelement should be highlighted by highlight(String) or highlight(WebElement), normally you don't need to call this method to clear the highlight if you want to highlight element one by one continuously, as the previous highlighted element will be automatically cleared before next element is highlighted.
static boolean	containFrameRS(java.lang.String rs)
static boolean	containTagRS(java.lang.String rs)
static java.lang.Object	executeAsyncScript(java.lang.String script, java.lang.Object... args)
static java.lang.Object	executeJavaScriptOnWebElement(java.lang.String script, org.openqa.selenium.WebElement webelement, java.lang.Object... args)
static java.lang.Object	executeScript(boolean synch, java.lang.String script, java.lang.Object... args) Execute a section of java-script code. It has the ability to detect a javascript error and throw an JSException.
static java.lang.Object	executeScript(java.lang.String script, java.lang.Object... args)
static org.openqa.selenium.WebElement	findElement(org.openqa.selenium.By by)
protected static java.util.List<org.openqa.selenium.WebElement>	findElements(org.openqa.selenium.SearchContext wel, java.lang.String xpath)
static java.lang.String	generateFullGenericXPath(org.openqa.selenium.WebElement element) Attempt to generate a full generic Xpath string for this element including all parent path information.
static java.lang.String	generateGenericXPath(org.openqa.selenium.WebElement element) Attempt to generate a simple Xpath string for this one element without any parent path information.
static java.lang.String	generateSAFSFrameRecognition(java.lang.String framexpath) Attempt to generate a simple frame recognition string without any parent path information.
static java.lang.String	generateUniqueName(java.lang.String prefix) Deprecated. This method has been moved to StringUtils, we can call StringUtils.generateUniqueName() directly.
static java.lang.String[]	getAllWindowTitles()
static boolean	getBoolean(org.openqa.selenium.WebElement webelement, java.lang.String... attributes) Get a boolean value from the WebElement according to the attributes.
static java.lang.String	getCssSelector(java.lang.String type, org.openqa.selenium.WebElement element) According to the type, generate a css selector for the WebElement.
(package private) static java.lang.String	getDescription(org.openqa.selenium.WebElement element) Return a string to describe a selenium web element.
protected static java.lang.String[]	getFirstQualifierPair(java.lang.String RS) Split a string by separator assignSeparator, and return the result. If the RS contains multiple assignSeparator, this method will ONLY consider the first separator, the string before that separator will be considered as qualifier; the string after will be all considered as value.
protected static org.openqa.selenium.WebElement	getFrameWebElement(org.openqa.selenium.SearchContext sc, int index) Find the Nth frame webelement in the search context.
static java.lang.String	getIDForWebDriver(org.openqa.selenium.WebDriver wd) At this time does NOT set the processed WebDriver to be the "current" or "lastUsed" WebDriver.
static org.openqa.selenium.JavascriptExecutor	getJS()
static int	getJsExecutionDelay()
static long	getJsTimeout()
static SearchObject.BrowserWindow	getLastBrowserWindow()
static SearchObject.FrameElement	getLastFrame() The frame object where the current GUI-component locate.
static java.lang.String	getLastVisitedURL()
protected static org.openqa.selenium.SearchContext	getMatchedObject(java.util.List<org.safs.selenium.webdriver.lib.SearchObject.WebElementWarpper> elements, java.lang.String value, boolean partialMatch)
protected static java.util.List<org.openqa.selenium.WebElement>	getMatchedObjects(java.util.List<org.safs.selenium.webdriver.lib.SearchObject.WebElementWarpper> elements, java.lang.String value, boolean partialMatch)
protected static org.openqa.selenium.WebElement	getNthWebElement(java.util.List<org.openqa.selenium.WebElement> preMatches, int matchindex, java.lang.String typeInSAFS) Find the Nth matched WebElement in a list.
static org.openqa.selenium.WebElement	getObject(org.openqa.selenium.SearchContext sc, java.lang.String recognitionString) Primary entry point to seek a WebElement based on a provided recognition string.
static org.openqa.selenium.WebElement	getObject(java.lang.String RS) Get the object based on the recognition string.
protected static org.openqa.selenium.SearchContext	getObjectByMultiAttributes(org.openqa.selenium.SearchContext sc, java.lang.String RS, boolean isPASM) Builds an XPath search string using multiple attributes provided in the recognition string then performs a findElement(By.xpath(string)); If the recognition string contains special attributes, How to tell them from normal attributes???
protected static org.openqa.selenium.SearchContext	getObjectByQualifier(org.openqa.selenium.SearchContext sc, java.lang.String qualifier, java.lang.String value) According to pair(qualifier, value), find the matched WebElement. Some qualifiers like "ID", can determine the WebElement uniquely and result only one WebElement; Other qualifiers may result several WebElement, the first one will be returned.
protected static org.openqa.selenium.SearchContext	getObjectByText(org.openqa.selenium.SearchContext wel, java.lang.String text, boolean partialMatch)
protected static org.openqa.selenium.SearchContext	getObjectByTitle(org.openqa.selenium.SearchContext wel, java.lang.String value, boolean partialMatch)
protected static org.openqa.selenium.WebElement	getObjectByXpathAndQualifiers(org.openqa.selenium.SearchContext sc, java.lang.String xpathStr, java.util.HashMap<java.lang.String,java.lang.String> qualifiers) According to xpath and qualifiers to find the WebElement.
protected static org.openqa.selenium.WebElement	getObjectForDomain(org.openqa.selenium.SearchContext sc, java.lang.String RS, boolean isPropertyAllMode) Alternate search for special framework elements like Dojo or SAP OpenUI5 components.
static java.util.List<org.openqa.selenium.WebElement>	getObjects(org.openqa.selenium.SearchContext sc, java.lang.String recognitionString) Primary entry point to seek all WebElements matching a provided recognition string.
protected static java.util.List<org.openqa.selenium.WebElement>	getObjectsByMultiAttributes(org.openqa.selenium.SearchContext sc, java.lang.String RS, boolean isPASM) Builds an XPath search string using multiple attributes provided in the recognition string then performs a findElements(By.xpath(string)); If the recognition string contains special attributes, How to tell them from normal attributes???
protected static java.util.List<org.openqa.selenium.WebElement>	getObjectsByQualifier(org.openqa.selenium.SearchContext sc, java.lang.String qualifier, java.lang.String value) According to pair(qualifier, value), find all matching WebElements. Some qualifiers like "ID", can determine the WebElement uniquely and result only one WebElement; Other qualifiers may result in several WebElements.
protected static java.util.List<org.openqa.selenium.WebElement>	getObjectsByText(org.openqa.selenium.SearchContext wel, java.lang.String text, boolean partialMatch)
protected static java.util.List<org.openqa.selenium.WebElement>	getObjectsByTitle(org.openqa.selenium.SearchContext wel, java.lang.String value, boolean partialMatch)
protected static java.util.List<org.openqa.selenium.WebElement>	getObjectsByXpathAndQualifiers(org.openqa.selenium.SearchContext sc, java.lang.String xpathStr, java.util.HashMap<java.lang.String,java.lang.String> qualifiers) According to xpath and qualifiers to find matching WebElements. While returning a List, it is likely the List will have only 1 matching item.
protected static java.util.List<org.openqa.selenium.WebElement>	getObjectsForDomain(org.openqa.selenium.SearchContext sc, java.lang.String RS, boolean isPropertyAllMode) Alternate search for special framework elements like Dojo or SAP OpenUI5 components.
static org.openqa.selenium.WebElement	getParentWebElement(org.openqa.selenium.WebElement element) Return the parent WebElement of the provided WebElement.
protected static org.openqa.selenium.WebElement	getSubItem(org.openqa.selenium.WebElement itemContainer, TextMatchingCriterion criterion) According to TextMatchingCriterion to get the sub item within a container WebElement.
protected static java.lang.String	getTagQualifierValue(java.lang.String RS) Example: tag=span;propertycontains=innerHTML:some value
static java.lang.String	getText(org.openqa.selenium.WebElement webelement) Attempts to retrieve a text value for the WebElement.
protected static java.lang.String	getThrowableMessages(java.lang.Throwable th)
static java.lang.Object	getValue(org.openqa.selenium.WebElement webelement, java.lang.String... attributes) Get a value from the WebElement according to the attributes. The first non-null-value of the attributes will be returned, so the order of attributes may affect the result.
static org.openqa.selenium.WebDriver	getWebDriver() Get the last used "current" WebDriver.
protected static org.openqa.selenium.WebDriver	getWebDriver(java.lang.String id) At this time does NOT set the retrieved WebDriver to be the "current" or "lastUsed" WebDriver.
protected static org.openqa.selenium.WebDriver	getWebDriverWithTitle(java.lang.String title)
protected static org.openqa.selenium.WebElement	getWebElement(org.openqa.selenium.SearchContext sc, java.lang.String tagName, int index) Find the Nth tag in the search context.
static java.lang.Object	getWebElementProperty(org.openqa.selenium.WebElement element, java.lang.String property) Return the specified property of a WebElement. For example, we can get the parentNode of a WebElement by calling this method with "parentNode" as the property.
protected static java.lang.String	getXpathCondition(java.lang.String propertyValuePairStr, boolean partialMatch)
static boolean	highlight(java.lang.String idOrNameOrXpath) Highlight the webelement by drawing a red rectangle around it.
static boolean	highlight(org.openqa.selenium.WebElement webelement) Highlight the webelement by drawing a red rectangle around it. To clean the red rectangle, please call clearHighlight().
static boolean	highlightThenClear(org.openqa.selenium.WebElement webelement, int duration) Highlight the webelement by drawing a red rectangle around it.
static boolean	isDisplayed(org.openqa.selenium.WebElement element) Check if the webelement is displayed (Selenium's API isDisplayed()).
static boolean	isDojoDomain(org.openqa.selenium.WebElement element) To test if the WebElement belongs to DOJO Domain.
protected static boolean	isFrameRS(java.lang.String recognitionString)
static boolean	isFrameWebElement(org.openqa.selenium.WebElement frameTag)
static boolean	isIgnoredNonUITag(java.lang.String tag)
static boolean	isSAPDomain(org.openqa.selenium.WebElement element) To test if the WebElement belongs to SAP OPENUI5 Domain.
static boolean	isStale(org.openqa.selenium.WebElement element) Test if a WebElement is stale(DOM element is deleted or is repaint or disappear).
static boolean	isValidBrowserID(java.lang.String ID) if the id is valid (not null and not empty).
static boolean	isValidFrameRS(java.lang.String frameRS)
static boolean	isVisible(org.openqa.selenium.WebElement element) Get the visibility of the webelement. Try Selenium's API isDisplayed() firstly, if it is false then try to test value of attribute 'visibility'.
static void	js_cleanError() Clean the global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_CODE_VAR, reset it value to JavaScriptFunctions.ERROR_CODE_NOT_SET.
protected static java.lang.Object	js_executeWithTimeout(java.lang.String js, long msTimeout)
static int	js_getErrorCode() Get the value of global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_CODE_VAR.
static java.lang.Object	js_getErrorObject() Get the value of global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_OBJECT_VAR.
static boolean	js_getGlobalBoolVariable(java.lang.String variable) Get the boolean value of a javascript global variable.
static java.lang.Object	js_getGlobalVariable(java.lang.String variable) Get the value of a javascript global variable.
static void	js_initError() Initialize the global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_CODE_VAR, set it value to JavaScriptFunctions.ERROR_CODE_NOT_SET.
protected static void	js_initialize() Execute javascript to initialize global javascript variables.
static void	js_setErrorCode(int error) Set the value of global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_CODE_VAR
static void	js_setErrorObject(java.lang.String errorMessage) Set a string value to global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_OBJECT_VAR
static void	js_setGlobalBoolVariable(java.lang.String variable, boolean onOrOff) Get the value for a javascript global boolean variable.
static void	js_setGlobalVariable(java.lang.String variable, java.lang.String value) Set the value for a javascript global variable.
static boolean	pageHasChanged() To detect if the page has changed or not. For example, if user click on a link, or a Log-Out menu item, the page may probably change. The current implementation is not guarantee!
protected static org.openqa.selenium.WebDriver	reconnectLastWebDriver() Will only connect to the "current" session.
static void	refreshJSExecutor() Use the lastUsedWD to refresh the lastJS.
static void	removeJavaScriptEventListener(org.openqa.selenium.WebElement element, java.lang.String eventName, java.lang.String listenerID) Note: It is important to call this method in a finally clause to make sure that the polling thread stop.
protected static org.openqa.selenium.WebDriver	removeWebDriver(java.lang.String id) Removes the provided webdriver from internal storage and deletes the session info in the RemoteDriver.
static void	resetXPathObjectCache() reset the internal xpath object cache for a new round of full xpath generation.
protected static java.lang.String	retrieveFrameRS(java.lang.String recognitionString) if the frame-RS is specified as one qualifier of RS, find and return it. For example, for "FrameID=yyy;property=xxx;property=xxx", we return "FrameID=yyy" The rest "property=xxx;property=xxx" is not useful for now, as FrameId, FrameName and FrameXpath, they are enough to find a frame.
protected static void	setJsExecutionDelay(int milliseconds) NOTE:Sometimes we needs to wait for the WEB page FULLY loaded so that the javascript code can return correctly. Please set this delay back to DEFAULT_JS_EXECUTION_DELAY after a special javascript call, otherwise the performance of the SeleniumPlus framework will be slowed down.
static void	setJsTimeout(long jsTimeout) Set the timeout for javascript code to execute.
static void	setLastFrame(SearchObject.FrameElement lastFrame) Note: User should be very careful when calling this method, it will change the whole searching context!!! Set the frame object where the current GUI-component locate.
static void	shutdown() Currently, shutdown will "quit()" every webdriver that is stored here.
static boolean	switchFrame(org.openqa.selenium.WebDriver webdriver, java.lang.String frameRS) Switch to a certain frame according to the parameter frameRS. Note: User should be extremely careful to call this method, which will change the frame to search within. Note: Before calling this method, make sure that webdriver.switchTo().defaultContent() is called.
static boolean	switchWindow(java.lang.String title, boolean... optionals) Switch to a certain window according to its title, this method will search it from all opened browsers. NOTE: Once successfully switched, lastUsedWD, lastJS may probably get changed.
static boolean	switchWindow(java.lang.String title, int expectedMatchIndex, boolean... optionals) Switch to a certain window according to its title, this method will search it from all opened browsers. NOTE: Once successfully switched, lastUsedWD, lastJS may probably get changed.
static boolean	switchWindow(java.lang.String browserID, java.lang.String title, boolean... optionals) Switch to a certain window according to its title within browser identified by parameter 'browserID'. NOTE: Once successfully switched, lastUsedWD, lastJS may probably get changed.
static int	switchWindow(java.lang.String browserID, java.lang.String title, int expectedMatchIndex, boolean... optionals) Switch to a certain window according to its title within browser identified by parameter 'browserID'. NOTE: Once successfully switched, lastUsedWD, lastJS may probably get changed.
static void	useBrowser(java.lang.String ID) Switch to browser indicated by ID.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TEXT_VALUE_ATTRIBUTES

public static final java.lang.String[] TEXT_VALUE_ATTRIBUTES

"value","text","placeholder". An array of attribute used as component's text content.

See Also:

getValue(WebElement, String...)

lastUsedWD

protected static org.openqa.selenium.WebDriver lastUsedWD

The Selenium 'WebDriver' currently used to manipulate the browser.

lastJS

protected static org.openqa.selenium.JavascriptExecutor lastJS

The Selenium 'JavascriptExecutor' currently used to execute javascript on the browser.

lastFrame

protected static SearchObject.FrameElement lastFrame

The frame object where the current GUI-component locate. If there is no frame, its value should be null.

See Also:

getObject(SearchContext, String)

SEARCH_CRITERIA_FRAMEINDEX

public static final java.lang.String SEARCH_CRITERIA_FRAMEINDEX

FRAMEINDEX, it should be placed in front of normal tokens like ID, CLASS, NAME etc. if exist. NOT recommended to use. Use FRAMEID OR FRAMENAME Instead.

See Also:

Constant Field Values

SEARCH_CRITERIA_FRAMEID

public static final java.lang.String SEARCH_CRITERIA_FRAMEID

FRAMEID, it should be placed in front of normal tokens like ID, CLASS, NAME etc. if exist.

See Also:

Constant Field Values

SEARCH_CRITERIA_IFRAMEID

public static final java.lang.String SEARCH_CRITERIA_IFRAMEID

IFRAMEID, it should be placed in front of normal tokens like ID, CLASS, NAME etc. if exist.

See Also:

Constant Field Values

SEARCH_CRITERIA_FRAMENAME

public static final java.lang.String SEARCH_CRITERIA_FRAMENAME

FRAMENAME, it should be placed in front of normal tokens like ID, CLASS, NAME etc. if exist.

See Also:

Constant Field Values

SEARCH_CRITERIA_FRAMEXPATH

public static final java.lang.String SEARCH_CRITERIA_FRAMEXPATH

FRAMEXPATH, it should be placed in front of normal tokens like ID, CLASS, NAME etc. if exist.

See Also:

Constant Field Values

TAG_FRAME

public static final java.lang.String TAG_FRAME

'frame' tag name

See Also:

Constant Field Values

TAG_IFRAME

public static final java.lang.String TAG_IFRAME

'iframe' tag name

See Also:

Constant Field Values

SEARCH_CRITERIA_TYPE

public static final java.lang.String SEARCH_CRITERIA_TYPE

TYPE

SEARCH_CRITERIA_ID

public static final java.lang.String SEARCH_CRITERIA_ID

ID

SEARCH_CRITERIA_NAME

public static final java.lang.String SEARCH_CRITERIA_NAME

NAME

SEARCH_CRITERIA_TEXT

public static final java.lang.String SEARCH_CRITERIA_TEXT

TEXT

SEARCH_CRITERIA_PATH

public static final java.lang.String SEARCH_CRITERIA_PATH

PATH

SEARCH_CRITERIA_PROPERTY

public static final java.lang.String SEARCH_CRITERIA_PROPERTY

PROPERTY

SEARCH_CRITERIA_PROPERTY_CONTAINS

public static final java.lang.String SEARCH_CRITERIA_PROPERTY_CONTAINS

PROPERTYCONTAINS

SEARCH_CRITERIA_INDEX

public static final java.lang.String SEARCH_CRITERIA_INDEX

INDEX

SEARCH_CRITERIA_CLASS_CONTAINS

public static final java.lang.String SEARCH_CRITERIA_CLASS_CONTAINS

CLASSCONTAINS

SEARCH_CRITERIA_ITEMINDEX

public static final java.lang.String SEARCH_CRITERIA_ITEMINDEX

ITEMINDEX

See Also:

Constant Field Values

SEARCH_CRITERIA_CLASS

public static final java.lang.String SEARCH_CRITERIA_CLASS

CLASS

See Also:

Constant Field Values

SEARCH_CRITERIA_TITLE

public static final java.lang.String SEARCH_CRITERIA_TITLE

TITLE

See Also:

Constant Field Values

SEARCH_CRITERIA_XPATH

public static final java.lang.String SEARCH_CRITERIA_XPATH

XPATH

See Also:

Constant Field Values

SEARCH_CRITERIA_CSS

public static final java.lang.String SEARCH_CRITERIA_CSS

CSS

See Also:

Constant Field Values

SEARCH_CRITERIA_LINK

public static final java.lang.String SEARCH_CRITERIA_LINK

LINK

See Also:

Constant Field Values

SEARCH_CRITERIA_PARTIALLINK

public static final java.lang.String SEARCH_CRITERIA_PARTIALLINK

PARTIALLINK

See Also:

Constant Field Values

SEARCH_CRITERIA_TAG

public static final java.lang.String SEARCH_CRITERIA_TAG

TAG

See Also:

Constant Field Values

SEARCH_CRITERIA_CONTAINS_SUFFIX

public static final java.lang.String SEARCH_CRITERIA_CONTAINS_SUFFIX

"CONTAINS"

See Also:

Constant Field Values

DOMAIN_DOJO

public static final java.lang.String DOMAIN_DOJO

DOJO

See Also:

Constant Field Values

DOMAIN_SAP

public static final java.lang.String DOMAIN_SAP

See Also:

Constant Field Values

DOMAIN_HTML

public static final java.lang.String DOMAIN_HTML

HTML

See Also:

Constant Field Values

INVALID_INDEX

public static final int INVALID_INDEX

See Also:

Constant Field Values

XPATH_CHILD_SEPARATOR

public static final java.lang.String XPATH_CHILD_SEPARATOR

separates parent/child relationships in recognition strings. (Default: "/" )

See Also:

Constant Field Values

childSeparator

public static java.lang.String childSeparator

separates parent/child relationships in recognition strings. (Default: ";\;" )

qulifierSeparator

public static java.lang.String qulifierSeparator

separates multiples qualifiers. (Default: ";" )

assignSeparator

public static java.lang.String assignSeparator

separates type and value for one qualifier. (Default: "=" )

propertySeparator

public static java.lang.String propertySeparator

separates property-name and property-value. (Default: ":" )

escapeChar

public static java.lang.Character escapeChar

the character to escape separators. (Default: '\\' )

IGNORED_NONUI_TAGS

public static final java.lang.String[] IGNORED_NONUI_TAGS

non-ui tags to be ignored in xpath searches and xpath generation. Like: br, head, title, meta, link, script, wbr

lastVisitedURL

protected static java.lang.String lastVisitedURL

The last visited URL,

lastBrowserWindow

protected static SearchObject.BrowserWindow lastBrowserWindow

The last visited browser window

DEFAULT_JS_TIMEOUT

public static final long DEFAULT_JS_TIMEOUT

'5000' milliseconds

See Also:

Constant Field Values

jsEventListenerMap

protected static java.util.Map<java.lang.String,SearchObject.GenericJSEventListener> jsEventListenerMap

A map containing pairs of (listenerID, listener). The listener will respond to a javasript event.

jsEventListenerWaitingThreadMap

protected static java.util.Map<java.lang.String,org.safs.selenium.webdriver.lib.SearchObject.PollingRunnable> jsEventListenerWaitingThreadMap

A map containing pairs of (listenerID, PollingRunnable). The PollingRunnable will check a javascript
variable in a loop, when the variable is true, it will invoke the listener according to the listenerID.

DEFAULT_JS_EXECUTION_DELAY

public static final int DEFAULT_JS_EXECUTION_DELAY

0

See Also:

Constant Field Values

CSS_SELECTOR_BY_ID

public static final java.lang.String CSS_SELECTOR_BY_ID

See Also:

Constant Field Values

CSS_SELECTOR_BY_CLASSNAME

public static final java.lang.String CSS_SELECTOR_BY_CLASSNAME

See Also:

Constant Field Values

CSS_CLASS_SEPARATOR

public static final java.lang.String CSS_CLASS_SEPARATOR

' '

See Also:

Constant Field Values

CSS_CLASS_SAP_PREFIX

public static final java.lang.String CSS_CLASS_SAP_PREFIX

'sap'

See Also:

Constant Field Values

CSS_CLASS_DOJO_DIJIT_PREFIX

public static final java.lang.String CSS_CLASS_DOJO_DIJIT_PREFIX

'dijit'

See Also:

Constant Field Values

MATCHED_ZERO_TIMES

public static final int MATCHED_ZERO_TIMES

0 integer zero

See Also:

Constant Field Values

MATCHED_ONE_TIME

public static final int MATCHED_ONE_TIME

1 integer one

See Also:

Constant Field Values

DEFAULT_PARTIAL_MATCH

public static final boolean DEFAULT_PARTIAL_MATCH

false

See Also:

Constant Field Values

DEFAULT_IGNORE_CASE

public static final boolean DEFAULT_IGNORE_CASE

true

See Also:

Constant Field Values

Constructor Detail

SearchObject

public SearchObject()

Method Detail

getLastFrame

public static SearchObject.FrameElement getLastFrame()

The frame object where the current GUI-component locate. If there is no frame, its value should be null.

See Also:

getObject(SearchContext, String)

setLastFrame

public static void setLastFrame(SearchObject.FrameElement lastFrame)

Note: User should be very careful when calling this method, it will change the whole searching context!!!
Set the frame object where the current GUI-component locate. If a null value is set, then there is no frame to switch and object will be searched in default document (webdriver.switchTo().defaultContent()).

See Also:

getObject(SearchContext, String)

getLastVisitedURL

public static java.lang.String getLastVisitedURL()

getLastBrowserWindow

public static SearchObject.BrowserWindow getLastBrowserWindow()

shutdown

public static void shutdown()
                     throws java.lang.Throwable

Currently, shutdown will "quit()" every webdriver that is stored here. Ideally, we do NOT want to quit instances that are running attached to a Selenium Server--whether it is remote or local.

Throws:

java.lang.Throwable

isIgnoredNonUITag

public static boolean isIgnoredNonUITag(java.lang.String tag)

Parameters:

tag -

Returns:

true if the provided tag is in the list of nonui tags to be ignored for xpath

See Also:

IGNORED_NONUI_TAGS

addWebDriver

protected static org.openqa.selenium.WebDriver addWebDriver(java.lang.String id,
                                                            org.openqa.selenium.WebDriver wd)

Store the WebDriver in the Hashtable by id.
This also sets this WebDriver as the "current" or "lastUsed" WebDriver. If there exists already a WebDriver in the Hashtable with the same id, it will be replaced by the new one,
and the old one will be returned. User will decide how to handle the old one, either store it with an other id
or simply stop it by calling WebDriver.quit()

Parameters:

id - String, the key for the WebDriver to store in the Hashtable.
if user provides null, then the hashcode of WebDriver will be used as key.

wd - WebDriver, the WebDriver to store in the Hashtable.

Returns:

WebDriver, the previous WebDriver stored in the Hashtable with the same id; null if no such WebDriver exists.

useBrowser

public static void useBrowser(java.lang.String ID)
                       throws SeleniumPlusException

Switch to browser indicated by ID. It will get the cached webdriver according to the browser's id
and set it to the lastUsedWD and set the lastJS if possible.

Parameters:

ID - String, the id to identify the browser

Throws:

SeleniumPlusException

getWebDriver

protected static org.openqa.selenium.WebDriver getWebDriver(java.lang.String id)

At this time does NOT set the retrieved WebDriver to be the "current" or "lastUsed" WebDriver.

Parameters:

id - String, the ID for the WebDriver stored in the Hashtable.
if user provides null, then the last used WebDriver will be returned.

Returns:

WebDriver, the WebDriver associated with id; null if no WebDriver is found.

getWebDriverWithTitle

protected static org.openqa.selenium.WebDriver getWebDriverWithTitle(java.lang.String title)

Parameters:

title - String, the case-insensitive title within the WebDriver stored in the Hashtable.
if user provides null or a zero-length title then the last used WebDriver will be returned.
the routine does not (yet) set the found WebDriver to be the lastUsedWD. That might change, though.

Returns:

WebDriver, the WebDriver associated with the browser title; null if no matching WebDriver is found.

getIDForWebDriver

public static java.lang.String getIDForWebDriver(org.openqa.selenium.WebDriver wd)

At this time does NOT set the processed WebDriver to be the "current" or "lastUsed" WebDriver.

Parameters:

wd - WebDriver to get our stored ID of.

Returns:

String ID of the WebDriver, or null if not found.

getAllWindowTitles

public static java.lang.String[] getAllWindowTitles()

Returns:

String[] of all known WebDriver window titles, or an empty array.

reconnectLastWebDriver

protected static org.openqa.selenium.WebDriver reconnectLastWebDriver()

Will only connect to the "current" session. Normally only called after a catastrophic failure of a RemoteDriver.

Returns:

getWebDriver

public static org.openqa.selenium.WebDriver getWebDriver()

Get the last used "current" WebDriver. If we do not have a last used WebDriver, we will attempt to process the remote session file to reconnect existing webdriver sessions and return the one that was stored as the last used session.

Returns:

WebDriver, the lastUsed WebDriver or null if no WebDriver was found.

isValidBrowserID

public static boolean isValidBrowserID(java.lang.String ID)

if the id is valid (not null and not empty).

Parameters:

ID - String, the browser id.

Returns:

boolean true if the browser id is valid (not null and not empty).

removeWebDriver

protected static org.openqa.selenium.WebDriver removeWebDriver(java.lang.String id)

Removes the provided webdriver from internal storage and deletes the session info in the RemoteDriver. Will pop off the next "lastUsed" WebDriver off the stack and set it as the new "lastUsed" WebDriver and sets the RemoteDriver "lastSessionId" as needed.

Parameters:

id - String, the ID for the WebDriver to remove
if it is NOT isValidBrowserID(String), then the last used WebDriver will be removed.

Returns:

WebDriver, the WebDriver has been removed; null if no WebDriver is removed.

findElement

public static org.openqa.selenium.WebElement findElement(org.openqa.selenium.By by)

getObject

public static org.openqa.selenium.WebElement getObject(java.lang.String RS)

Get the object based on the recognition string. Currently, the routine assumes the recognition string is for an item in the lastUsedWD--the last used WebDriver. This routine will be modified to detect a recognition string that may include the need to locate which WebDriver is the right one and not assume the last one is the right one.

Parameters:

RS -

Returns:

See Also:

getObject(SearchContext, String)

containTagRS

public static boolean containTagRS(java.lang.String rs)

Parameters:

rs -

Returns:

true if the RS contains a qualifier of "TAG=value" (case-insensitive comparison)

containFrameRS

public static boolean containFrameRS(java.lang.String rs)

isValidFrameRS

public static boolean isValidFrameRS(java.lang.String frameRS)

isFrameRS

protected static boolean isFrameRS(java.lang.String recognitionString)

Parameters:

recognitionString - String

Returns:

boolean, true if the RS is a kind of frame-RS

retrieveFrameRS

protected static java.lang.String retrieveFrameRS(java.lang.String recognitionString)

if the frame-RS is specified as one qualifier of RS, find and return it.
For example, for "FrameID=yyy;property=xxx;property=xxx", we return "FrameID=yyy"
The rest "property=xxx;property=xxx" is not useful for now, as FrameId, FrameName
and FrameXpath, they are enough to find a frame.

Parameters:

recognitionString - String

Returns:

String, the frame-RS

switchFrame

public static boolean switchFrame(org.openqa.selenium.WebDriver webdriver,
                                  java.lang.String frameRS)

Switch to a certain frame according to the parameter frameRS.
Note: User should be extremely careful to call this method, which will change the frame to search within.
Note: Before calling this method, make sure that webdriver.switchTo().defaultContent() is called.

Parameters:

webdriver - WebDriver, the webdriver used to search frame and switch frame

frameRS - String, the recognition string of the frame

getTagQualifierValue

protected static java.lang.String getTagQualifierValue(java.lang.String RS)
                                                throws com.thoughtworks.selenium.SeleniumException

Example: tag=span;propertycontains=innerHTML:some value

Parameters:

RS - -- Full MultiAttribute qualifier RS. (Does not have to be a single qualifier assignment segment.) The algorithm does NOT assume the TAG qualifier is first in the RS.

Returns:

the value associated with any TAG= qualifier setting, or null if it does not exist.

Throws:

com.thoughtworks.selenium.SeleniumException

getFirstQualifierPair

protected static java.lang.String[] getFirstQualifierPair(java.lang.String RS)
                                                   throws com.thoughtworks.selenium.SeleniumException

Split a string by separator assignSeparator, and return the result.
If the RS contains multiple assignSeparator, this method will ONLY
consider the first separator, the string before that separator will be considered
as qualifier; the string after will be all considered as value.

Parameters:

RS - String, a recognition with a assignSeparator inside.

Returns:

String[], the separated RS, including qualifier and value.

Throws:

com.thoughtworks.selenium.SeleniumException - if the RS is not valid.

pageHasChanged

public static boolean pageHasChanged()

To detect if the page has changed or not.
For example, if user click on a link, or a Log-Out menu item, the page may probably change.
The current implementation is not guarantee!

Returns:

boolean, if the page has changed.

_switchFrames

protected static SearchObject.SwitchFramesResults _switchFrames(java.lang.String recognitionString)

Before doing any component search, we make sure we are in the correct frame. Frame information may or may not be within the provided recognition string.

Parameters:

recognitionString -

getObject

public static org.openqa.selenium.WebElement getObject(org.openqa.selenium.SearchContext sc,
                                                       java.lang.String recognitionString)

Primary entry point to seek a WebElement based on a provided recognition string. We support multiple types of recognition strings

Parameters:

sc - SearchContext, could be the WebDriver or a parent WebElement context.

recognitionString - String, The recognition string used to identify the sought element.

Returns:

WebElement found or null if not found.

getObjects

public static java.util.List<org.openqa.selenium.WebElement> getObjects(org.openqa.selenium.SearchContext sc,
                                                                        java.lang.String recognitionString)

Primary entry point to seek all WebElements matching a provided recognition string. We support multiple types of recognition strings

Parameters:

sc - SearchContext, could be the WebDriver or a parent WebElement context.

recognitionString - String, The recognition string used to identify the matching elements.

Returns:

List<WebElement> with 0 or more WebElement entries.

isFrameWebElement

public static boolean isFrameWebElement(org.openqa.selenium.WebElement frameTag)

getFrameWebElement

protected static org.openqa.selenium.WebElement getFrameWebElement(org.openqa.selenium.SearchContext sc,
                                                                   int index)

Find the Nth frame webelement in the search context.

Parameters:

sc - SearchContext, the search context, SHOULD be WebDriver

index - int, the index of the tag, 1-based

Returns:

WebElement, the webelement or null if not found

getWebElement

protected static org.openqa.selenium.WebElement getWebElement(org.openqa.selenium.SearchContext sc,
                                                              java.lang.String tagName,
                                                              int index)

Find the Nth tag in the search context.

Parameters:

sc - SearchContext, the search context

tagName - String, the tag name to find

index - int, the index of the tag, 1-based

Returns:

WebElement, the webelement or null if not found

findElements

protected static java.util.List<org.openqa.selenium.WebElement> findElements(org.openqa.selenium.SearchContext wel,
                                                                             java.lang.String xpath)

getObjectByText

protected static org.openqa.selenium.SearchContext getObjectByText(org.openqa.selenium.SearchContext wel,
                                                                   java.lang.String text,
                                                                   boolean partialMatch)

getObjectsByText

protected static java.util.List<org.openqa.selenium.WebElement> getObjectsByText(org.openqa.selenium.SearchContext wel,
                                                                                 java.lang.String text,
                                                                                 boolean partialMatch)

Returns:

0 or more matched elements

getObjectByTitle

protected static org.openqa.selenium.SearchContext getObjectByTitle(org.openqa.selenium.SearchContext wel,
                                                                    java.lang.String value,
                                                                    boolean partialMatch)

getObjectsByTitle

protected static java.util.List<org.openqa.selenium.WebElement> getObjectsByTitle(org.openqa.selenium.SearchContext wel,
                                                                                  java.lang.String value,
                                                                                  boolean partialMatch)

Returns:

0 or more matched elements

getMatchedObject

protected static org.openqa.selenium.SearchContext getMatchedObject(java.util.List<org.safs.selenium.webdriver.lib.SearchObject.WebElementWarpper> elements,
                                                                    java.lang.String value,
                                                                    boolean partialMatch)

Parameters:

elements - List<WebElementWarpper>, contains WebElement to match

value - String, the value to match with

partialMatch - boolean, if we try to find the partial matched item

Returns:

SearchContext, the matched object

getMatchedObjects

protected static java.util.List<org.openqa.selenium.WebElement> getMatchedObjects(java.util.List<org.safs.selenium.webdriver.lib.SearchObject.WebElementWarpper> elements,
                                                                                  java.lang.String value,
                                                                                  boolean partialMatch)

Parameters:

elements - List<WebElementWarpper>, contains WebElements to match

value - String, the value to match with

partialMatch - boolean, if we try to find the partial matched item

Returns:

List<WebElement> 0 or more matched WebElements.

getObjectByQualifier

protected static org.openqa.selenium.SearchContext getObjectByQualifier(org.openqa.selenium.SearchContext sc,
                                                                        java.lang.String qualifier,
                                                                        java.lang.String value)
                                                                 throws SeleniumPlusException

According to pair(qualifier, value), find the matched WebElement.
Some qualifiers like "ID", can determine the WebElement uniquely and result
only one WebElement; Other qualifiers may result several WebElement, the first
one will be returned.

Parameters:

sc - SearchContext, the search context, it is normally a WebElement.

qualifier - String, the qualifier like xpath, css, id, name, link etc.

value - String, the value of a qualifier.

Returns:

SearchContext, the WebElment found according to qualifier and its value.

Throws:

SeleniumPlusException

getObjectsByQualifier

protected static java.util.List<org.openqa.selenium.WebElement> getObjectsByQualifier(org.openqa.selenium.SearchContext sc,
                                                                                      java.lang.String qualifier,
                                                                                      java.lang.String value)
                                                                               throws SeleniumPlusException

According to pair(qualifier, value), find all matching WebElements.
Some qualifiers like "ID", can determine the WebElement uniquely and result
only one WebElement; Other qualifiers may result in several WebElements.

Parameters:

sc - SearchContext, the search context, it is normally a WebElement.

qualifier - String, the qualifier like xpath, css, id, name, link etc.

value - String, the value of a qualifier.

Returns:

List<WebElement> 0 or more

Throws:

SeleniumPlusException

getObjectByMultiAttributes

protected static org.openqa.selenium.SearchContext getObjectByMultiAttributes(org.openqa.selenium.SearchContext sc,
                                                                              java.lang.String RS,
                                                                              boolean isPASM)

 Builds an XPath search string using multiple attributes provided in the recognition string
 then performs a findElement(By.xpath(string));
 If the recognition string contains special attributes, How to tell them from normal attributes???

 

Parameters:

sc - SearchContext, the search context

RS - String, the recognition string

isPASM - boolean, if true, each part of 'recognition string' will be treated as property.
if false, some reserved words will be treated as qualifiers, but not properties.
the reserved words are SEARCH_CRITERIA_ITEMINDEX, SEARCH_CRITERIA_PATH etc.

Returns:

SearchContext (WebElement or WebDriver)

getObjectsByMultiAttributes

protected static java.util.List<org.openqa.selenium.WebElement> getObjectsByMultiAttributes(org.openqa.selenium.SearchContext sc,
                                                                                            java.lang.String RS,
                                                                                            boolean isPASM)

 Builds an XPath search string using multiple attributes provided in the recognition string
 then performs a findElements(By.xpath(string));
 If the recognition string contains special attributes, How to tell them from normal attributes???

 

Parameters:

sc - SearchContext, the search context

RS - String, the recognition string

isPASM - boolean, if true, each part of 'recognition string' will be treated as property.
if false, some reserved words will be treated as qualifiers, but not properties.
the reserved words are SEARCH_CRITERIA_ITEMINDEX, SEARCH_CRITERIA_PATH etc.

Returns:

List<WebElement> with 0 or more matching elements.

getSubItem

protected static org.openqa.selenium.WebElement getSubItem(org.openqa.selenium.WebElement itemContainer,
                                                           TextMatchingCriterion criterion)

According to TextMatchingCriterion to get the sub item within a container WebElement.

Parameters:

itemContainer - WebElement, the container WebElement, like list, menu etc.

criterion - TextMatchingCriterion, holding the searching condition

Returns:

WebElement, the matched sub item webelement

getObjectByXpathAndQualifiers

protected static org.openqa.selenium.WebElement getObjectByXpathAndQualifiers(org.openqa.selenium.SearchContext sc,
                                                                              java.lang.String xpathStr,
                                                                              java.util.HashMap<java.lang.String,java.lang.String> qualifiers)

According to xpath and qualifiers to find the WebElement.

Parameters:

sc - SearchContext, the search context, it is normally a WebElement.

xpathStr - String, the xpath used to find a WebElment

qualifiers - HashMap, qualifiers and their values used to find a WebElement

Returns:

WebElement

getObjectsByXpathAndQualifiers

protected static java.util.List<org.openqa.selenium.WebElement> getObjectsByXpathAndQualifiers(org.openqa.selenium.SearchContext sc,
                                                                                               java.lang.String xpathStr,
                                                                                               java.util.HashMap<java.lang.String,java.lang.String> qualifiers)

According to xpath and qualifiers to find matching WebElements.
While returning a List, it is likely the List will have only 1 matching item.

Parameters:

sc - SearchContext, the search context, it is normally a WebElement.

xpathStr - String, the xpath used to find matching WebElements

qualifiers - HashMap, qualifiers and their values used to find matching WebElement subItems.

Returns:

List<WebElement> 0 or more WebElements.

getNthWebElement

protected static org.openqa.selenium.WebElement getNthWebElement(java.util.List<org.openqa.selenium.WebElement> preMatches,
                                                                 int matchindex,
                                                                 java.lang.String typeInSAFS)

Find the Nth matched WebElement in a list.

Parameters:

preMatches - List<WebElement>, a list of WebElment from where to find a matched Element

matchindex - int, the expected index, 1-based

typeInSAFS - String, the expected type, like "Button", "List", "CheckBox". If null, match all elements.

Returns:

WebElement, the Nth matched WebElement. null if not found.

getObjectForDomain

protected static org.openqa.selenium.WebElement getObjectForDomain(org.openqa.selenium.SearchContext sc,
                                                                   java.lang.String RS,
                                                                   boolean isPropertyAllMode)

Alternate search for special framework elements like Dojo or SAP OpenUI5 components.

Parameters:

sc - SearchContext, the search context

RS - String, the recognition string

isPropertyAllMode - boolean, if true, each part of 'recognition string' will be treated as property.
if false, some reserved words will be treated as qualifiers, but not properties.
the reserved words are SEARCH_CRITERIA_ITEMINDEX, SEARCH_CRITERIA_PATH etc.

Returns:

WebElement or null if no match found.

getObjectsForDomain

protected static java.util.List<org.openqa.selenium.WebElement> getObjectsForDomain(org.openqa.selenium.SearchContext sc,
                                                                                    java.lang.String RS,
                                                                                    boolean isPropertyAllMode)

Alternate search for special framework elements like Dojo or SAP OpenUI5 components.

Parameters:

sc - SearchContext, the search context

RS - String, the recognition string

isPropertyAllMode - boolean, if true, each part of 'recognition string' will be treated as property.
if false, some reserved words will be treated as qualifiers, but not properties.
the reserved words are SEARCH_CRITERIA_ITEMINDEX, SEARCH_CRITERIA_PATH etc.

Returns:

List<WebElement> 0 or more matching WebElements.

getXpathCondition

protected static java.lang.String getXpathCondition(java.lang.String propertyValuePairStr,
                                                    boolean partialMatch)

Parameters:

propertyValuePairStr - String, the pair representing property and value, like property:value, separated by propertySeparator

partialMatch - boolean, if the property's value will be matched partially (considered as a substring)

Returns:

String, the xpath condition for searching

See Also:

#getXpathCondition(String, String, boolean)

getBoolean

public static boolean getBoolean(org.openqa.selenium.WebElement webelement,
                                 java.lang.String... attributes)

Get a boolean value from the WebElement according to the attributes.

Parameters:

webelement - WebElement, the WebElement to get value of an attribute.

attributes - String..., an array of attribute to get value for.

Returns:

boolean true if one of the attribute contains true value.

getText

public static java.lang.String getText(org.openqa.selenium.WebElement webelement)

Attempts to retrieve a text value for the WebElement. This is by combining webelement.getText() and our own getValue() and returning whichever gets us a text value.

Parameters:

webelement - WebElement, the web element to get text from.

Returns:

String, the element's text content

getValue

public static java.lang.Object getValue(org.openqa.selenium.WebElement webelement,
                                        java.lang.String... attributes)

Get a value from the WebElement according to the attributes.
The first non-null-value of the attributes will be returned, so the order
of attributes may affect the result.

Parameters:

webelement - WebElement, the WebElement to get value of an attribute.

attributes - String..., an array of attribute to get value for.

Returns:

Object the first non-null-value of the attributes; or null if all attributes have null value.

See Also:

TEXT_VALUE_ATTRIBUTES

js_getGlobalBoolVariable

public static boolean js_getGlobalBoolVariable(java.lang.String variable)
                                        throws java.lang.IllegalStateException

Get the boolean value of a javascript global variable.

Parameters:

variable - String, the name of the global variable.

Returns:

boolean, the value of javascript global variable.

Throws:

java.lang.IllegalStateException - if the value is NOT present or attainable.

See Also:

js_getGlobalVariable(String)

setJsTimeout

public static void setJsTimeout(long jsTimeout)

Set the timeout for javascript code to execute.

Parameters:

jsTimeout - long, timeout in milliseconds for the javascript execution to finish

See Also:

js_getErrorCode(), js_getErrorObject(), js_getGlobalVariable(String)

getJsTimeout

public static long getJsTimeout()

js_executeWithTimeout

protected static java.lang.Object js_executeWithTimeout(java.lang.String js,
                                                        long msTimeout)
                                                 throws SeleniumPlusException,
                                                        java.lang.InterruptedException

Parameters:

js - String, the javascript code to execute

msTimeout - long, the timeout in milliseconds for the javascript execution

Returns:

Object, the javascript execution result

Throws:

SeleniumPlusException - if the timeout has been reached

java.lang.InterruptedException - if the thread (executing javascript) has been interrupted

js_getGlobalVariable

public static java.lang.Object js_getGlobalVariable(java.lang.String variable)

Get the value of a javascript global variable.

Parameters:

variable - String, the name of the global variable.

Returns:

Object, the value of javascript global variable.

Throws:

java.lang.IllegalStateException - if the value is NOT present or attainable.

js_setGlobalBoolVariable

public static void js_setGlobalBoolVariable(java.lang.String variable,
                                            boolean onOrOff)

Get the value for a javascript global boolean variable.

Parameters:

variable - String, the name of the global variable.

onOrOff - boolean, the value to set

See Also:

js_setGlobalVariable(String, String)

js_setGlobalVariable

public static void js_setGlobalVariable(java.lang.String variable,
                                        java.lang.String value)

Set the value for a javascript global variable.

Parameters:

variable - String, the name of the global variable.

value - String, the value to set

js_initialize

protected static void js_initialize()

Execute javascript to initialize global javascript variables.

See Also:

WDLibrary.startBrowser(String, String, String, int, boolean, Map)

js_initError

public static void js_initError()
                         throws SeleniumPlusException

Initialize the global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_CODE_VAR,
set it value to JavaScriptFunctions.ERROR_CODE_NOT_SET.
Initialize the global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_OBJECT_VAR to undefined.

Throws:

SeleniumPlusException

js_cleanError

public static void js_cleanError()
                          throws SeleniumPlusException

Clean the global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_CODE_VAR,
reset it value to JavaScriptFunctions.ERROR_CODE_NOT_SET.
Clean the global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_OBJECT_VAR, reset it to undefined.

Throws:

SeleniumPlusException

js_getErrorCode

public static int js_getErrorCode()
                           throws SeleniumPlusException

Get the value of global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_CODE_VAR.

Throws:

SeleniumPlusException

js_setErrorCode

public static void js_setErrorCode(int error)
                            throws SeleniumPlusException

Set the value of global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_CODE_VAR

Throws:

SeleniumPlusException

js_getErrorObject

public static java.lang.Object js_getErrorObject()
                                          throws SeleniumPlusException

Get the value of global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_OBJECT_VAR.

Throws:

SeleniumPlusException

js_setErrorObject

public static void js_setErrorObject(java.lang.String errorMessage)
                              throws SeleniumPlusException

Set a string value to global variable JavaScriptFunctions.SAFS_JAVASCRIPT_GLOBAL_ERROR_OBJECT_VAR

Throws:

SeleniumPlusException

highlightThenClear

public static boolean highlightThenClear(org.openqa.selenium.WebElement webelement,
                                         int duration)

Highlight the webelement by drawing a red rectangle around it.

Parameters:

webelement - WebElement, the web element to highlight.

duration - int, how long in millisecond the red rectangle will stay.

Returns:

boolean, true if the element is highlighted and then cleaned.

See Also:

highlight(WebElement), clearHighlight()

highlight

public static boolean highlight(java.lang.String idOrNameOrXpath)

Highlight the webelement by drawing a red rectangle around it.

Parameters:

idOrNameOrXpath - String, the id or name or xpath of web element to highlight.

Returns:

boolean, true if the element is highlighted.

highlight

public static boolean highlight(org.openqa.selenium.WebElement webelement)

Highlight the webelement by drawing a red rectangle around it.
To clean the red rectangle, please call clearHighlight().

Parameters:

webelement - WebElement, the web element to highlight.

Returns:

boolean, true if the element is highlighted.

See Also:

clearHighlight()

clearHighlight

public static boolean clearHighlight()

clear the previous highlight of a webelement.
Note:The webelement should be highlighted by highlight(String)
or highlight(WebElement), normally you don't need to call this method
to clear the highlight if you want to highlight element one by one continuously, as
the previous highlighted element will be automatically cleared before next element
is highlighted.

Returns:

boolean, true if the element's highlight has been cleared.

See Also:

highlight(String), highlight(WebElement)

isVisible

public static boolean isVisible(org.openqa.selenium.WebElement element)
                         throws SeleniumPlusException

Get the visibility of the webelement.
Try Selenium's API isDisplayed() firstly, if it is false then try to test value of attribute 'visibility'.

Parameters:

element - WebElement

Returns:

true if the webelement is visible

Throws:

SeleniumPlusException - if the WebElement is null

See Also:

isDisplayed(WebElement)

isDisplayed

public static boolean isDisplayed(org.openqa.selenium.WebElement element)
                           throws SeleniumPlusException

Check if the webelement is displayed (Selenium's API isDisplayed()).

Parameters:

element - WebElement, the element to check.

Returns:

true if the webelement is visible

Throws:

SeleniumPlusException - if the WebElement is null or is stale

See Also:

isVisible(WebElement)

isStale

public static boolean isStale(org.openqa.selenium.WebElement element)
                       throws SeleniumPlusException

Test if a WebElement is stale(DOM element is deleted or is repaint or disappear).

Parameters:

element - WebElement, the WebElement to detect.

Returns:

boolean true if the WebElement is stale.

Throws:

SeleniumPlusException - if the element is null.

addJavaScriptEventListener

public static java.lang.String addJavaScriptEventListener(org.openqa.selenium.WebElement element,
                                                          java.lang.String eventName,
                                                          SearchObject.GenericJSEventListener listener)
                                                   throws SeleniumPlusException

Parameters:

element - WebElement, the element to which the listener will be added.

eventName - String, event name to attach this listener.

listener - GenericJSEventListener, the listener to respond to fired-event.

Returns:

String, the ID of this listener. Will be used to remove the listener.

Throws:

SeleniumPlusException

removeJavaScriptEventListener

public static void removeJavaScriptEventListener(org.openqa.selenium.WebElement element,
                                                 java.lang.String eventName,
                                                 java.lang.String listenerID)
                                          throws SeleniumPlusException

Note: It is important to call this method in a finally clause to make sure that the polling thread stop.

   String listenerID = null;
   try{
        listenerID = addJavaScriptEventListener(element, eventName, listener);
   }catch(Exception e){
   }finally{
     if(listenerID!=null) removeJavaScriptEventListener(element, eventName, listenerID);
   }
 

Parameters:

element - WebElement, the element from which the listener will be removed.

eventName - String, event name to detach a listener.

String, - the ID of this listener, used to remove a listener.

Throws:

SeleniumPlusException

executeJavaScriptOnWebElement

public static java.lang.Object executeJavaScriptOnWebElement(java.lang.String script,
                                                             org.openqa.selenium.WebElement webelement,
                                                             java.lang.Object... args)
                                                      throws SeleniumPlusException

Parameters:

script - String, the javascript function to execute. Its first parameter is always DOM object.

webelement - WebElement, used to find the DOM Object to operate.
it is passed directly to javascript function and will be considered as a DOM element.

args - Object[], the extra parameters used by the javascript function, from SECOND parameter.

Returns:

Throws:

SeleniumPlusException

executeScript

public static java.lang.Object executeScript(java.lang.String script,
                                             java.lang.Object... args)
                                      throws SeleniumPlusException

Returns:

Object or null.

Throws:

SeleniumPlusException

See Also:

JavascriptExecutor.executeScript(String, Object...), executeScript(boolean, String, Object...)

executeAsyncScript

public static java.lang.Object executeAsyncScript(java.lang.String script,
                                                  java.lang.Object... args)
                                           throws SeleniumPlusException

Returns:

Object or null.

Throws:

SeleniumPlusException

See Also:

JavascriptExecutor.executeAsyncScript(String, Object...), executeScript(boolean, String, Object...)

setJsExecutionDelay

protected static void setJsExecutionDelay(int milliseconds)

NOTE:Sometimes we needs to wait for the WEB page FULLY loaded so that the javascript code can return correctly.
Please set this delay back to DEFAULT_JS_EXECUTION_DELAY after a special javascript call, otherwise the performance of the SeleniumPlus framework will be slowed down.

Parameters:

milliseconds - int, the milliseconds to delay the javascript execution.

See Also:

executeScript(boolean, String, Object...)

getJsExecutionDelay

public static int getJsExecutionDelay()

Returns:

int, the millisecond to delay the javascript's execution.

See Also:

executeScript(boolean, String, Object...)

executeScript

public static java.lang.Object executeScript(boolean synch,
                                             java.lang.String script,
                                             java.lang.Object... args)
                                      throws SeleniumPlusException

Execute a section of java-script code.
It has the ability to detect a javascript error and throw an JSException.

 It is user's responsibility to set javascript global errorcode and errormessage in his
 javascript code, user can call
 JavaScriptFunctions.setJSErrorCode(int)
 JavaScriptFunctions.setJSErrorObject(String)
 for example, see JavaScriptFunctions.SAP#sap_m_List_getItems(boolean).
 

Throws:

SeleniumPlusException - if there is no appropriate JavascriptExecutor to use.

See Also:

JavascriptExecutor.executeScript(String, Object...), JavascriptExecutor.executeAsyncScript(String, Object...)

getJS

public static org.openqa.selenium.JavascriptExecutor getJS()
                                                    throws SeleniumPlusException

Returns:

JavascriptExecutor, the latest valid JavaSc

Throws:

SeleniumPlusException

refreshJSExecutor

public static void refreshJSExecutor()
                              throws SeleniumPlusException

Use the lastUsedWD to refresh the lastJS.

Throws:

SeleniumPlusException - if the lastUsedWD cannot be casted to a JavascriptExecutor

checkNotNull

public static void checkNotNull(java.lang.Object object)
                         throws SeleniumPlusException

Check that the object is not null.

Parameters:

object - Object

Throws:

SeleniumPlusException - will be thrown out with SeleniumPlusException.CODE_OBJECT_IS_NULL if the object is null.

getCssSelector

public static java.lang.String getCssSelector(java.lang.String type,
                                              org.openqa.selenium.WebElement element)

According to the type, generate a css selector for the WebElement.

Parameters:

type - String, the type of the css selector.

element - WebElement, the WebElement from which a css selector will be generated.

Returns:

String, a css selector.

getDescription

static java.lang.String getDescription(org.openqa.selenium.WebElement element)

Return a string to describe a selenium web element.

Parameters:

element - WebElement

Returns:

String,

getWebElementProperty

public static java.lang.Object getWebElementProperty(org.openqa.selenium.WebElement element,
                                                     java.lang.String property)

Return the specified property of a WebElement.
For example, we can get the parentNode of a WebElement by calling this method with "parentNode" as the property.

Parameters:

element - WebElement

property - String property to retrieve.

Returns:

Object to be cast as needed by the specific request, can be null;

getParentWebElement

public static org.openqa.selenium.WebElement getParentWebElement(org.openqa.selenium.WebElement element)

Return the parent WebElement of the provided WebElement.

Parameters:

element - WebElement

Returns:

WebElement parent or null if there is no parent, or an error occurred.

checkCSSClassName

static boolean checkCSSClassName(org.openqa.selenium.WebElement element,
                                 java.lang.String prefix,
                                 java.lang.String separator)

To check if the html tag's css class name containing a certain prefix.

Parameters:

element - WebElement, The selenium web element

prefix - String, the prefix of the css class name

separator - String, the separator in the css class name, normally its a ' '

Returns:

boolean true if the css class name contains a certain prefix.

isSAPDomain

public static boolean isSAPDomain(org.openqa.selenium.WebElement element)
                           throws SeleniumPlusException

To test if the WebElement belongs to SAP OPENUI5 Domain.

Parameters:

element -

Returns:

Throws:

SeleniumPlusException

isDojoDomain

public static boolean isDojoDomain(org.openqa.selenium.WebElement element)
                            throws SeleniumPlusException

To test if the WebElement belongs to DOJO Domain.

Parameters:

element -

Returns:

Throws:

SeleniumPlusException

generateUniqueName

@Deprecated
public static java.lang.String generateUniqueName(java.lang.String prefix)

Deprecated. This method has been moved to StringUtils, we can call StringUtils.generateUniqueName() directly.

Generate a unique name. For example, it can be used as a javascript variable name
when calling functions in JavaScriptFunctions to avoid the conflict with variables defined
in the Application Under Test.

Parameters:

prefix - String, the prefix of the unique name

Returns:

String, the unique name

resetXPathObjectCache

public static void resetXPathObjectCache()

reset the internal xpath object cache for a new round of full xpath generation.

This should be called by external routines getting ready to process an entire page of web elements to avoid processing the same parent nodes many times. This is strictly for performance reasons.

The routine should be called both BEFORE and AFTER the processing of nodes with the recursive generateGenericXPath routine.

See Also:

generateFullGenericXPath(WebElement)

generateFullGenericXPath

public static java.lang.String generateFullGenericXPath(org.openqa.selenium.WebElement element)

Attempt to generate a full generic Xpath string for this element including all parent path information.

Uses generateGenericXPath for each node in the hierarchy.

A caller getting ready to process many web elements--or even just one-should ALWAYS call resetXPathObjectCache before processing that first element and after processing the last element.

Parameters:

element -

Returns:

full xpath to object. null if WebElement provided is null or the xpath cannot be deduced.

See Also:

generateGenericXPath(WebElement), resetXPathObjectCache()

generateGenericXPath

public static java.lang.String generateGenericXPath(org.openqa.selenium.WebElement element)

Attempt to generate a simple Xpath string for this one element without any parent path information.

Currently tries to differentiate the tag name by id, title, or class.

Examples:

div[@id='myid']
div[@title='mytitle']
div[@class='myclass']

if none of those have valid values, then only the tag name is returned. In that case, we check to see if it is the Nth sibling of the same tag type and add that, if needed.

Parameters:

element -

Returns:

generateSAFSFrameRecognition

public static java.lang.String generateSAFSFrameRecognition(java.lang.String framexpath)

Attempt to generate a simple frame recognition string without any parent path information.

Currently tries to differentiate the tag name by id, name, or index.

Parameters:

framexpath - from generateGenericXPath

Returns:

Examples:

frameid='myid'
framename='myname'
frameindex='3'

switchWindow

public static boolean switchWindow(java.lang.String title,
                                   boolean... optionals)
                            throws SeleniumPlusException

Switch to a certain window according to its title, this method will search it from all opened browsers.
NOTE: Once successfully switched, lastUsedWD, lastJS may probably get changed.

Parameters:

title - String, the title of the window to switch to. It can be a normal string, a regexp string or a wildcard string. If it is regexp/wildcard string, the optional parameters will be ignored.

optionals - boolean[]

• optionals[0] partialMatch boolean, if the title is provided as sub-string. The default value is false. It is valid ONLY when title is normal string;
• optionals[1] ignoreCase boolean, if the title are case in-sensitive to compare. The default value is true. It is valid ONLY when title is normal string;

Returns:

boolean true if successfully switched to window matching parameter title

Throws:

SeleniumPlusException

switchWindow

public static boolean switchWindow(java.lang.String title,
                                   int expectedMatchIndex,
                                   boolean... optionals)
                            throws SeleniumPlusException

Switch to a certain window according to its title, this method will search it from all opened browsers.
NOTE: Once successfully switched, lastUsedWD, lastJS may probably get changed.

Parameters:

title - String, the title of the window to switch to. It can be a normal string, a regexp string or a wildcard string. If it is regexp/wildcard string, the optional parameters will be ignored.

expectedMatchIndex - int, the index of matched window if multiple windows match. These windows are ordered according to their title alphabet order. It is 1-based index and should be bigger than MATCHED_ZERO_TIMES

optionals - boolean[]

• optionals[0] partialMatch boolean, if the title is provided as sub-string. The default value is false. It is valid ONLY when title is normal string;
• optionals[1] ignoreCase boolean, if the title are case in-sensitive to compare. The default value is true. It is valid ONLY when title is normal string;

Returns:

boolean true if successfully switched to window matching parameter title

Throws:

SeleniumPlusException

switchWindow

public static boolean switchWindow(java.lang.String browserID,
                                   java.lang.String title,
                                   boolean... optionals)
                            throws SeleniumPlusException

Switch to a certain window according to its title within browser identified by parameter 'browserID'.
NOTE: Once successfully switched, lastUsedWD, lastJS may probably get changed.

Parameters:

browserID - String, the browser ID when calling #startBrowser(String, String, String, int, boolean)

title - String, the title of the window to switch to. It can be a normal string, a regexp string or a wildcard string. If it is regexp/wildcard string, the optional parameters will be ignored.

optionals - boolean[]

• optionals[0] partialMatch boolean, if the title is provided as sub-string. The default value is false. It is valid ONLY when title is normal string;
• optionals[1] ignoreCase boolean, if the title are case in-sensitive to compare. The default value is true. It is valid ONLY when title is normal string;

Returns:

boolean true if successfully switched

Throws:

SeleniumPlusException

switchWindow

public static int switchWindow(java.lang.String browserID,
                               java.lang.String title,
                               int expectedMatchIndex,
                               boolean... optionals)
                        throws SeleniumPlusException

Switch to a certain window according to its title within browser identified by parameter 'browserID'.
NOTE: Once successfully switched, lastUsedWD, lastJS may probably get changed.

Parameters:

browserID - String, the browser ID when calling #startBrowser(String, String, String, int, boolean)

title - String, the title of the window to switch to. It can be a normal string, a regexp string or a wildcard string. If it is regexp/wildcard string, the optional parameters will be ignored.

expectedMatchIndex - int, the index of matched window if multiple windows match. These windows are ordered according to their title alphabet order. It is 1-based index and should be bigger than MATCHED_ZERO_TIMES

optionals - boolean[]

• optionals[0] partialMatch boolean, if the title is provided as sub-string. The default value is false. It is valid ONLY when title is normal string;
• optionals[1] ignoreCase boolean, if the title are case in-sensitive to compare. The default value is true. It is valid ONLY when title is normal string;

Returns:

int the matched times.

Throws:

SeleniumPlusException

getThrowableMessages

protected static java.lang.String getThrowableMessages(java.lang.Throwable th)