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

    All Methods Static Methods Concrete Methods
    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 Canvas` | `getTestRoot()` Gets the implicit root canvas available in scLocators starting "//testRoot[]".
    `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 allowEdits)` 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[]".

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

    - #### 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 `FormItem`s 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 allowEdits)

      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
        `allowEdits` - whether to allow 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

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