Module Contents

The public interface of the unittest_expander module consists of the following functions, classes, objects 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

Apply this decorator to a test class to generate actual parametrized test methods, i.e., to “expand” parameter collections which have been bound (by applying foreach()) to original test methods.

―

The public interface of expand() includes also the attributes described below.

Two of them make it possible to customize how names of parametrized test methods are generated:

expand.global_name_pattern

Type:str or None Value:None (use the default pattern)

expand.global_name_formatter

Type:string.Formatter-like object or None Value:None (use the default formatter)

Other two allow – respectively – to switch the context ordering style, and to decide whether a certain deprecated, signature-introspection-based feature shall be enabled:

expand.legacy_context_ordering

Type:bool Value:True

expand.legacy_signature_introspection

Type:bool Value:True

Warning

For each of the last two attributes, True (the default value) dictates a deprecated (legacy) behavior, whereas only False is compatible with future versions of unittest_expander.

The foreach() method decorator

@foreach(param_collection)

or

@foreach(*param_collection_items, **param_collection_labeled_items)

Call this function, specifying parameter collections to be bound to a test method, and then apply the resultant decorator to that method (only then it will be possible – by applying expand() to the test class owning the method – to generate actual parametrized test methods).

To learn more about what needs to be passed to foreach(), see the description (below) of the paramseq’s constructor (note that the call signatures of foreach() and that constructor are the same).

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 tuple/str/unicode/bytes/bytearray (in other words, such an object for whom isinstance(obj, collections.abc.Sequence) and not isinstance(obj, (tuple, str, bytes, bytearray)) returns True in Python 3) – for example, a list,

• a mapping (i.e., such an object that isinstance(obj, collections.abc.Mapping) returns True in Python 3) – for example, a dict,

• a set (i.e., such an object that isinstance(obj, collections.abc.Set) returns True in Python 3) – for example, a set or frozenset,

• a callable (i.e., such an object that callable(obj) returns True) which is supposed to:

  • accept one positional argument (the test class) or no arguments at all,
  • return an iterable object (i.e., an object that could be used as a for loop’s subject, able to yield consecutive items)

  – for example, a generator function.

Each item of a parameter collection is supposed to be:

• a param instance,
• a tuple (to be converted automatically to a param which will contain parameter values being the items of that tuple),
• any other object (to be converted automatically to a param which will contain only one parameter value: that object).

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.

Its public interface includes the following methods:

__add__(param_collection)

Returns a new paramseq instance – being a result of concatenation of the paramseq instance we operate on and the given param_collection (see the above description of the paramseq constructor’s argument param_collection…).

__radd__(param_collection)

Returns a new paramseq instance – being a result of concatenation of the given param_collection (see the above description of the paramseq constructor’s argument param_collection…) and the paramseq instance we operate on.

context(context_manager_factory, *its_args, **its_kwargs, _enable_exc_suppress_=False)

Returns a new paramseq instance containing clones of the items of the instance we operate on – each cloned with a param.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.

Its public interface includes the following methods:

context(context_manager_factory, *its_args, **its_kwargs, _enable_exc_suppress_=False)

Returns a new param instance being a clone of the the instance we operate on, 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__() returns True); to enable this possibility you need to set the _enable_exc_suppress_ keyword argument to True.

label(text)

Returns a new param instance being a clone of the instance we operate on, with the specified textual label attached.

The current special object

current

A special singleton object which, when used during execution of a parametrized test method, provides access (in a thread-local manner) to the following properties of the (currently executed) test:

current.label

Type:str Value:the test’s label (which was automatically generated or explicitly specified with param.label()…)

current.context_targets

Type:Sequence Value:the test contexts’ as-targets (i.e., objects returned by __enter__() of each of the context managers which were specified with param.context()…)

current.all_args

Type:Sequence Value:all positional arguments obtained by the currently executed parametrized test method (in particular, including all positional arguments which were passed to the param constructor…)

current.all_kwargs

Type:Mapping Value:all keyword arguments obtained by the currently executed parametrized test method (in particular, including all keyword arguments which were passed to the param constructor…)

current.count

Type:int Value:the consecutive number (within a single application of expand()) of the generated parametrized test method

current.base_name

Type:str Value:the name of the original (non-parametrized) test method

current.base_obj

Type:function Value:the original (non-parametrized) test method itself

Non-essential constants and classes

__version__

The version of unittest_expander as a str being a PEP 440-compliant identifier.

class Substitute(actual_object)

A kind of attribute-access-proxying wrapper, automatically applied by the machinery of expand() to each test method previously decorated with foreach().

The sole constructor argument (actual_object) is the object (typically, a test method) to be proxied.

Apart from exposing in a transparent way nearly all attributes of the proxied object, the public interface of a Substitute includes the following instance attribute:

actual_object

The proxied object itself (unwrapped).

Note

A Substitute instance is never callable – even though (typically) the proxied object is.