Debian Codegraph @

docs/source/traits_user_manual/testing.rst

raw
1 .. index:: testing, test trait classes
2
3 Testing
4 =======
5
6 .. _testing_trait_classes:
7
8 Testing Traits Classes
9 ----------------------
10
11 A mixin class is provided to facilitate writing tests for HasTraits classes.
12 The following methods are available when |UnittestTools| is added as a
13 mixin class in the developer's test cases.
14
15 .. autosummary::
16 :nosignatures:
17
18 ~traits.testing.unittest_tools.UnittestTools.assertTraitChanges
19 ~traits.testing.unittest_tools.UnittestTools.assertTraitDoesNotChange
20 ~traits.testing.unittest_tools.UnittestTools.assertMultiTraitChanges
21 ~traits.testing.unittest_tools.UnittestTools.assertTraitChangesAsync
22 ~traits.testing.unittest_tools.UnittestTools.assertEventuallyTrue
23
24 The above assert methods, except |assertEventuallyTrue|, can be used as
25 context managers, which at entry, hook a trait listeners on the class for the
26 desired events and record the arguments passed to the change handler at every
27 fired event. This way the developer can easily assert that specific events
28 have been fired. Further analysis and checking can be performed by inspecting
29 the list of recorded events. Both normal and extended trait names are
30 supported. However, no check is performed regarding the validity of the trait
31 name, thus care is required to safeguard against spelling mistakes in the
32 names of the traits that we need to assert the behaviour.
33
34 The following example demonstrates the basic usage of the mixin class in a
35 TestCase::
36
37 import unittest
38 from traits.api import HasTraits, Float, List, Bool, on_trait_change
39 from traits.testing.api import UnittestTools
40
41
42 class MyClass(HasTraits):
43
44 number = Float(2.0)
45 list_of_numbers = List(Float)
46 flag = Bool
47
48 @on_trait_change('number')
49 def _add_number_to_list(self, value):
50 """ Append the value to the list of numbers. """
51 self.list_of_numbers.append(value)
52
53 def add_to_number(self, value):
54 """ Add the value to `number`. """
55 self.number += value
56
57
58 class MyTestCase(unittest.TestCase, UnittestTools):
59
60 def setUp(self):
61 self.my_class = MyClass()
62
63 def test_when_using_with(self):
64 """ Check normal use cases as a context manager.
65 """
66 my_class = self.my_class
67
68 # Checking for change events
69 with self.assertTraitChanges(my_class, 'number') as result:
70 my_class.number = 5.0
71
72 # Inspecting the last recorded event
73 expected = (my_class, 'number', 2.0, 5.0)
74 self.assertSequenceEqual(result.events, [expected])
75
76 # Checking for specific number of events
77 with self.assertTraitChanges(my_class, 'number', count=3) as result:
78 my_class.flag = True
79 my_class.add_to_number(10.0)
80 my_class.add_to_number(10.0)
81 my_class.add_to_number(10.0)
82
83 expected = [(my_class, 'number', 5.0, 15.0),
84 (my_class, 'number', 15.0, 25.0),
85 (my_class, 'number', 25.0, 35.0)]
86 self.assertSequenceEqual(result.events, expected)
87
88 # Check using extended names
89 with self.assertTraitChanges(my_class, 'list_of_numbers[]'):
90 my_class.number = -3.0
91
92 # Check that event is not fired
93 my_class.number = 2.0
94 with self.assertTraitDoesNotChange(my_class, 'number') as result:
95 my_class.flag = True
96 my_class.number = 2.0 # The value is the same as the original
97
98 Using Mocks
99 -----------
100
101 Trying to mock a method in a |HasStrictTraits| instance will raise an error
102 because the |HasStrictTraits| machinery does not allow any modification of
103 the methods and attributes of a |HasStrictTraits| instance. To circumvent the
104 |HasStrictTraits| machinery, and mock methods using ``unittest.mock`` or
105 `the mock library`_, please follow the logic in the example below::
106
107 from traits.api import HasStrictTraits, Float
108 from unittest.mock import Mock
109
110 class MyClass(HasStrictTraits):
111
112 number = Float(2.0)
113
114 def add_to_number(self, value):
115 """ Add the value to `number`. """
116 self.number += value
117
118 my_class = MyClass()
119
120 # Using my_class.add_to_number = Mock() will fail.
121 # But setting the mock on the instance `__dict__` works.
122 my_class.__dict__['add_to_number'] = Mock()
123
124 # We can now use the mock in our tests.
125 my_class.add_to_number(42)
126 print(my_class.add_to_number.call_args_list)
127
128 .. note::
129
130 The above method will not work for mocking |Property| setters,
131 getters and validators.
132
133 .. _the mock library: https://pypi.python.org/pypi/mock
134 .. |HasStrictTraits| replace:: :class:`~traits.has_traits.HasStrictTraits`
135 .. |UnittestTools| replace:: :class:`~traits.testing.unittest_tools.UnittestTools`
136 .. |Property| replace:: :func:`~traits.traits.Property`
137 .. |assertEventuallyTrue| replace:: :func:`~traits.testing.unittest_tools.UnittestTools.assertEventuallyTrue`