Source code for traitsui.testing.tester.ui_tester

# (C) Copyright 2004-2022 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 top-level object(s) to support testing TraitsUI applications.
"""

import contextlib

from traitsui.testing._gui import process_cascade_events
from traitsui.testing._exception_handling import reraise_exceptions
from traitsui.testing.tester._ui_tester_registry.default_registry import (
    get_default_registries,
)
from traitsui.testing.tester.ui_wrapper import UIWrapper


[docs]class UITester: """UITester assists testing of GUI applications developed using TraitsUI. See :ref:`testing-traitsui-applications` Section in the User Manual for further details. Parameters ---------- registries : list of TargetRegistry, optional Registries of interaction for different targets, in the order of decreasing priority. If provided, a shallow copy will be made. Additional registries are appended to the list to provide builtin support for TraitsUI UI and editors. delay : int, optional Time delay (in ms) in which actions by the tester 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 tester are performed. Note it is propagated through to created child wrappers. The delay allows visual confirmation test code is working as desired. """ def __init__(self, *, registries=None, delay=0, auto_process_events=True): if registries is None: self._registries = [] else: self._registries = registries.copy() # These registries contribute the support for TraitsUI UI and editors. # The find_by_name/find_by_id methods in this class also depend on # one of these registries. self._registries.extend(get_default_registries()) self.delay = delay self._auto_process_events = auto_process_events @property def auto_process_events(self): """Flag to indicate whether to process (cascade) GUI events automatically. This is propagated through to :class:`~traitsui.testing.tester.ui_wrapper.UIWrapper` instances created from this tester. This value can only be set at instantiation. """ # No mutations post-init are allowed because UIWrapper created prior to # the mutation will not respect the new value, and so it would be # confusing if this attribute was allowed to be mutated. return self._auto_process_events
[docs] @contextlib.contextmanager def create_ui(self, object, ui_kwargs=None): """Context manager to create a UI and dispose it upon exit. This method does not modify the states of the :class:`UITester` and is not a requirement for using other methods on the tester. Parameters ---------- object : HasTraits An instance of HasTraits for which a GUI will be created. ui_kwargs : dict or None, optional Keyword arguments to be provided to ``HasTraits.edit_traits``. Default is to call ``edit_traits`` with no additional keyword arguments. Yields ------ ui : traitsui.ui.UI """ ui_kwargs = {} if ui_kwargs is None else ui_kwargs ui = object.edit_traits(**ui_kwargs) try: yield ui finally: with reraise_exceptions(): if self._auto_process_events: # At the end of a test, there may be events to be # processed. If dispose happens first, those events will be # processed after various editor states are removed, # causing errors. But if we are asked not to process # events, then don't. process_cascade_events() try: ui.dispose() finally: # dispose is not atomic and may push more events to the # event queue. Flush those too unless we are asked not to. if self._auto_process_events: process_cascade_events()
[docs] def find_by_name(self, ui, name): """Find the TraitsUI editor with the given name and return a new ``UIWrapper`` object for further interactions with the editor. ``name`` is typically a value defined on :attr:`traitsui.item.Item.name`. This name is passed onto :func:`traitsui.ui.UI.get_editors`. Parameters ---------- ui : traitsui.ui.UI The UI created, e.g. by ``create_ui``. name : str A single name for retrieving a target on a UI. Returns ------- wrapper : UIWrapper """ return self._get_wrapper(ui).find_by_name(name=name)
[docs] def find_by_id(self, ui, id): """Find the TraitsUI editor with the given identifier and return a new ``UIWrapper`` object for further interactions with the editor. ``id`` is typically a value defined on :attr:`traitsui.item.Item.id` or :attr:`traitsui.group.Group.id`. This provides a shortcut to locate a very nested editor in a view. Parameters ---------- ui : traitsui.ui.UI The UI created, e.g. by ``create_ui``. id : str Id for finding an item in the UI. Returns ------- wrapper : UIWrapper """ return self._get_wrapper(ui).find_by_id(id=id)
def _get_wrapper(self, ui): """Return a new UIWrapper wrapping the given traitsui.ui.UI. Parameters ---------- ui : traitsui.ui.UI The UI created, e.g. by ``create_ui``. Returns ------- wrapper : UIWrapper """ return UIWrapper( target=ui, registries=self._registries, delay=self.delay, auto_process_events=self._auto_process_events, )