Debian Codegraph @

docs/source/traitsui_user_manual/testing/tutorials/first_test.rst

raw
1 .. _testing-tutorial-first-test:
2
3 First simple test
4 =================
5
6 Suppose we have a TraitsUI GUI application like this::
7
8 from traits.api import HasTraits, observe, Str
9 from traitsui.api import TextEditor, Item, View
10
11
12 class Form(HasTraits):
13
14 first_name = Str()
15 last_name = Str()
16 full_name = Str()
17
18 @observe("first_name")
19 @observe("last_name")
20 def _full_name_updated(self, event):
21 self.full_name = " ".join([self.first_name, self.last_name])
22
23 view = View(
24 Item(name="first_name"),
25 Item(name="last_name"),
26 Item(name="full_name", style="readonly"),
27 )
28
29 if __name__ == "__main__":
30 form = Form()
31 form.configure_traits() # GUI appears
32
33 .. figure:: images/first_test/init-app.png
34
35 .. figure:: images/first_test/modified-fields.png
36
37 As a user types in the first two text boxes, the last read only text field will
38 be updated. A test that demonstrates this behavior will need to do the
39 following things:
40
41 #. Open the GUI
42 #. Find the text boxes and the read only display field
43 #. Simulate the user typing in the text boxes
44 #. Inspect and assert the content in the read only field
45
46 Step 1: Creating a GUI
47 ----------------------
48
49 Test code can open and close the GUI using |UITester.create_ui|::
50
51 from traitsui.testing.api import UITester
52
53 form = Form()
54 tester = UITester()
55 with tester.create_ui(form) as ui:
56 pass
57
58 Running this test, you should see the GUI being opened and closed immediately.
59 We will use the ``ui`` (an instance of |UI|) in the next step.
60
61 Step 2: Locating a UI editor
62 ----------------------------
63
64 We need to find the text boxes in order to modify them. |UITester.find_by_name|
65 can be used to find the editors in the UI by names. The names are simply the
66 names used in defining |Item| in the view::
67
68 from traitsui.testing.api import UITester
69
70 form = Form()
71 tester = UITester()
72 with tester.create_ui(form) as ui:
73 first_name_field = tester.find_by_name(ui, "first_name")
74 last_name_field = tester.find_by_name(ui, "last_name")
75 full_name_field = tester.find_by_name(ui, "full_name")
76
77 The ``first_name_field``, ``last_name_field`` and ``full_name_field`` are
78 objects we can use to interact with in the test.
79
80 Step 3: Perform a user interaction to modify GUI state
81 ------------------------------------------------------
82
83 We can find the interactions supported by ``first_name_field`` using
84 |UIWrapper.help| method::
85
86 full_name_field.help()
87
88 will print something like this (abbreviated for the purpose of this section)::
89
90 Interactions
91 ------------
92 <class 'traitsui.testing.tester.command.KeyClick'>
93 An object representing the user clicking a key on the keyboard.
94 ...
95
96 <class 'traitsui.testing.tester.command.KeySequence'>
97 An object representing the user typing a sequence of keys.
98 ...
99
100 <class 'traitsui.testing.tester.command.MouseClick'>
101 An object representing the user clicking a mouse button.
102 ...
103
104 <class 'traitsui.testing.tester.query.DisplayedText'>
105 An object representing an interaction to obtain the displayed
106 (echoed) plain text.
107 ...
108
109 Locations
110 ---------
111 No locations are supported.
112
113 Objects in the "Interactions" section can be used with |UIWrapper.perform|
114 and |UIWrapper.inspect|. To simulate the text boxes being edited, we want to
115 |UIWrapper.perform| an action that represents the user typing a sequence of
116 keys. |KeySequence| is exactly what we need::
117
118 from traitsui.testing.api import KeySequence
119
120 # ...
121 first_name_field.perform(KeySequence("Leia"))
122 last_name_field.perform(KeySequence("Skywalker"))
123
124 Adding this to the existing test, this is what we have::
125
126 from traitsui.testing.api import KeySequence, UITester
127
128 form = Form()
129 tester = UITester()
130 with tester.create_ui(form) as ui:
131 first_name_field = tester.find_by_name(ui, "first_name")
132 first_name_field.perform(KeySequence("Leia"))
133
134 last_name_field = tester.find_by_name(ui, "last_name")
135 last_name_field.perform(KeySequence("Skywalker"))
136
137 We can confirm this behavior visually by setting the |UITester.delay| parameter
138 and run the test again::
139
140 tester = UITester(delay=50) # delay in milliseconds
141
142 Step 4: Inspect the GUI states as the user sees it
143 --------------------------------------------------
144
145 To extract the displayed text in the read only field, we can use
146 |UIWrapper.inspect| with the |DisplayedText| object::
147
148 from traitsui.testing.api import DisplayedText
149 # ...
150 displayed = full_name_field.inspect(DisplayedText())
151 assert displayed == "Leia Skywalker"
152
153 Our final test
154 --------------
155
156 .. code-block::
157
158 from traitsui.testing.api import DisplayedText, KeySequence, UITester
159
160 form = Form()
161 tester = UITester()
162 with tester.create_ui(form) as ui:
163 first_name_field = tester.find_by_name(ui, "first_name")
164 first_name_field.perform(KeySequence("Leia"))
165
166 last_name_field = tester.find_by_name(ui, "last_name")
167 last_name_field.perform(KeySequence("Skywalker"))
168
169 full_name_field = tester.find_by_name(ui, "full_name")
170 displayed = full_name_field.inspect(DisplayedText())
171 assert displayed == "Leia Skywalker"
172
173 If the application is written correctly, the test should pass.
174
175 See the test capturing a bug
176 ----------------------------
177
178 If we forgot to add the :func:`~traits.has_traits.observe` decorators::
179
180 class Form(HasTraits):
181
182 first_name = Str()
183 last_name = Str()
184 full_name = Str()
185
186 # Let's suppose we left these out:
187 # @observe("first_name")
188 # @observe("last_name")
189 def _full_name_updated(self, event):
190 self.full_name = " ".join([self.first_name, self.last_name])
191
192 view = View(
193 Item(name="first_name"),
194 Item(name="last_name"),
195 Item(name="full_name", style="readonly"),
196 )
197
198 The ``full_name`` field won't be updated in the GUI, which would be a bug.
199 If we run the test again, we will get an assertion error:
200
201 .. code-block:: bash
202
203 Traceback (most recent call last):
204 File "first-test.py", line 35, in <module>
205 assert displayed == "Leia Skywalker"
206 AssertionError
207
208 (If the test was written with a testing framework, more failure information on
209 the actual value will be available.)
210
211 What did we learn?
212 ------------------
213
214 - |UITester.create_ui| makes it easy to create and dispose a |UI|. Such a
215 minimal test makes sure the view can be initialized without errors.
216 - |UITester.find_by_name| can be used to find the TraitsUI editor inside a UI
217 for further interactions.
218 - |UIWrapper.perform| can be used to mutate GUI states.
219 - |UIWrapper.inspect| can be used to inspect GUI states.
220 - From the output of |UIWrapper.help|, objects listed in the "Interactions"
221 section can be used with |UIWrapper.perform| and |UIWrapper.inspect|.
222 - The |UITester.delay| parameter can be set to a nonzero value to help with
223 visual confirmation.
224
225
226 .. include:: ../substitutions.rst