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.

See also

traitsui.testing.tester.locator.TargetById

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.

See also

traitsui.testing.tester.locator.TargetByName

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