Package com.smartgwt.client.util

# Class AutoTest

java.lang.Object
com.smartgwt.client.util.AutoTest

public class AutoTest extends Object
Standalone class providing a general interface for integration with Automated Testing Tools

For an overview of Automated Testing in Smart GWT, see the documentation `here`.

## AutoTestLocators

The AutoTest class is responsible for creating and resolving `autoTestLocators` - identifier strings which can reliably identify an interactive element in a Smart GWT application.

These locators are designed to work across browsers, Smart GWT versions, and even major changes to your application's UI. They do not rely on the DOM structure, and are intended to be able to identify the target element reliably without requiring pervasive explicitly specified `component IDs`.

Note that AutoTest locators are the only supported way to identify Smart GWT generated DOM elements when recording tests for automated testing tools. Using XPath DOM locators to identify elements is not a supported approach. The DOM structure and DOM element attributes generated by Smart GWT components are not guaranteed to be identical for functionally equivalent elements across different Smart GWT builds, different browsers, and for dynamically generated components, could even change across page reloads.

The primary APIs for working with AutoTest locators are as follows:

- `getLocator()` to retrieve a locator for an element
- `getElement()` to resolve a stored locator back to an element

Developers should also be aware of the `installLocatorShortcut()` method which allows you to retreive locators via a simple key combo + mouseDown event on the target element.

See the `AutoTestLocator overview` documentation for details on how locators are structured.

See the `Reliable AutoTestLocators overview` documentation for best practices for generating high quality locators.

### AutoTest locator variables

AutoTest locators may be written to include dynamic variables to be resolved at runtime. See the following APIs for details:

- `setVariable()`: Set up a named variable for later use
- `storeLocatorResult()`: Resolve a locator against the current environment and store it as a variable
- `getVariable()`: Retrieves the value of a previously defined variable

### Locator testRoot

For tests that target a standard widget hierarchy such as a `screen`, the `testRoot` may be used to reliably identify the widget hierarchy in question wherever it is rendered inside a larger application.

## Waiting for asynchronous operations

The AutoTest class provides utilities to wait for asynchronous actions, including both system delays (such as `redraws that fire on system idle`, for example), and asynchronous `RPC operations`.

- `waitForElement()`: this method will wait for asynchronous operations to complete before resolving an `AutoTestLocator` to an element and firing a callback function. This allows recorded tests to reference elements that are blocked or unavailable until some asynchronous action(s) complete.
- `waitForSystemDone()`: this method will wait for any outstanding asynchronous system operations to complete and then fire the specified callback.
- `isSystemDone()`: this method may be called to check whether there are currently any outstanding asynchronous system operations.

Note that Smart GWT's support for integrating with high level tools such as `Playwright`, `Cypress` and `Selenium` automatically makes use of these APIs.

See Also:
  - `AutoTest overview and related methods`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AutoTest()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `getFullPathLocator()`
  Convenience method to generate a `AutoTestLocator` with no search segments and an explicit path from the locator root to the target.
  `static String`
  `getFullPathLocator(Element target)`
  See `getFullPathLocator()`
  `static String`
  `getFullPathLocator(Element target, boolean checkForNativeHandling)`
  See `getFullPathLocator()`
  `static String`
  `getFullPathLocator(Element target, boolean checkForNativeHandling, String[] coords)`
  Convenience method to generate a `AutoTestLocator` with no search segments and an explicit path from the locator root to the target.
  `static QualityIndicatedLocator`
  `getLocatorWithIndicators(Element DOMElement)`
  Returns the `QualityIndicatedLocator` associated with some DOM element in a Smart GWT application page.
  `static QualityIndicatedLocator`
  `getLocatorWithIndicators(Element DOMElement, boolean checkForNativeHandling)`
  See `getLocatorWithIndicators()`
  `static QualityIndicatedLocator`
  `getLocatorWithIndicators(Element DOMElement, boolean checkForNativeHandling, String[] coords)`
  Returns the `QualityIndicatedLocator` associated with some DOM element in a Smart GWT application page.
  `static String`
  `getMinimalLocator()`
  Convenience method to generate a `AutoTestLocator` that is as compact as possible.
  `static String`
  `getMinimalLocator(Element target)`
  See `getMinimalLocator()`
  `static String`
  `getMinimalLocator(Element target, boolean checkForNativeHandling)`
  See `getMinimalLocator()`
  `static String`
  `getMinimalLocator(Element target, boolean checkForNativeHandling, String[] coords)`
  Convenience method to generate a `AutoTestLocator` that is as compact as possible.
  `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 Boolean`
  `isCanvasDone(Canvas canvas)`
  Returns whether the canvas is in a consistent state with no pending operations.
  `static Boolean`
  `isElementClickable(Canvas canvas)`
  Returns whether the instance is ready to be clicked on by a Selenium test.
  `static Boolean`
  `isElementClickable(FormItem item)`
  Returns whether the instance is ready to be clicked on by a Selenium test.
  `static 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 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 Boolean`
  `isFormDone(Canvas canvas)`
  Returns whether the DynamicForm is in a consistent state with no pending operations.
  `static Boolean`
  `isGridDone(Canvas canvas)`
  Returns whether the ListGrid supplied or containing the supplied canvas is in a consistent state with no pending operations.
  `static Boolean`
  `isItemDone(FormItem item)`
  Returns whether the FormItem is in a consistent state with no pending operations.
  `static boolean`
  `isSystemDone()`
  Returns a boolean to indicate whether the current application is fully loaded with no pending operations, and is ready for user interaction.
  `static boolean`
  `isSystemDone(boolean options)`
  Returns a boolean to indicate whether the current application is fully loaded with no pending operations, and is ready for user interaction.
  `static boolean`
  `isSystemDone(SystemDoneConfig options)`
  Returns a boolean to indicate whether the current application is fully loaded with no pending operations, and is ready for user interaction.
  `static Boolean`
  `isTileGridDone(Canvas canvas)`
  Returns whether the TileGrid is in a consistent state with no pending operations.
  `static Boolean`
  `isTileLayoutDone(Canvas canvas)`
  Returns whether the TileLayout is in a consistent state with no pending operations.
  `static Canvas`
  `locateCanvasFromDOMElement(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 FormItem`
  `locateFormItemFromDOMElement(Element element)`
  Given an element in the DOM, returns the FormItem containing this element, or null if the element is not contained in any FormItem.
  `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()`
  `static void`
  `waitForElement(String locator, String callback)`
  Waits for any in-progress actions to complete and then returns the element for the specified locator.
  `static void`
  `waitForElement(String locator, String callback, ElementWaitConfig options)`
  Waits for any in-progress actions to complete and then returns the element for the specified locator.
  `static void`
  `waitForSystemDone(String callback)`
  Fires the provided callback when `isSystemDone()` returns true.
  `static void`
  `waitForSystemDone(String callback, SystemWaitConfig options)`
  Fires the provided callback when `isSystemDone()` returns true.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### AutoTest

    public AutoTest()

- ## Method Details

  - ### getFullPathLocator

    public static String getFullPathLocator()
    Convenience method to generate a `AutoTestLocator` with no search segments and an explicit path from the locator root to the target.

    This method sets `getLocator()` with the following configuration settings:

    - useSearchSegments:false
    - useMinimalFallbackAttributes:false
    - useCompactFallbackSyntax:false
    Returns:
      full-path locator string to identify the target. See `AutoTestLocator`

  - ### getFullPathLocator

    public static String getFullPathLocator(Element target)
    See `getFullPathLocator()`

  - ### getFullPathLocator

    public static String getFullPathLocator(Element target, boolean checkForNativeHandling)
    See `getFullPathLocator()`

  - ### getFullPathLocator

    public static String getFullPathLocator(Element target, boolean checkForNativeHandling, String[] coords)
    Convenience method to generate a `AutoTestLocator` with no search segments and an explicit path from the locator root to the target.

    This method sets `getLocator()` with the following configuration settings:

    - useSearchSegments:false
    - useMinimalFallbackAttributes:false
    - useCompactFallbackSyntax:false
    Parameters:
      `target` - Target within the page. This may be a DOM element, a `Canvas` or a `FormItem`. If null, a locator for the last mouse event target DOM element 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:
      full-path locator string to identify the target. See `AutoTestLocator`

  - ### getLocatorWithIndicators

    public static QualityIndicatedLocator getLocatorWithIndicators(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(Element DOMElement, boolean checkForNativeHandling)
    See `getLocatorWithIndicators()`

  - ### getLocatorWithIndicators

    public static QualityIndicatedLocator getLocatorWithIndicators(Element DOMElement, boolean checkForNativeHandling, 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 String getMinimalLocator()
    Convenience method to generate a `AutoTestLocator` that is as compact as possible.

    This method sets `getLocator()` with the following configuration settings:

    - useSearchSegments:true
    - searchSegmentsIncludeHidden:false
    - useMinimalFallbackAttributes:true
    - useCompactFallbackSyntax:true
    Returns:
      minimal locator string to identify the target. See `AutoTestLocator`

  - ### getMinimalLocator

    public static String getMinimalLocator(Element target)
    See `getMinimalLocator()`

  - ### getMinimalLocator

    public static String getMinimalLocator(Element target, boolean checkForNativeHandling)
    See `getMinimalLocator()`

  - ### getMinimalLocator

    public static String getMinimalLocator(Element target, boolean checkForNativeHandling, String[] coords)
    Convenience method to generate a `AutoTestLocator` that is as compact as possible.

    This method sets `getLocator()` with the following configuration settings:

    - useSearchSegments:true
    - searchSegmentsIncludeHidden:false
    - useMinimalFallbackAttributes:true
    - useCompactFallbackSyntax:true
    Parameters:
      `target` - Target within the page. This may be a DOM element, a `Canvas` or a `FormItem`. If null, a locator for the last mouse event target DOM element 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 to identify the target. 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 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 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 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 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 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 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 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 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 a boolean to indicate whether the current application is fully loaded with no pending operations, and is ready for user interaction. This includes the following checks:
    - 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()`
    In addition to this the `options` parameter allows developers to check additional criteria as documented under `SystemDoneConfig`.

    Note: `waitForSystemDone()` will poll this method repeatedly to check for all pending actions being complete. The `SystemWaitConfig` parameter of that method allow the user to speciofy which actions to wait for. By default `waitForSystemDone()` will wait for all actions to complete, including queued redraws, timers, network requests, as well as page load and comopnent level `isComponentDone` checks.

    Depending on your application configuration, it is possible that this method will not be able to determine whether it is truly in a busy state. Some examples include:

    - If `SystemDoneConfig.includeTimers` is true and the application has a constantly running background timer to perform some ongoing polling action or similar, this method may return `false` even though the application is ready for interaction
    - Similarly if `SystemDoneConfig.includeRedraws` is true, and the application is using messaging, or some other mechanism to periodically refresh component(s) such that they are repeatedly marked as dirty, this method may return `false` even though the application is ready for interaction
    - If this application makes use of some third-party library to perform asynchronous actions, this method may return `true` even when the application is waiting on a response from this third-party tool.

    Debugging systemDone issues: To diagnose why the system is not becoming "done", enable the `"systemDone"` log category. At INFO level, the reason for each blocking condition is logged. At DEBUG level, detailed diagnostics are logged including canvas drawn state, layout reflow status, pending animations, and parent visibility.

              SC.setLogPriority("systemDone", LogPriority.INFO);  // basic diagnostics
              SC.setLogPriority("systemDone", LogPriority.DEBUG); // detailed diagnostics

    Returns:
      whether loaded page is 'done' as described above

  - ### isSystemDone

    public static boolean isSystemDone(SystemDoneConfig options)
    Returns a boolean to indicate whether the current application is fully loaded with no pending operations, and is ready for user interaction. This includes the following checks:
    - 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()`
    In addition to this the `options` parameter allows developers to check additional criteria as documented under `SystemDoneConfig`.

    Note: `waitForSystemDone()` will poll this method repeatedly to check for all pending actions being complete. The `SystemWaitConfig` parameter of that method allow the user to speciofy which actions to wait for. By default `waitForSystemDone()` will wait for all actions to complete, including queued redraws, timers, network requests, as well as page load and comopnent level `isComponentDone` checks.

    Depending on your application configuration, it is possible that this method will not be able to determine whether it is truly in a busy state. Some examples include:

    - If `SystemDoneConfig.includeTimers` is true and the application has a constantly running background timer to perform some ongoing polling action or similar, this method may return `false` even though the application is ready for interaction
    - Similarly if `SystemDoneConfig.includeRedraws` is true, and the application is using messaging, or some other mechanism to periodically refresh component(s) such that they are repeatedly marked as dirty, this method may return `false` even though the application is ready for interaction
    - If this application makes use of some third-party library to perform asynchronous actions, this method may return `true` even when the application is waiting on a response from this third-party tool.

    Debugging systemDone issues: To diagnose why the system is not becoming "done", enable the `"systemDone"` log category. At INFO level, the reason for each blocking condition is logged. At DEBUG level, detailed diagnostics are logged including canvas drawn state, layout reflow status, pending animations, and parent visibility.

              SC.setLogPriority("systemDone", LogPriority.INFO);  // basic diagnostics
              SC.setLogPriority("systemDone", LogPriority.DEBUG); // detailed diagnostics

    Parameters:
      `options` - This parameter determines what specific outstanding actions are required to be completed before the system is considered "done" with current processing. If passed as a boolean rather than a SystemDoneConfig object, this determines whether the system should wait for `pending redraws`.
    Returns:
      whether loaded page is 'done' as described above

  - ### isSystemDone

    public static boolean isSystemDone(boolean options)
    Returns a boolean to indicate whether the current application is fully loaded with no pending operations, and is ready for user interaction. This includes the following checks:
    - 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()`
    In addition to this the `options` parameter allows developers to check additional criteria as documented under `SystemDoneConfig`.

    Note: `waitForSystemDone()` will poll this method repeatedly to check for all pending actions being complete. The `SystemWaitConfig` parameter of that method allow the user to speciofy which actions to wait for. By default `waitForSystemDone()` will wait for all actions to complete, including queued redraws, timers, network requests, as well as page load and comopnent level `isComponentDone` checks.

    Depending on your application configuration, it is possible that this method will not be able to determine whether it is truly in a busy state. Some examples include:

    - If `SystemDoneConfig.includeTimers` is true and the application has a constantly running background timer to perform some ongoing polling action or similar, this method may return `false` even though the application is ready for interaction
    - Similarly if `SystemDoneConfig.includeRedraws` is true, and the application is using messaging, or some other mechanism to periodically refresh component(s) such that they are repeatedly marked as dirty, this method may return `false` even though the application is ready for interaction
    - If this application makes use of some third-party library to perform asynchronous actions, this method may return `true` even when the application is waiting on a response from this third-party tool.

    Debugging systemDone issues: To diagnose why the system is not becoming "done", enable the `"systemDone"` log category. At INFO level, the reason for each blocking condition is logged. At DEBUG level, detailed diagnostics are logged including canvas drawn state, layout reflow status, pending animations, and parent visibility.

              SC.setLogPriority("systemDone", LogPriority.INFO);  // basic diagnostics
              SC.setLogPriority("systemDone", LogPriority.DEBUG); // detailed diagnostics

    Parameters:
      `options` - This parameter determines what specific outstanding actions are required to be completed before the system is considered "done" with current processing. If passed as a boolean rather than a SystemDoneConfig object, this determines whether the system should wait for `pending redraws`.
    Returns:
      whether loaded page is 'done' as described above

  - ### isTileGridDone

    public static 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 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(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

  - ### locateFormItemFromDOMElement

    public static FormItem locateFormItemFromDOMElement(Element element)
    Given an element in the DOM, returns the FormItem containing this element, or null if the element is not contained in any FormItem.
    Parameters:
      `element` - DOM element within in the page
    Returns:
      formItem 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()`

  - ### waitForElement

    public static void waitForElement(String locator, String callback)
    Waits for any in-progress actions to complete and then returns the element for the specified locator.

    By default this method will wait for the `system to be done` before calling `getElement()` with the specified locator. The `waitStyle` attribute of the options parameter may be used to instead wait for the locator to resolve to a `clickable element`.

    Parameters:
      `locator` - locator for the element to retrieve. See `AutoTestLocator`
      `callback` - callback to fire when the element has been retrieved - takes two parameters:
      - "element" (DOMElement) - the clickable element the locator resolved to (or null)
      - "done" (boolean) - this will be false if the method timed out
      . See `Callback`

  - ### waitForElement

    public static void waitForElement(String locator, String callback, ElementWaitConfig options)
    Waits for any in-progress actions to complete and then returns the element for the specified locator.

    By default this method will wait for the `system to be done` before calling `getElement()` with the specified locator. The `waitStyle` attribute of the options parameter may be used to instead wait for the locator to resolve to a `clickable element`.

    Parameters:
      `locator` - locator for the element to retrieve. See `AutoTestLocator`
      `callback` - callback to fire when the element has been retrieved - takes two parameters:
      - "element" (DOMElement) - the clickable element the locator resolved to (or null)
      - "done" (boolean) - this will be false if the method timed out
      . See `Callback`
      `options` - Options to configure the wait

  - ### waitForSystemDone

    public static void waitForSystemDone(String callback)
    Fires the provided callback when `isSystemDone()` returns true.

    By default this will wait for the following system actions to complete:

    - All outstanding Smart GWT `RPC and DataSource requests`
    - All outstanding FileLoader requests
    - Any `queued redraws`
    - Any non-recurring delayed actions
    Pass `{includeFieldRebuild:true}` to also wait for field-rebuild work on not-yet-drawn `ListGrids` (e.g. async formula or summary field computation initiated before the grid is drawn). Note that this behavior may differ from the default settings for `isSystemDone()`

    The `options` parameter gives developers finer grained control over what to wait for.

    Parameters:
      `callback` - Action to fire. This will take a single parameter "done" which will be set to false if the method timed out waiting for isSystemDone() to return true;. See `Callback`
    See Also:
      - `Callback`

  - ### waitForSystemDone

    public static void waitForSystemDone(String callback, SystemWaitConfig options)
    Fires the provided callback when `isSystemDone()` returns true.

    By default this will wait for the following system actions to complete:

    - All outstanding Smart GWT `RPC and DataSource requests`
    - All outstanding FileLoader requests
    - Any `queued redraws`
    - Any non-recurring delayed actions
    Pass `{includeFieldRebuild:true}` to also wait for field-rebuild work on not-yet-drawn `ListGrids` (e.g. async formula or summary field computation initiated before the grid is drawn). Note that this behavior may differ from the default settings for `isSystemDone()`

    The `options` parameter gives developers finer grained control over what to wait for.

    Parameters:
      `callback` - Action to fire. This will take a single parameter "done" which will be set to false if the method timed out waiting for isSystemDone() to return true;. See `Callback`
      `options` - options to configure the wait

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