Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Decorators for labeling and modifying behavior of test objects.
4Decorators that merely return a modified version of the original
5function object are straightforward. Decorators that return a new
6function object need to use
7::
9 nose.tools.make_decorator(original_function)(decorator)
11in returning the decorator, in order to preserve meta-data such as
12function name, setup and teardown functions and so on - see
13``nose.tools`` for more information.
15"""
16import collections.abc
17import warnings
19from .utils import SkipTest, assert_warns, HAS_REFCOUNT
21__all__ = ['slow', 'setastest', 'skipif', 'knownfailureif', 'deprecated',
22 'parametrize', '_needs_refcount',]
25def slow(t):
26 """
27 .. deprecated:: 1.21
28 This decorator is retained for compatibility with the nose testing framework, which is being phased out.
29 Please use the nose2 or pytest frameworks instead.
31 Label a test as 'slow'.
33 The exact definition of a slow test is obviously both subjective and
34 hardware-dependent, but in general any individual test that requires more
35 than a second or two should be labeled as slow (the whole suite consists of
36 thousands of tests, so even a second is significant).
38 Parameters
39 ----------
40 t : callable
41 The test to label as slow.
43 Returns
44 -------
45 t : callable
46 The decorated test `t`.
48 Examples
49 --------
50 The `numpy.testing` module includes ``import decorators as dec``.
51 A test can be decorated as slow like this::
53 from numpy.testing import *
55 @dec.slow
56 def test_big(self):
57 print('Big, slow test')
59 """
60 # Numpy 1.21, 2020-12-20
61 warnings.warn('the np.testing.dec decorators are included for nose support, and are '
62 'deprecated since NumPy v1.21. Use the nose2 or pytest frameworks instead.', DeprecationWarning, stacklevel=2)
64 t.slow = True
65 return t
67def setastest(tf=True):
68 """
69 .. deprecated:: 1.21
70 This decorator is retained for compatibility with the nose testing framework, which is being phased out.
71 Please use the nose2 or pytest frameworks instead.
73 Signals to nose that this function is or is not a test.
75 Parameters
76 ----------
77 tf : bool
78 If True, specifies that the decorated callable is a test.
79 If False, specifies that the decorated callable is not a test.
80 Default is True.
82 Notes
83 -----
84 This decorator can't use the nose namespace, because it can be
85 called from a non-test module. See also ``istest`` and ``nottest`` in
86 ``nose.tools``.
88 Examples
89 --------
90 `setastest` can be used in the following way::
92 from numpy.testing import dec
94 @dec.setastest(False)
95 def func_with_test_in_name(arg1, arg2):
96 pass
98 """
99 # Numpy 1.21, 2020-12-20
100 warnings.warn('the np.testing.dec decorators are included for nose support, and are '
101 'deprecated since NumPy v1.21. Use the nose2 or pytest frameworks instead.', DeprecationWarning, stacklevel=2)
102 def set_test(t):
103 t.__test__ = tf
104 return t
105 return set_test
107def skipif(skip_condition, msg=None):
108 """
109 .. deprecated:: 1.21
110 This decorator is retained for compatibility with the nose testing framework, which is being phased out.
111 Please use the nose2 or pytest frameworks instead.
113 Make function raise SkipTest exception if a given condition is true.
115 If the condition is a callable, it is used at runtime to dynamically
116 make the decision. This is useful for tests that may require costly
117 imports, to delay the cost until the test suite is actually executed.
119 Parameters
120 ----------
121 skip_condition : bool or callable
122 Flag to determine whether to skip the decorated test.
123 msg : str, optional
124 Message to give on raising a SkipTest exception. Default is None.
126 Returns
127 -------
128 decorator : function
129 Decorator which, when applied to a function, causes SkipTest
130 to be raised when `skip_condition` is True, and the function
131 to be called normally otherwise.
133 Notes
134 -----
135 The decorator itself is decorated with the ``nose.tools.make_decorator``
136 function in order to transmit function name, and various other metadata.
138 """
140 def skip_decorator(f):
141 # Local import to avoid a hard nose dependency and only incur the
142 # import time overhead at actual test-time.
143 import nose
145 # Numpy 1.21, 2020-12-20
146 warnings.warn('the np.testing.dec decorators are included for nose support, and are '
147 'deprecated since NumPy v1.21. Use the nose2 or pytest frameworks instead.', DeprecationWarning, stacklevel=2)
149 # Allow for both boolean or callable skip conditions.
150 if isinstance(skip_condition, collections.abc.Callable):
151 skip_val = lambda: skip_condition()
152 else:
153 skip_val = lambda: skip_condition
155 def get_msg(func,msg=None):
156 """Skip message with information about function being skipped."""
157 if msg is None:
158 out = 'Test skipped due to test condition'
159 else:
160 out = msg
162 return f'Skipping test: {func.__name__}: {out}'
164 # We need to define *two* skippers because Python doesn't allow both
165 # return with value and yield inside the same function.
166 def skipper_func(*args, **kwargs):
167 """Skipper for normal test functions."""
168 if skip_val():
169 raise SkipTest(get_msg(f, msg))
170 else:
171 return f(*args, **kwargs)
173 def skipper_gen(*args, **kwargs):
174 """Skipper for test generators."""
175 if skip_val():
176 raise SkipTest(get_msg(f, msg))
177 else:
178 yield from f(*args, **kwargs)
180 # Choose the right skipper to use when building the actual decorator.
181 if nose.util.isgenerator(f):
182 skipper = skipper_gen
183 else:
184 skipper = skipper_func
186 return nose.tools.make_decorator(f)(skipper)
188 return skip_decorator
191def knownfailureif(fail_condition, msg=None):
192 """
193 .. deprecated:: 1.21
194 This decorator is retained for compatibility with the nose testing framework, which is being phased out.
195 Please use the nose2 or pytest frameworks instead.
197 Make function raise KnownFailureException exception if given condition is true.
199 If the condition is a callable, it is used at runtime to dynamically
200 make the decision. This is useful for tests that may require costly
201 imports, to delay the cost until the test suite is actually executed.
203 Parameters
204 ----------
205 fail_condition : bool or callable
206 Flag to determine whether to mark the decorated test as a known
207 failure (if True) or not (if False).
208 msg : str, optional
209 Message to give on raising a KnownFailureException exception.
210 Default is None.
212 Returns
213 -------
214 decorator : function
215 Decorator, which, when applied to a function, causes
216 KnownFailureException to be raised when `fail_condition` is True,
217 and the function to be called normally otherwise.
219 Notes
220 -----
221 The decorator itself is decorated with the ``nose.tools.make_decorator``
222 function in order to transmit function name, and various other metadata.
224 """
225 # Numpy 1.21, 2020-12-20
226 warnings.warn('the np.testing.dec decorators are included for nose support, and are '
227 'deprecated since NumPy v1.21. Use the nose2 or pytest frameworks instead.', DeprecationWarning, stacklevel=2)
229 if msg is None:
230 msg = 'Test skipped due to known failure'
232 # Allow for both boolean or callable known failure conditions.
233 if isinstance(fail_condition, collections.abc.Callable):
234 fail_val = lambda: fail_condition()
235 else:
236 fail_val = lambda: fail_condition
238 def knownfail_decorator(f):
239 # Local import to avoid a hard nose dependency and only incur the
240 # import time overhead at actual test-time.
241 import nose
242 from .noseclasses import KnownFailureException
244 def knownfailer(*args, **kwargs):
245 if fail_val():
246 raise KnownFailureException(msg)
247 else:
248 return f(*args, **kwargs)
249 return nose.tools.make_decorator(f)(knownfailer)
251 return knownfail_decorator
253def deprecated(conditional=True):
254 """
255 .. deprecated:: 1.21
256 This decorator is retained for compatibility with the nose testing framework, which is being phased out.
257 Please use the nose2 or pytest frameworks instead.
259 Filter deprecation warnings while running the test suite.
261 This decorator can be used to filter DeprecationWarning's, to avoid
262 printing them during the test suite run, while checking that the test
263 actually raises a DeprecationWarning.
265 Parameters
266 ----------
267 conditional : bool or callable, optional
268 Flag to determine whether to mark test as deprecated or not. If the
269 condition is a callable, it is used at runtime to dynamically make the
270 decision. Default is True.
272 Returns
273 -------
274 decorator : function
275 The `deprecated` decorator itself.
277 Notes
278 -----
279 .. versionadded:: 1.4.0
281 """
282 def deprecate_decorator(f):
283 # Local import to avoid a hard nose dependency and only incur the
284 # import time overhead at actual test-time.
285 import nose
287 # Numpy 1.21, 2020-12-20
288 warnings.warn('the np.testing.dec decorators are included for nose support, and are '
289 'deprecated since NumPy v1.21. Use the nose2 or pytest frameworks instead.', DeprecationWarning, stacklevel=2)
291 def _deprecated_imp(*args, **kwargs):
292 # Poor man's replacement for the with statement
293 with assert_warns(DeprecationWarning):
294 f(*args, **kwargs)
296 if isinstance(conditional, collections.abc.Callable):
297 cond = conditional()
298 else:
299 cond = conditional
300 if cond:
301 return nose.tools.make_decorator(f)(_deprecated_imp)
302 else:
303 return f
304 return deprecate_decorator
307def parametrize(vars, input):
308 """
309 .. deprecated:: 1.21
310 This decorator is retained for compatibility with the nose testing framework, which is being phased out.
311 Please use the nose2 or pytest frameworks instead.
313 Pytest compatibility class. This implements the simplest level of
314 pytest.mark.parametrize for use in nose as an aid in making the transition
315 to pytest. It achieves that by adding a dummy var parameter and ignoring
316 the doc_func parameter of the base class. It does not support variable
317 substitution by name, nor does it support nesting or classes. See the
318 pytest documentation for usage.
320 .. versionadded:: 1.14.0
322 """
323 from .parameterized import parameterized
325 # Numpy 1.21, 2020-12-20
326 warnings.warn('the np.testing.dec decorators are included for nose support, and are '
327 'deprecated since NumPy v1.21. Use the nose2 or pytest frameworks instead.', DeprecationWarning, stacklevel=2)
329 return parameterized(input)
331_needs_refcount = skipif(not HAS_REFCOUNT, "python has no sys.getrefcount")