traitsui.testing.tester.ui_wrapper module

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.

class traitsui.testing.tester.ui_wrapper.UIWrapper(target, *, registries, delay=0, auto_process_events=True)[source]

Bases: object

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.

delay

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.

Type

int

_target

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.

Type

any

find_by_id(id)[source]

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

Return type

UIWrapper

Raises

LocationNotSupported – If the current target does not support locating another target by a unique identifier.

find_by_name(name)[source]

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

Return type

UIWrapper

Raises

LocationNotSupported – If the current target does not support locating another target by a name.

help()[source]

Print help messages. (This function is intended for interactive use.)

inspect(interaction)[source]

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 values returned for the given inspection. The type should be documented by the interaction type object.

Return type

any

Raises

InteractionNotSupported – If the interaction given is not supported for the current UI target.

See also

UIWrapper.help

locate(location)[source]

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 – A new UIWrapper for the given location.

Return type

UIWrapper

Raises

LocationNotSupported – If the given location is not supported.

See also

UIWrapper.help

perform(interaction)[source]

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