| 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 |