Debian Codegraph @

docs/source/traitsui_user_manual/testing/discussions/target_interaction_location.rst

raw
1 .. _testing-target-interaction-location:
2
3 Understanding Target, Interaction and Location
4 ==============================================
5
6 When one writes a test using |UITester|, three categories of objects are
7 involved.
8
9 * Target
10 is an object on which we can perform an action (e.g. a mouse click) to
11 modify an application state, or retrieve a GUI application state, or
12 search for other contained targets (e.g. a table widget that contains
13 buttons and text).
14
15 An instance of |UIWrapper| wraps a target under the protected attribute
16 |UIWrapper._target|.
17
18 * Interaction
19 is an object that wraps the information for performing an action
20 or retrieving GUI state(s), but it does not necessarily contain information
21 to a Target. For example, both |MouseClick| and |DisplayedText| are
22 interactions that can be used against different targets. An interaction can
23 also be specialized for a specific target if needed.
24
25 |UIWrapper.perform| and |UIWrapper.inspect| handle an interaction.
26
27 * Location
28 is an object that wraps the information for searching a target from a
29 container target, but it does not necessarily contain information specific
30 to a Target. For example, both |TargetById| and |TargetByName| are
31 locations for identifying a contained target via an id or a name, which can
32 be used against different targets. A location can also be specialized for a
33 specific target if needed.
34
35 |UIWrapper.locate| resolves a location.
36
37
38 .. _testing-target-is-protected:
39
40 Why is Target protected?
41 ------------------------
42
43 The |UIWrapper._target| attribute is protected because it often exposes
44 implementation details of the GUI component being tested (e.g. it may refer to
45 the Qt specific implementation of a ButtonEditor). Since it is best for tests
46 to avoid dependencies on implementation details, its usage in test code is
47 discouraged.
48
49 However, this attribute is expected to be used while extending the testing API,
50 which inevitably requires knowledge of the implementation details on the tested
51 components. If the implementation details and the testing support code are not
52 maintained together, tests may be subject to breakages caused by changes to
53 implementation details that do not affect the overall behavior. Developers
54 should evaluate based on context whether they should proceed.
55
56
57 .. include:: ../substitutions.rst