Module Contents¶
The module unittest_expander
’s public interface consists of the
following functions, classes and constants.
(See: Narrative Documentation – for a much richer description of most of them, including a lot of usage examples…)
The expand()
class decorator¶
-
@
expand
¶
or
-
@
expand
(*, into=globals()) Deprecated since version 0.4.0: The into argument will become illegal in the version 0.5.0.
———
This decorator is intended to be applied to test classes: doing that causes that test parameters – previously attached to related test methods (and/or classes) by decorating them with
foreach()
– are “expanded”, that is, actual parametrized versions of those methods (and/or classes) are generated.The public interface provided by
expand()
includes also the following attributes (making it possible to customize how names of parametrized test methods and classes are generated):-
expand.
global_name_pattern
¶
-
expand.
global_name_formatter
¶
-
The foreach()
method/class decorator¶
-
@
foreach
(param_collection)¶ param_collection must be a parameter collection – that is, one of:
- a
paramseq
instance, - a sequence not being a text string (in other words, such an
object for whom
isinstance(obj, collections.abc.Sequence) and not isinstance(obj, str)
returnsTrue
in Python 3) – for example, alist
, - a mapping (i.e., such an object that
isinstance(obj, collections.abc.Mapping)
returnsTrue
in Python 3) – for example, adict
, - a set (i.e., such an object that
isinstance(obj, collections.abc.Set)
returnsTrue
in Python 3) – for example, aset
orfrozenset
, - a callable (i.e., such an object that
callable(obj)
returnsTrue
) which is supposed: to accept one positional argument (the test class) or no arguments at all, and to return an iterable object (i.e., an object that could be used as afor
loop’s subject, able to yield consecutive items) – for example, a generator.
Any valid parameter collection will be, under the hood, automatically coerced to a
paramseq
.Deprecated since version 0.4.0: A parameter collection given as a tuple (i.e., an instance of the built-in type
tuple
or of a subclass of it, e.g., a named tuple) will become illegal in the version 0.5.0 (note that this deprecation concerns tuples used as parameter collections themselves, not as items of parameter collections; the latter are – and will be – perfectly OK). As a parameter collection, instead of a tuple, use another type (e.g., alist
).Deprecated since version 0.4.3: A parameter collection given as an instance of the Python 3 built-in type
bytes
orbytearray
(or of a subclass thereof) will become illegal in the version 0.5.0.Each item of a parameter collection is supposed to be:
- a
or
-
@
foreach
(*param_collection_items, **param_collection_labeled_items) The total number of given arguments (positional and/or keyword ones) must be greater than 1. Each argument will be treated as a parameter collection’s item (see above); for each keyword argument (if any), its name will be used to
label()
the item it refers to.———
This decorator is intended to be applied to test methods and/or test classes – to attach to those methods (or classes) the test parameters from the specified parameter collection (only then it is possible to generate, by using
expand()
, actual parametrized methods and/or classes…).Deprecated since version 0.4.0: Support for decorating test classes with
foreach()
will be removed in the version 0.5.0.
The paramseq
class¶
-
class
paramseq
(param_collection)¶ param_collection must be a parameter collection – that is, one of:
- a
paramseq
instance, - a sequence not being a text string (in other words, such an
object for whom
isinstance(obj, collections.abc.Sequence) and not isinstance(obj, str)
returnsTrue
in Python 3) – for example, alist
, - a mapping (i.e., such an object that
isinstance(obj, collections.abc.Mapping)
returnsTrue
in Python 3) – for example, adict
, - a set (i.e., such an object that
isinstance(obj, collections.abc.Set)
returnsTrue
in Python 3) – for example, aset
orfrozenset
, - a callable (i.e., such an object that
callable(obj)
returnsTrue
) which is supposed: to accept one positional argument (the test class) or no arguments at all, and to return an iterable object (i.e., an object that could be used as afor
loop’s subject, able to yield consecutive items) – for example, a generator.
Deprecated since version 0.4.0: A parameter collection given as a tuple (i.e., an instance of the built-in type
tuple
or of a subclass of it, e.g., a named tuple) will become illegal in the version 0.5.0 (note that this deprecation concerns tuples used as parameter collections themselves, not as items of parameter collections; the latter are – and will be – perfectly OK). As a parameter collection, instead of a tuple, use another type (e.g., alist
).Deprecated since version 0.4.3: A parameter collection given as an instance of the Python 3 built-in type
bytes
orbytearray
(or of a subclass thereof) will become illegal in the version 0.5.0.Each item of a parameter collection is supposed to be:
- a
or
-
class
paramseq
(*param_collection_items, **param_collection_labeled_items) The total number of given arguments (positional and/or keyword ones) must be greater than 1. Each argument will be treated as a parameter collection’s item (see above); for each keyword argument (if any), its name will be used to
label()
the item it refers to.———
A
paramseq
instance is the canonical form of a parameter collection – whose items areparam
instances.The public interface provided by this class includes the following instance methods:
-
__add__
(param_collection)¶ Returns a new
paramseq
instance – being a result of concatenation of the currentparamseq
instance and given param_collection (see the description of theparamseq
constructor’s argument param_collection…).Deprecated since version 0.4.0: param_collection being a tuple will become illegal in the version 0.5.0.
-
__radd__
(param_collection)¶ Returns a new
paramseq
instance – being a result of concatenation of given param_collection (see the description of theparamseq
constructor’s argument param_collection…) and the currentparamseq
instance.Deprecated since version 0.4.0: param_collection being a tuple will become illegal in the version 0.5.0.
-
context
(context_manager_factory, *its_args, **its_kwargs, _enable_exc_suppress_=False)¶ Returns a new
paramseq
instance contaning clones of the items of the current instance – each cloned with aparam.context()
call (see below), to which all given arguments are passed.
-
The param
class¶
-
class
param
(*args, **kwargs)¶ args and kwargs specify actual (positional and keyword) arguments to be passed to test method call(s).
———
A
param
instance is the canonical form of a parameter collection’s item. It represents a single combination of test parameter values.The public interface provided by this class includes the following instance methods:
-
context
(context_manager_factory, *its_args, **its_kwargs, _enable_exc_suppress_=False)¶ Returns a new
param
instance being a clone of the current instance, with the specified context manager factory (and its arguments) attached.By default, the possibility to suppress exceptions by returning a true value from context manager’s
__exit__()
is disabled (exceptions are propagated even if__exit__()
returnsTrue
); to enable this possibility you need to set the _enable_exc_suppress_ keyword argument toTrue
.
-
Non-essential constants and classes¶
The __version__
constant¶
-
__version__
¶ The version of
unittest_expander
as a PEP 440-compliant identifier (being astr
).
The Substitute
class¶
-
class
Substitute
(actual_object)¶ actual_object is the object to be proxied (typically, it is a test method or test class, previously decorated with
foreach()
).———
Apart from exposing in a transparent way nearly all attributes of the proxied object, the public interface provided by this class includes the following instance attribute:
-
actual_object
¶ The proxied object itself (unwrapped).
Substitute
instances are not callable.-