Initial UITester API for writing toolkit agnostic tests (#1107)

* Initial UITester API

* Add the missing __init__.py file

* Add test requirement decorators

* Add a sentence to the docstring

* Lots of renaming; move UIWrapper into its own module

* Differentiate the two register methods so if necessary, we can have an interface and combine the classes

* Fix some docstring

* Fix test requirements

* A few more naming change in docstring

* Combine the registries into an object where composition occurs there

* Fix spelling and references to objects renamed/not-yet-added

* Remove the description for nesting find_by_name (a future feature)

* One more docstring and spelling fix

* Add copyright header

traitsui/testing/tester/command.py

@@ -0,0 +1,28 @@
+#  Copyright (c) 2005-2020, Enthought, Inc.
+#  All rights reserved.
+#
+#  This software is provided without warranty under the terms of the BSD
+#  license included in LICENSE.txt and may be redistributed only
+#  under the conditions described in the aforementioned license.  The license
+#  is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+#  Thanks for using Enthought open source!
+#
+
+""" This module defines interaction objects that can be passed to
+``UIWrapper.perform`` where the actions represent 'commands'.
+
+Implementations for these actions are expected to produce the
+documented side effects without returning any values.
+"""
+
+
+class MouseClick:
+    """ An object representing the user clicking a mouse button.
+    Currently the left mouse button is assumed.
+
+    In most circumstances, a widget can still be clicked on even if it is
+    disabled. Therefore unlike key events, if the widget is disabled,
+    implementations should not raise an exception.
+    """
+    pass

traitsui/testing/tester/exceptions.py

@@ -0,0 +1,61 @@
+#  Copyright (c) 2005-2020, Enthought, Inc.
+#  All rights reserved.
+#
+#  This software is provided without warranty under the terms of the BSD
+#  license included in LICENSE.txt and may be redistributed only
+#  under the conditions described in the aforementioned license.  The license
+#  is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+#  Thanks for using Enthought open source!
+#
+
+
+class TesterError(Exception):
+    """ Custom exception for UITester/UIWrapper. """
+    pass
+
+
+class InteractionNotSupported(TesterError):
+    """ Raised when an interaction is not supported by a wrapper.
+
+    Parameters
+    ----------
+    target_class : subclass of type
+        The type of a UI target being operated on.
+    interaction_class : subclass of type
+        Any class for the interaction.
+    supported : list of types
+        List of supported interaction types.
+    """
+
+    def __init__(self, target_class, interaction_class, supported):
+        self.target_class = target_class
+        self.interaction_class = interaction_class
+        self.supported = supported
+
+    def __str__(self):
+        return (
+            "No handler is found for target {!r} with interaction {!r}. "
+            "Supported these: {!r}".format(
+                self.target_class, self.interaction_class, self.supported
+            )
+        )
+
+
+class LocationNotSupported(TesterError):
+    """ Raised when attempt to resolve a location on a UI fails
+    because the location type is not supported.
+    """
+
+    def __init__(self, target_class, locator_class, supported):
+        self.target_class = target_class
+        self.locator_class = locator_class
+        self.supported = supported
+
+    def __str__(self):
+        return (
+            "Location {!r} is not supported for {!r}. "
+            "Supported these: {!r}".format(
+                self.locator_class, self.target_class, self.supported
+            )
+        )

traitsui/testing/tester/locator.py

@@ -0,0 +1,37 @@
+#  Copyright (c) 2005-2020, Enthought, Inc.
+#  All rights reserved.
+#
+#  This software is provided without warranty under the terms of the BSD
+#  license included in LICENSE.txt and may be redistributed only
+#  under the conditions described in the aforementioned license.  The license
+#  is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+#  Thanks for using Enthought open source!
+#
+
+""" This module defines objects for locating nested UI targets, to be
+used with ``UIWrapper.locate``.
+
+Implementations for these actions are expected to return a value which is
+a UI target where further location resolution or user interaction can be
+applied.
+"""
+
+
+class NestedUI:
+    """ A locator for locating a nested ``traitsui.ui.UI`` object assuming
+    there is only one. If there are multiple, more location information
+    needs to have been provided already.
+    """
+    pass
+
+
+class TargetByName:
+    """ A locator for locating the next UI target using a name.
+
+    Attributes
+    ----------
+    name : str
+    """
+    def __init__(self, name):
+        self.name = name

traitsui/testing/tester/query.py

@@ -0,0 +1,29 @@
+#  Copyright (c) 2005-2020, Enthought, Inc.
+#  All rights reserved.
+#
+#  This software is provided without warranty under the terms of the BSD
+#  license included in LICENSE.txt and may be redistributed only
+#  under the conditions described in the aforementioned license.  The license
+#  is also available online at http://www.enthought.com/licenses/BSD.txt
+#
+#  Thanks for using Enthought open source!
+#
+
+""" This module defines interaction objects that can be passed to
+``UIWrapper.inspect`` where the actions represent 'queries'.
+
+Implementations for these actions are expected to return value(s), ideally
+without incurring side-effects.
+"""
+
+
+class DisplayedText:
+    """ An object representing an interaction to obtain the displayed (echoed)
+    plain text.
+
+    E.g. For a textbox using a password styling, the displayed text should
+    be a string of platform-dependent password mask characters.
+
+    Implementations should return a ``str``.
+    """
+    pass