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