Source code for traitsui.testing.tester.ui_wrapper
# (C) Copyright 2004-2023 Enthought, Inc., Austin, TX
# 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!
""" Define the top-level object which is responsible for dispatching testing
functionality for a given GUI object. The functionality is exposed via
``UITester``, which is a TraitsUI specific tester.
"""
from contextlib import contextmanager
import textwrap
from traitsui.testing._exception_handling import (
reraise_exceptions as _reraise_exceptions,
)
from traitsui.testing._gui import (
process_cascade_events as _process_cascade_events,
)
from traitsui.testing.tester import locator
from traitsui.testing.tester.exceptions import (
InteractionNotSupported,
LocationNotSupported,
)
[docs]class UIWrapper:
"""
An ``UIWrapper`` has the following responsibilities:
(1) Wraps a UI target.
(2) Search for a nested UI target within the wrapped UI target.
(3) Perform user interaction on the UI target, e.g. mouse click.
A UI target is an object which can be searched for nested UI targets,
either as intermediate things (like editors or a table widget), or as a
leaf widget which can be operated upon (e.g. a mouse click).
For example, a ``UIWrapper`` may wrap an instance of traitsui.ui.UI in
which more UI targets can be located. A ``UIWrapper`` may also wrap a
leaf widget on which user interactions can be performed.
For locating a nested UI target, the ``locate`` method is provided.
For simulating user interactions such as a mouse click or visual
inspection, the ``perform`` and ``inspect`` methods are provided.
Parameters
----------
target : any
An object on which further UI target can be searched for, or can be
a leaf target that can be operated on.
registries : list of AbstractTargetRegistry
Registries of interaction for different target, in the order
of decreasing priority.
delay : int, optional
Time delay (in ms) in which actions by the wrapper are performed. Note
it is propagated through to created child wrappers. The delay allows
visual confirmation test code is working as desired. Defaults to 0.
auto_process_events : bool, optional
Whether to process (cascade) GUI events automatically. Default is True.
For tests that launch a modal dialog and rely on a recurring timer to
poll if the dialog is closed, it may be necessary to set this flag to
false in order to avoid deadlocks. Note that this is propagated
through to created child wrappers.
Attributes
----------
delay : int
Time delay (in ms) in which actions by the wrapper are performed. Note
it is propagated through to created child wrappers. The delay allows
visual confirmation test code is working as desired.
_target : any
The UI target currently wrapped for interactions or locating nested
components. This is a protected attribute intended to be used for
extending the testing API. Usage of this attribute may expose the
software's internal structure to the tests, developers should use this
attribute with discretion based on context.
"""
def __init__(
self, target, *, registries, delay=0, auto_process_events=True
):
self._target = target
self._registries = registries
self._auto_process_events = auto_process_events
self.delay = delay
[docs] def help(self):
"""Print help messages.
(This function is intended for interactive use.)
"""
# mapping from interaction types to their documentation
interaction_to_doc = dict()
# mapping from location types to their documentation
location_to_doc = dict()
# Order registries by their priority (low to high)
for registry in self._registries[::-1]:
for type_ in registry._get_interactions(self._target):
interaction_to_doc[type_] = registry._get_interaction_doc(
target=self._target,
interaction_class=type_,
)
for type_ in registry._get_locations(self._target):
location_to_doc[type_] = registry._get_location_doc(
target=self._target,
locator_class=type_,
)
print("Interactions")
print("------------")
for interaction_type in sorted(interaction_to_doc, key=repr):
print(repr(interaction_type))
print(
textwrap.indent(
interaction_to_doc[interaction_type], prefix=" "
)
)
print()
if not interaction_to_doc:
print("No interactions are supported.")
print()
print("Locations")
print("---------")
for locator_type in sorted(location_to_doc, key=repr):
print(repr(locator_type))
print(
textwrap.indent(location_to_doc[locator_type], prefix=" ")
)
print()
if not location_to_doc:
print("No locations are supported.")
print()
[docs] def locate(self, location):
"""Attempt to resolve the given location and return a new
UIWrapper.
Parameters
----------
location : any
An instance of a location type supported by the current target.
e.g. ``traitsui.testing.api.Index(1)``
Returns
-------
wrapper : UIWrapper
A new UIWrapper for the given location.
Raises
------
LocationNotSupported
If the given location is not supported.
See Also
--------
UIWrapper.help
"""
return UIWrapper(
target=self._get_next_target(location),
registries=self._registries,
delay=self.delay,
auto_process_events=self._auto_process_events,
)
[docs] def find_by_name(self, name):
"""Find a target inside the current target using a name.
This is equivalent to calling ``locate(TargetByName(name=name))``.
Parameters
----------
name : str
A single name for retreiving a target on a UI.
Returns
-------
wrapper : UIWrapper
Raises
------
LocationNotSupported
If the current target does not support locating another target
by a name.
See Also
--------
traitsui.testing.tester.locator.TargetByName
"""
return self.locate(locator.TargetByName(name=name))
[docs] def find_by_id(self, id):
"""Find a target inside the current target using an id.
This is equivalent to calling ``locate(TargetById(id=id))``.
Parameters
----------
id : str
Id for finding an item in the UI.
Returns
-------
wrapper : UIWrapper
Raises
------
LocationNotSupported
If the current target does not support locating another target
by a unique identifier.
See Also
--------
traitsui.testing.tester.locator.TargetById
"""
return self.locate(locator.TargetById(id=id))
[docs] def perform(self, interaction):
"""Perform a user interaction that causes side effects.
Parameters
----------
interaction : object
An instance of an interaction type supported by the current target.
e.g. ``traitsui.testing.api.MouseClick()``
Raises
------
InteractionNotSupported
If the interaction given is not supported for the current UI
target.
See Also
--------
UIWrapper.help
"""
self._perform_or_inspect(interaction)
[docs] def inspect(self, interaction):
"""Return a value or values for inspection.
Parameters
----------
interaction : object
An instance of an interaction type supported by the current target.
e.g. ``traitsui.testing.api.DisplayedText()``
Returns
-------
values : any
Any values returned for the given inspection. The type should be
documented by the interaction type object.
Raises
------
InteractionNotSupported
If the interaction given is not supported for the current UI
target.
See Also
--------
UIWrapper.help
"""
return self._perform_or_inspect(interaction)
# Private methods #########################################################
def _perform_or_inspect(self, interaction):
"""Perform a user interaction or a user inspection.
Parameters
----------
interaction : instance of interaction type
An object defining the interaction.
Returns
-------
value : any
Raises
------
InteractionNotSupported
If the given interaction does not have a corresponding
implementation for the wrapped UI target.
"""
supported = []
for registry in self._registries:
try:
handler = registry._get_handler(
target=self._target,
interaction=interaction,
)
except InteractionNotSupported as e:
supported.extend(e.supported)
continue
else:
context = (
_event_processed
if self._auto_process_events
else _nullcontext
)
with context():
return handler(self, interaction)
raise InteractionNotSupported(
target_class=self._target.__class__,
interaction_class=interaction.__class__,
supported=supported,
)
def _get_next_target(self, location):
"""Return the next UI target from the given location.
Parameters
----------
location : instance of locator type
A location for resolving the next target.
Returns
-------
new_target : any
Raises
------
LocationNotSupport
If no solver are provided for resolving the given location in the
wrapped UI target.
"""
supported = set()
for registry in self._registries:
try:
handler = registry._get_solver(
target=self._target,
location=location,
)
except LocationNotSupported as e:
supported |= set(e.supported)
else:
if self._auto_process_events:
with _reraise_exceptions():
_process_cascade_events()
return handler(self, location)
raise LocationNotSupported(
target_class=self._target.__class__,
locator_class=location.__class__,
supported=list(supported),
)
@contextmanager
def _event_processed():
"""Context manager to ensure GUI events are processed upon entering
and exiting the context.
"""
with _reraise_exceptions():
_process_cascade_events()
try:
yield
finally:
_process_cascade_events()
@contextmanager
def _nullcontext():
"""Equivalent to contextlib.nullcontext() in Python >= 3.7"""
yield
