Debian Codegraph @

traits/testing/unittest_tools.py

raw
1 # (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
2 # All rights reserved.
3 #
4 # This software is provided without warranty under the terms of the BSD
5 # license included in LICENSE.txt and may be redistributed only under
6 # the conditions described in the aforementioned license. The license
7 # is also available online at http://www.enthought.com/licenses/BSD.txt
8 #
9 # Thanks for using Enthought open source!
10
11 """ Trait assert mixin class to simplify test implementation for Trait
12 Classes.
13
14 """
15
16 import contextlib
17 import threading
18 import sys
19 import warnings
20
21 # Support for 'from traits.testing.unittest_tools import unittest',
22 # which was used to make unittest2 available under the name unittest
23 # on Python 2.6. We keep the import for now, for backwards compatibility.
24 import unittest # noqa: F401
25
26 from traits.api import (
27 Any,
28 Event,
29 HasStrictTraits,
30 Int,
31 List,
32 Str,
33 Property,
34 )
35 from traits.util.async_trait_wait import wait_for_condition
36
37
38 class _AssertTraitChangesContext(object):
39 """ A context manager used to implement the trait change assert methods.
40
41 Notes
42 -----
43 Checking if the provided xname corresponds to valid traits in the class
44 is not implemented yet.
45
46 Parameters
47 ----------
48 obj : HasTraits
49 The HasTraits class instance whose class trait will change.
50
51 xname : str
52 The extended trait name of trait changes to listen to.
53
54 count : int, optional
55 The expected number of times the event should be fired. When None
56 (default value) there is no check for the number of times the
57 change event was fired.
58
59 test_case : TestCase
60 A unittest TestCase where to raise the failureException if
61 necessary.
62
63 Attributes
64 ----------
65 obj : HasTraits
66 The HasTraits class instance whose class trait will change.
67
68 xname : str
69 The extended trait name of trait changes to listen to.
70
71 count : int, optional
72 The expected number of times the event should be fired. When None
73 (default value) there is no check for the number of times the
74 change event was fired.
75
76 events : list of tuples
77 A list with tuple elements containing the arguments of an
78 `on_trait_change` event signature (<object>, <name>, <old>, <new>).
79
80 Raises
81 ------
82 AssertionError :
83 When the desired number of trait changed did not take place or when
84 `count = None` and no trait change took place.
85
86 """
87
88 def __init__(self, obj, xname, count, test_case):
89 self.obj = obj
90 self.xname = xname
91 self.count = count
92 self.event = None
93 self.events = []
94 self.failureException = test_case.failureException
95
96 def _listener(self, obj, name, old, new):
97 """ Dummy trait listener.
98 """
99 self.event = (obj, name, old, new)
100 self.events.append(self.event)
101
102 def __enter__(self):
103 """ Bind the trait listener.
104 """
105 self.obj.on_trait_change(self._listener, self.xname)
106 return self
107
108 def __exit__(self, exc_type, exc_value, tb):
109 """ Remove the trait listener.
110 """
111 if exc_type is not None:
112 return False
113
114 self.obj.on_trait_change(self._listener, self.xname, remove=True)
115 if self.count is not None and len(self.events) != self.count:
116 msg = "Change event for {0} was fired {1} times instead of {2}"
117 items = self.xname, len(self.events), self.count
118 raise self.failureException(msg.format(*items))
119 elif self.count is None and not self.events:
120 msg = "A change event was not fired for: {0}".format(self.xname)
121 raise self.failureException(msg)
122 return False
123
124
125 @contextlib.contextmanager
126 def reverse_assertion(context, msg):
127 context.__enter__()
128 try:
129 yield context
130 finally:
131 try:
132 context.__exit__(None, None, None)
133 except AssertionError:
134 pass
135 else:
136 raise context.failureException(msg)
137
138
139 class _TraitsChangeCollector(HasStrictTraits):
140 """ Class allowing thread-safe recording of events.
141 """
142
143 # The object we're listening to.
144 obj = Any
145
146 # The (possibly extended) trait name(s).
147 trait_name = Str
148
149 # Read-only event count.
150 event_count = Property(Int)
151
152 # Event that's triggered when the event count is updated.
153 event_count_updated = Event
154
155 # Private list of events.
156 events = List(Any)
157
158 # Private lock used to allow access to events by multiple threads
159 # simultaneously.
160 _lock = Any()
161
162 def __init__(self, **traits):
163 if "trait" in traits:
164 value = traits.pop("trait")
165 message = (
166 "The `trait` keyword is deprecated." " please use `trait_name`"
167 )
168 warnings.warn(message, DeprecationWarning, stacklevel=2)
169 traits["trait_name"] = value
170 super().__init__(**traits)
171
172 # We assign the lock eagerly rather than depending on a lazy default,
173 # since we want to be sure that the lock is created (a) only once,
174 # and (b) on the main thread. Similarly for the events list.
175 self._lock = threading.Lock()
176 self.events = []
177
178 def start_collecting(self):
179 self.obj.on_trait_change(self._event_handler, self.trait_name)
180
181 def stop_collecting(self):
182 self.obj.on_trait_change(
183 self._event_handler, self.trait_name, remove=True
184 )
185
186 def _event_handler(self, new):
187 with self._lock:
188 self.events.append(new)
189 self.event_count_updated = True
190
191 def _get_event_count(self):
192 """ Traits property getter.
193
194 Thread-safe access to event count.
195
196 """
197 with self._lock:
198 return len(self.events)
199
200
201 class UnittestTools(object):
202 """ Mixin class to augment the unittest.TestCase class with useful trait
203 related assert methods.
204
205 """
206
207 def assertTraitChanges(
208 self, obj, trait, count=None, callableObj=None, *args, **kwargs
209 ):
210 """ Assert an object trait changes a given number of times.
211
212 Assert that the class trait changes exactly `count` times during
213 execution of the provided function.
214
215 This method can also be used in a with statement to assert that
216 a class trait has changed during the execution of the code inside
217 the with statement (similar to the assertRaises method). Please note
218 that in that case the context manager returns itself and the user
219 can introspect the information of:
220
221 - The last event fired by accessing the ``event`` attribute of the
222 returned object.
223
224 - All the fired events by accessing the ``events`` attribute of
225 the return object.
226
227 Note that in the case of chained properties (trait 'foo' depends on
228 'bar', which in turn depends on 'baz'), the order in which the
229 corresponding trait events appear in the ``events`` attribute is
230 not well-defined, and may depend on dictionary ordering.
231
232 **Example**::
233
234 class MyClass(HasTraits):
235 number = Float(2.0)
236
237 my_class = MyClass()
238
239 with self.assertTraitChanges(my_class, 'number', count=1):
240 my_class.number = 3.0
241
242 Parameters
243 ----------
244 obj : HasTraits
245 The HasTraits class instance whose class trait will change.
246
247 trait : str
248 The extended trait name of trait changes to listen to.
249
250 count : int or None, optional
251 The expected number of times the event should be fired. When None
252 (default value) there is no check for the number of times the
253 change event was fired.
254
255 callableObj : callable, optional
256 A callable object that will trigger the expected trait change.
257 When None (default value) a trigger is expected to be called
258 under the context manger returned by this method.
259
260 *args :
261 List of positional arguments for ``callableObj``
262
263 **kwargs :
264 Dict of keyword value pairs to be passed to the ``callableObj``
265
266
267 Returns
268 -------
269 context : context manager or None
270 If ``callableObj`` is None, an assertion context manager is
271 returned, inside of which a trait-change trigger can be invoked.
272 Otherwise, the context is used internally with ``callableObj`` as
273 the trigger, in which case None is returned.
274
275 Notes
276 -----
277 - Checking if the provided ``trait`` corresponds to valid traits in
278 the class is not implemented yet.
279 - Using the functional version of the assert method requires the
280 ``count`` argument to be given even if it is None.
281
282 """
283 context = _AssertTraitChangesContext(obj, trait, count, self)
284 if callableObj is None:
285 return context
286 with context:
287 callableObj(*args, **kwargs)
288
289 def assertTraitDoesNotChange(
290 self, obj, trait, callableObj=None, *args, **kwargs
291 ):
292 """ Assert an object trait does not change.
293
294 Assert that the class trait does not change during
295 execution of the provided function.
296
297 Parameters
298 ----------
299 obj : HasTraits
300 The HasTraits class instance whose class trait will change.
301
302 trait : str
303 The extended trait name of trait changes to listen to.
304
305 callableObj : callable, optional
306 A callable object that should not trigger a change in the
307 passed trait. When None (default value) a trigger is expected
308 to be called under the context manger returned by this method.
309
310 *args :
311 List of positional arguments for ``callableObj``
312
313 **kwargs :
314 Dict of keyword value pairs to be passed to the ``callableObj``
315
316
317 Returns
318 -------
319 context : context manager or None
320 If ``callableObj`` is None, an assertion context manager is
321 returned, inside of which a trait-change trigger can be invoked.
322 Otherwise, the context is used internally with ``callableObj`` as
323 the trigger, in which case None is returned.
324
325 """
326 msg = "A change event was fired for: {0}".format(trait)
327 context = _AssertTraitChangesContext(obj, trait, None, self)
328 if callableObj is None:
329 return reverse_assertion(context, msg)
330 with reverse_assertion(context, msg):
331 callableObj(*args, **kwargs)
332
333 @contextlib.contextmanager
334 def assertMultiTraitChanges(
335 self, objects, traits_modified, traits_not_modified
336 ):
337 """ Assert that traits on multiple objects do or do not change.
338
339 This combines some of the functionality of `assertTraitChanges` and
340 `assertTraitDoesNotChange`.
341
342 Parameters
343 ----------
344 objects : list of HasTraits
345 The HasTraits class instances whose traits will change.
346
347 traits_modified : list of str
348 The extended trait names of trait expected to change.
349
350 traits_not_modified : list of str
351 The extended trait names of traits not expected to change.
352
353 """
354 with contextlib.ExitStack() as exit_stack:
355 cms = []
356 for obj in objects:
357 for trait in traits_modified:
358 cms.append(exit_stack.enter_context(
359 self.assertTraitChanges(obj, trait)))
360 for trait in traits_not_modified:
361 cms.append(exit_stack.enter_context(
362 self.assertTraitDoesNotChange(obj, trait)))
363 yield tuple(cms)
364
365 @contextlib.contextmanager
366 def assertTraitChangesAsync(self, obj, trait, count=1, timeout=5.0):
367 """ Assert an object trait eventually changes.
368
369 Context manager used to assert that the given trait changes at
370 least `count` times within the given timeout, as a result of
371 execution of the body of the corresponding with block.
372
373 The trait changes are permitted to occur asynchronously.
374
375 **Example usage**::
376
377 with self.assertTraitChangesAsync(my_object, 'SomeEvent', count=4):
378 <do stuff that should cause my_object.SomeEvent to be
379 fired at least 4 times within the next 5 seconds>
380
381
382 Parameters
383 ----------
384 obj : HasTraits
385 The HasTraits class instance whose class trait will change.
386
387 trait : str
388 The extended trait name of trait changes to listen to.
389
390 count : int, optional
391 The expected number of times the event should be fired.
392
393 timeout : float or None, optional
394 The amount of time in seconds to wait for the specified number
395 of changes. None can be used to indicate no timeout.
396
397 """
398 collector = _TraitsChangeCollector(obj=obj, trait_name=trait)
399
400 # Pass control to body of the with statement.
401 collector.start_collecting()
402 try:
403 yield collector
404
405 # Wait for the expected number of events to arrive.
406 try:
407 wait_for_condition(
408 condition=lambda obj: obj.event_count >= count,
409 obj=collector,
410 trait="event_count_updated",
411 timeout=timeout,
412 )
413 except RuntimeError:
414 actual_event_count = collector.event_count
415 msg = (
416 "Expected {0} event on {1} to be fired at least {2} "
417 "times, but the event was only fired {3} times "
418 "before timeout ({4} seconds)."
419 ).format(trait, obj, count, actual_event_count, timeout)
420 self.fail(msg)
421
422 finally:
423 collector.stop_collecting()
424
425 def assertEventuallyTrue(self, obj, trait, condition, timeout=5.0):
426 """ Assert that the given condition is eventually true.
427
428 Parameters
429 ----------
430 obj : HasTraits
431 The HasTraits class instance whose traits will change.
432
433 trait : str
434 The extended trait name of trait changes to listen to.
435
436 condition : callable
437 A function that will be called when the specified trait
438 changes. This should accept ``obj`` and should return a
439 Boolean indicating whether the condition is satisfied or not.
440
441 timeout : float or None, optional
442 The amount of time in seconds to wait for the condition to
443 become true. None can be used to indicate no timeout.
444
445 """
446 try:
447 wait_for_condition(
448 condition=condition, obj=obj, trait=trait, timeout=timeout
449 )
450 except RuntimeError:
451 # Helpful to know whether we timed out because the
452 # condition never became true, or because the expected
453 # event was never issued.
454 condition_at_timeout = condition(obj)
455 self.fail(
456 "Timed out waiting for condition. "
457 "At timeout, condition was {0}.".format(condition_at_timeout)
458 )
459
460 @contextlib.contextmanager
461 def _catch_warnings(self):
462 """
463 Replacement for warnings.catch_warnings.
464
465 This method wraps warnings.catch_warnings, takes care to
466 reset the warning registry before entering the with context,
467 and ensures that DeprecationWarnings are always emitted.
468
469 The hack to reset the warning registry is no longer needed in
470 Python 3.4 and later. See http://bugs.python.org/issue4180 for
471 more background.
472
473 .. deprecated:: 6.2
474 Use :func:`warnings.catch_warnings` instead.
475
476 """
477 warnings.warn(
478 (
479 "The _catch_warnings method is deprecated. "
480 "Use warnings.catch_warnings instead."
481 ),
482 DeprecationWarning,
483 )
484
485 # Ugly hack copied from the core Python code (see
486 # Lib/test/test_support.py) to reset the warnings registry
487 # for the module making use of this context manager.
488 #
489 # Note that this hack is unnecessary in Python 3.4 and later; see
490 # http://bugs.python.org/issue4180 for the background.
491 registry = sys._getframe(4).f_globals.get("__warningregistry__")
492 if registry:
493 registry.clear()
494
495 with warnings.catch_warnings(record=True) as w:
496 warnings.simplefilter("always", DeprecationWarning)
497 yield w
498
499 @contextlib.contextmanager
500 def assertDeprecated(self):
501 """
502 Assert that the code inside the with block is deprecated. Intended
503 for testing uses of traits.util.deprecated.deprecated.
504
505 """
506 with warnings.catch_warnings(record=True) as w:
507 warnings.simplefilter("always", DeprecationWarning)
508 yield w
509
510 self.assertGreater(
511 len(w),
512 0,
513 msg="Expected a DeprecationWarning, " "but none was issued",
514 )
515
516 @contextlib.contextmanager
517 def assertNotDeprecated(self):
518 """
519 Assert that the code inside the with block is not deprecated. Intended
520 for testing uses of traits.util.deprecated.deprecated.
521
522 """
523 with warnings.catch_warnings(record=True) as w:
524 warnings.simplefilter("always", DeprecationWarning)
525 yield w
526
527 self.assertEqual(
528 len(w),
529 0,
530 msg="Expected no DeprecationWarning, "
531 "but at least one was issued",
532 )