com.smartgwt.client.util

Class AutoTest

java.lang.Object

com.smartgwt.client.util.AutoTest

public class AutoTest
extends java.lang.Object

Standalone class providing a general interface for integration with Automated Testing Tools

Constructor Summary

Constructors

Constructor and Description
AutoTest()

Method Summary

Modifier and Type	Method and Description
static QualityIndicatedLocator	getLocatorWithIndicators(com.google.gwt.dom.client.Element DOMElement) Returns the QualityIndicatedLocator associated with some DOM element in a Smart GWT application page.
static QualityIndicatedLocator	getLocatorWithIndicators(com.google.gwt.dom.client.Element DOMElement, boolean checkForNativeHandling)
static QualityIndicatedLocator	getLocatorWithIndicators(com.google.gwt.dom.client.Element DOMElement, boolean checkForNativeHandling, java.lang.String[] coords) Returns the QualityIndicatedLocator associated with some DOM element in a Smart GWT application page.
static java.lang.String	getMinimalLocator(com.google.gwt.dom.client.Element DOMElement) Returns a locator that's optimized to have minimal length while still trying to robustly represent that targeted canvas.
static java.lang.String	getMinimalLocator(com.google.gwt.dom.client.Element DOMElement, boolean checkForNativeHandling)
static java.lang.String	getMinimalLocator(com.google.gwt.dom.client.Element DOMElement, boolean checkForNativeHandling, java.lang.String[] coords) Returns a locator that's optimized to have minimal length while still trying to robustly represent that targeted canvas.
static Canvas	getTestRoot() Gets the implicit root canvas available in scLocators starting "//testRoot[]".
static void	installLocatorShortcut() This method allows developers to retrieve locators for elements on the page via a key-combo plus mouseDown on the element in question. It may be invoked from a bookmarklet stored in the browser, giving developers a one-click way to retrieve locators for any Smart GWT application
static java.lang.Boolean	isCanvasDone(Canvas canvas) Returns whether the canvas is in a consistent state with no pending operations.
static java.lang.Boolean	isElementClickable(Canvas canvas) Returns whether the instance is ready to be clicked on by a Selenium test.
static java.lang.Boolean	isElementClickable(FormItem item) Returns whether the instance is ready to be clicked on by a Selenium test.
static java.lang.Boolean	isElementReadyForKeyPresses(Canvas canvas) Given a DOM element, returns whether the associated Smart GWT Canvas or FormItem is ready to receive keyPress events from a Selenium test.
static java.lang.Boolean	isElementReadyForKeyPresses(FormItem item) Given a DOM element, returns whether the associated Smart GWT Canvas or FormItem is ready to receive keyPress events from a Selenium test.
static java.lang.Boolean	isFormDone(Canvas canvas) Returns whether the DynamicForm is in a consistent state with no pending operations.
static java.lang.Boolean	isGridDone(Canvas canvas) Returns whether the ListGrid supplied or containing the supplied canvas is in a consistent state with no pending operations.
static java.lang.Boolean	isItemDone(FormItem item) Returns whether the FormItem is in a consistent state with no pending operations.
static boolean	isSystemDone() Returns whether the loaded page is in a consistent state with no pending operations.
static boolean	isSystemDone(boolean includeRedraws)
static boolean	isSystemDone(boolean includeRedraws, boolean includeEdits) Returns whether the loaded page is in a consistent state with no pending operations.
static java.lang.Boolean	isTileGridDone(Canvas canvas) Returns whether the TileGrid is in a consistent state with no pending operations.
static java.lang.Boolean	isTileLayoutDone(Canvas canvas) Returns whether the TileLayout is in a consistent state with no pending operations.
static Canvas	locateCanvasFromDOMElement(com.google.gwt.dom.client.Element element) Given an element in the DOM, returns the canvas containing this element, or null if the element is not contained in any canvas handle.
static void	setTestRoot(Canvas canvas) Sets the implicit root canvas available in scLocators starting "//testRoot[]".
static void	uninstallLocatorShortcut() Uninstalls the locator shortcut installed by installLocatorShortcut()

Methods inherited from class java.lang.Object

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

Constructor Detail

AutoTest

public AutoTest()

Method Detail

getLocatorWithIndicators

public static QualityIndicatedLocator getLocatorWithIndicators(com.google.gwt.dom.client.Element DOMElement)

Returns the QualityIndicatedLocator associated with some DOM element in a Smart GWT application page. If coords, representing the page position, is passed in, the locator may be generated with a specific trailing "target area" identifer that will map back to the appropriate, potentially different, physical coordinates, even if the widget is moved. The coords argument will only have an effect in cases where the mouse position over the target could potentially change behavior.

Parameters:

DOMElement - DOM element within in the page. If null the locator for the last mouse event target will be generated

Returns:

Locator details allowing the AutoTest subsystem to find an equivalent DOM element on subsequent page loads.

getLocatorWithIndicators

public static QualityIndicatedLocator getLocatorWithIndicators(com.google.gwt.dom.client.Element DOMElement,
                                                               boolean checkForNativeHandling)

See Also:

getLocatorWithIndicators(com.google.gwt.dom.client.Element)

getLocatorWithIndicators

public static QualityIndicatedLocator getLocatorWithIndicators(com.google.gwt.dom.client.Element DOMElement,
                                                               boolean checkForNativeHandling,
                                                               java.lang.String[] coords)

Returns the QualityIndicatedLocator associated with some DOM element in a Smart GWT application page. If coords, representing the page position, is passed in, the locator may be generated with a specific trailing "target area" identifer that will map back to the appropriate, potentially different, physical coordinates, even if the widget is moved. The coords argument will only have an effect in cases where the mouse position over the target could potentially change behavior.

Parameters:

DOMElement - DOM element within in the page. If null the locator for the last mouse event target will be generated

checkForNativeHandling - If this parameter is passed in, check whether the target element responds to native browser events directly rather than going through the Smart GWT widget/event handling model. If we detect this case, return null rather than a live locator. This allows us to differentiate between (for example) an event on a Canvas handle, and an event occurring directly on a simple <a href=...> tag written inside a Canvas handle.

coords - X, Y page position

Returns:

Locator details allowing the AutoTest subsystem to find an equivalent DOM element on subsequent page loads.

getMinimalLocator

public static java.lang.String getMinimalLocator(com.google.gwt.dom.client.Element DOMElement)

Returns a locator that's optimized to have minimal length while still trying to robustly represent that targeted canvas. The returned locator may simply be an ID, if the target has a manually assigned ID, or it may consist of syntax starting with //: that will search for a widget with the specified ID or defining property (e.g. "title"). A minimal locator may also contain a second, interior search denoted by // that searches the hierarchy below the preceding part of the locator.

A minimal locator should be passed to getObject(), getElement(), etc., to retrieve the original target.

Note that when searching by defining property, a breadth-first search of the widget hierarchy will be run looking for the first widget of the appropriate framework class with the specified defining property.

Parameters:

DOMElement - DOM element within in the page. If null the locator for the last mouse event target will be generated

Returns:

minimal locator string allowing the AutoTest subsystem to find an equivalent DOM element on subsequent page loads. See AutoTestLocator

getMinimalLocator

public static java.lang.String getMinimalLocator(com.google.gwt.dom.client.Element DOMElement,
                                                 boolean checkForNativeHandling)

See Also:

getMinimalLocator(com.google.gwt.dom.client.Element)

getMinimalLocator

public static java.lang.String getMinimalLocator(com.google.gwt.dom.client.Element DOMElement,
                                                 boolean checkForNativeHandling,
                                                 java.lang.String[] coords)

Returns a locator that's optimized to have minimal length while still trying to robustly represent that targeted canvas. The returned locator may simply be an ID, if the target has a manually assigned ID, or it may consist of syntax starting with //: that will search for a widget with the specified ID or defining property (e.g. "title"). A minimal locator may also contain a second, interior search denoted by // that searches the hierarchy below the preceding part of the locator.

A minimal locator should be passed to getObject(), getElement(), etc., to retrieve the original target.

Note that when searching by defining property, a breadth-first search of the widget hierarchy will be run looking for the first widget of the appropriate framework class with the specified defining property.

Parameters:

DOMElement - DOM element within in the page. If null the locator for the last mouse event target will be generated

checkForNativeHandling - If this parameter is passed in, check whether the target element responds to native browser events directly rather than going through the Smart GWT widget/event handling model. If we detect this case, return null rather than a live locator. This allows us to differentiate between (for example) an event on a Canvas handle, and an event occurring directly on a simple <a href=...> tag written inside a Canvas handle.

coords - X, Y page position

Returns:

minimal locator string allowing the AutoTest subsystem to find an equivalent DOM element on subsequent page loads. See AutoTestLocator

installLocatorShortcut

public static void installLocatorShortcut()

This method allows developers to retrieve locators for elements on the page via a key-combo plus mouseDown on the element in question.
It may be invoked from a bookmarklet stored in the browser, giving developers a one-click way to retrieve locators for any Smart GWT application

When installLocatorShortcut() is invoked, it will register a Page-level mouseDown handler which, if the Shift+Ctrl or Shift+Meta key-combo are being held down will display the locator for the element under the mouse in a text-box and also copy it to clipboard.

As with the isc.showConsole() method, developers may wish to create a bookmark in their browser to quickly enable this functionality on any Smart GWT application, without any changes to the application code:

1. Create a new bookmark in your browser.
2. Enter url "javascript:isc.AutoTest.installLocatorShortcut()".
3. Label the bookmark as "Locator Shortcut"
4. Consider adding this to the Bookmarks Toolbar. This allows you to enable the feature with a single click from any Smart GWT application.

To uninstall the locator shortcut, call uninstallLocatorShortcut()

isCanvasDone

public static java.lang.Boolean isCanvasDone(Canvas canvas)

Returns whether the canvas is in a consistent state with no pending operations. Returns null if the supplied argument is not a valid canvas. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• canvas is drawn
• canvas isn't dirty
• canvas has no queued overflow operations
• canvas is not animating

Parameters:

canvas - canvas to test

Returns:

whether canvas is 'done' as described above

isElementClickable

public static java.lang.Boolean isElementClickable(Canvas canvas)

Returns whether the instance is ready to be clicked on by a Selenium test. Returns null if the supplied instance is not a valid canvas or form item. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• no network operations are outstanding (configurable, see implicitNetworkWait)
• canvas is visible, enabled, and not masked,
• canvas satisfies isCanvasDone()
• if canvas is a TileGrid, it satisfies isTileGridDone()
• if canvas is a TileLayout, it satisfies isTileLayoutDone()
• if canvas is a ListGrid or body of a ListGrid, it satisfies isGridDone()
• if canvas is a DynamicForm, it satisfies isFormDone()

Note that for a form item in a DynamicForm, the DynamicForm must satisfy the third condition above, while the container widget of the element must satisfy the remaining conditions.

Parameters:

canvas - instance to test

Returns:

whether instance is 'clickable' as described above

isElementClickable

public static java.lang.Boolean isElementClickable(FormItem item)

Returns whether the instance is ready to be clicked on by a Selenium test. Returns null if the supplied instance is not a valid canvas or form item. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• no network operations are outstanding (configurable, see implicitNetworkWait)
• canvas is visible, enabled, and not masked,
• canvas satisfies isCanvasDone()
• if canvas is a TileGrid, it satisfies isTileGridDone()
• if canvas is a TileLayout, it satisfies isTileLayoutDone()
• if canvas is a ListGrid or body of a ListGrid, it satisfies isGridDone()
• if canvas is a DynamicForm, it satisfies isFormDone()

Note that for a form item in a DynamicForm, the DynamicForm must satisfy the third condition above, while the container widget of the element must satisfy the remaining conditions.

Parameters:

item - instance to test

Returns:

whether instance is 'clickable' as described above

isElementReadyForKeyPresses

public static java.lang.Boolean isElementReadyForKeyPresses(Canvas canvas)

Given a DOM element, returns whether the associated Smart GWT Canvas or FormItem is ready to receive keyPress events from a Selenium test. Returns null if the locator is not valid or doesn't represent a valid Canvas or FormItem. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• if a TextItem, FileItem, or TextAreaItem, it has native focus,
• the element satisfies isElementClickable()

Parameters:

canvas - DOM element to test (element obtained from canvas, form item, or Smart GWT locator if provided)

Returns:

whether element is 'ready' as described above

isElementReadyForKeyPresses

public static java.lang.Boolean isElementReadyForKeyPresses(FormItem item)

Given a DOM element, returns whether the associated Smart GWT Canvas or FormItem is ready to receive keyPress events from a Selenium test. Returns null if the locator is not valid or doesn't represent a valid Canvas or FormItem. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• if a TextItem, FileItem, or TextAreaItem, it has native focus,
• the element satisfies isElementClickable()

Parameters:

item - DOM element to test (element obtained from canvas, form item, or Smart GWT locator if provided)

Returns:

whether element is 'ready' as described above

isFormDone

public static java.lang.Boolean isFormDone(Canvas canvas)

Returns whether the DynamicForm is in a consistent state with no pending operations. Returns null if the supplied argument is not a valid DynamicForm. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• form has no pending delayed "set values" or "set values focus" operations
• all contained items satisfy isItemDone()

Parameters:

canvas - canvas to test

Returns:

whether canvas is 'done' as described above

isGridDone

public static java.lang.Boolean isGridDone(Canvas canvas)

Returns whether the ListGrid supplied or containing the supplied canvas is in a consistent state with no pending operations. Returns null if the supplied canvas is not a ListGrid or contained in a ListGrid. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• no pending scroll operations
• no pending filter editor operations
• no unsaved edits to the grid records
• no asynchronous regrouping operations are in progress
• no outstanding fetch/filter operations are present for the ResultSet
• no outstanding sort operations are present that will update the ListGrid

Parameters:

canvas - canvas to test

Returns:

whether canvas is 'done' as described above

isItemDone

public static java.lang.Boolean isItemDone(FormItem item)

Returns whether the FormItem is in a consistent state with no pending operations. Returns null if the supplied argument is not a valid FormItem. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• if the container widget of the item isn't the parent DynamicForm, then the container widget must satisfy isCanvasDone() (or isGridDone(), etc., as appropriate)
• the item cannot have any fetches in progress for missing display/value field values
• picklists (SelectItem or ComboBoxItem) cannot have any pending row fetches
• any contained FormItems must satisfy isItemDone() themselves
• any contained Canvas must satisfy isCanvasDone() (or isGridDone(), etc., as appropriate)

Parameters:

item - canvas to test

Returns:

whether item is 'done' as described above

isSystemDone

public static boolean isSystemDone()

Returns whether the loaded page is in a consistent state with no pending operations. Specifically, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• all ListGrids (as defined by isc.isA.ListGrid) satisfy isGridDone()
• all TileGrids that are drawn satisfy isTileGridDone()
• all TileLayouts that are drawn satisfy isTileLayoutDone()
• all DynamicForms that are drawn satisfy isFormDone()
• all Canvii that are drawn satisfy isCanvasDone()
• no network operations are outstanding (configurable, see implicitNetworkWait)
• there are no pending Canvas redraws (if includeRedraws parameter is true)

Note: In a situation where messaging is being used to periodically refresh components, or if the application contains a label updated every second to show the current time, it's possible that this call might always return false if includeRedraws is true.

Returns:

whether loaded page is 'done' as described above

isSystemDone

public static boolean isSystemDone(boolean includeRedraws)

See Also:

isSystemDone()

isSystemDone

public static boolean isSystemDone(boolean includeRedraws,
                                   boolean includeEdits)

Returns whether the loaded page is in a consistent state with no pending operations. Specifically, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• all ListGrids (as defined by isc.isA.ListGrid) satisfy isGridDone()
• all TileGrids that are drawn satisfy isTileGridDone()
• all TileLayouts that are drawn satisfy isTileLayoutDone()
• all DynamicForms that are drawn satisfy isFormDone()
• all Canvii that are drawn satisfy isCanvasDone()
• no network operations are outstanding (configurable, see implicitNetworkWait)
• there are no pending Canvas redraws (if includeRedraws parameter is true)

Note: In a situation where messaging is being used to periodically refresh components, or if the application contains a label updated every second to show the current time, it's possible that this call might always return false if includeRedraws is true.

Parameters:

includeRedraws - whether to check for pending Canvas redraws

includeEdits - whether to check for unsaved edits for ListGrids

Returns:

whether loaded page is 'done' as described above

isTileGridDone

public static java.lang.Boolean isTileGridDone(Canvas canvas)

Returns whether the TileGrid is in a consistent state with no pending operations. Returns null if the supplied canvas is not a valid TileGrid. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• the TileGrid (as a tileLayout) satisfies isTileLayoutDone()
• the TileGrid has no pending layout animation operations queued

Parameters:

canvas - TileGrid to test

Returns:

whether TileGrid is 'done' as described above

isTileLayoutDone

public static java.lang.Boolean isTileLayoutDone(Canvas canvas)

Returns whether the TileLayout is in a consistent state with no pending operations. Returns null if the supplied canvas is not a valid TileLayout. Otherwise, returns true or false according as the conditions below are all satisfied:

• page has finished loading
• the TileLayout (as a canvas) satisfies isCanvasDone()
• the TileLayout is not currently animating any layout operations

Parameters:

canvas - TileLayout to test

Returns:

whether TileLayout is 'done' as described above

locateCanvasFromDOMElement

public static Canvas locateCanvasFromDOMElement(com.google.gwt.dom.client.Element element)

Given an element in the DOM, returns the canvas containing this element, or null if the element is not contained in any canvas handle.

Parameters:

element - DOM element within in the page

Returns:

canvas containing the element, or null if none apply

setTestRoot

public static void setTestRoot(Canvas canvas)

Sets the implicit root canvas available in scLocators starting "//testRoot[]". Setting this property may enable one to use the same script to test identical widget hierarchies that are rooted under different base widgets.

Parameters:

canvas - the implicit root

uninstallLocatorShortcut

public static void uninstallLocatorShortcut()

Uninstalls the locator shortcut installed by installLocatorShortcut()

getTestRoot

public static Canvas getTestRoot()

Gets the implicit root canvas available in scLocators starting "//testRoot[]". Setting this property may enable one to use the same script to test identical widget hierarchies that are rooted under different base widgets.

Returns:

the canvas currently set as the test root