hbutils.testing.generator.base

Test case generation utilities for combinatorial testing workflows.

This module provides foundational utilities and a base class for building test case generators that emit combinations of values. It focuses on normalizing user-provided values into tuples and providing a structured interface for derived generators that implement concrete combination strategies.

The module contains the following main public components:

BaseGenerator - Base class for implementing test case generators

Example:

>>> class SimpleGenerator(BaseGenerator):
...     def cases(self):
...         for a in self.values['a']:
...             for b in self.values['b']:
...                 yield {'a': a, 'b': b}
...
>>> gen = SimpleGenerator({'a': [1, 2], 'b': ['x', 'y']})
>>> list(gen.tuple_cases())
[(1, 'x'), (1, 'y'), (2, 'x'), (2, 'y')]

Note

This module is intended to be extended. The BaseGenerator.cases() method must be implemented in subclasses.

BaseGenerator

class hbutils.testing.generator.base.BaseGenerator(values: Mapping[str, object], names: List[str] | None = None)[source]

Base generator class for creating test case combinations.

This class provides the foundation for generating test cases with different combinations of input values. It stores a mapping of parameter names to their possible values and provides methods to iterate over test cases in different formats.

Subclasses should implement the cases() method to define the specific strategy for generating test case combinations.

Parameters:

values (Mapping[str, object]) – A mapping of parameter names to their possible values. Each value can be a single item or an iterable (list, tuple, generator, range). Single values will be automatically converted to tuples. For example: {'a': [2, 3], 'b': ['x', 'y']}.
names (Optional[List[str]]) – Optional list of parameter names to define the order of parameters. If not provided, uses the sorted keys from values. Default is None.

Variables:

values (Mapping[str, Tuple[object, ...]]) – Mapping of parameter names to tuples of possible values.
names (List[str]) – Ordered list of parameter names to be used for output tuples.

Example:

>>> gen = BaseGenerator({'a': [1, 2], 'b': ['x', 'y']})
>>> gen.names
['a', 'b']
>>> gen.values
{'a': (1, 2), 'b': ('x', 'y')}

__init__(values: Mapping[str, object], names: List[str] | None = None) → None[source]

Initialize the BaseGenerator with values and optional names.

Parameters:

values (Mapping[str, object]) – A mapping of parameter names to their possible values. Each value can be a single item or an iterable (list, tuple, generator, range). Single values will be automatically converted to tuples. For example: {'a': [2, 3], 'b': ['x', 'y']}.
names (Optional[List[str]]) – Optional list of parameter names to define the order of parameters. If not provided, uses the sorted keys from values. Default is None.

Example:

>>> gen = BaseGenerator({'a': [1, 2], 'b': ['x', 'y']})
>>> gen.names
['a', 'b']
>>> gen.values
{'a': (1, 2), 'b': ('x', 'y')}

cases() → Iterator[Mapping[str, object]][source]

Generate test cases as dictionaries.

This is a virtual method that must be implemented in subclasses to define the specific strategy for generating test case combinations.

Returns:: An iterator yielding dictionaries where keys are parameter names and values are the selected values for that test case.
Return type:: Iterator[Mapping[str, object]]
Raises:: NotImplementedError – This method must be implemented by subclasses.

Example:

>>> # In a subclass implementation:
>>> for case in generator.cases():
...     print(case)
{'a': 1, 'b': 'x'}
{'a': 2, 'b': 'y'}

property names: List[str]

Get the ordered list of parameter names.

Returns:: A list of parameter names in the order they should be used.
Return type:: List[str]

Example:

>>> gen = BaseGenerator({'b': [1, 2], 'a': [3, 4]})
>>> gen.names
['a', 'b']

tuple_cases() → Iterator[Tuple[object, ...]][source]

Generate test cases as tuples.

This method converts the dictionary-based cases from cases() into tuples, with values ordered according to names. This format is convenient for use with testing frameworks that expect tuple arguments.

Returns:: An iterator yielding tuples of test case values in the order defined by names.
Return type:: Iterator[Tuple[object, …]]

Example:

>>> # Assuming cases() yields {'a': 1, 'b': 'x'} and {'a': 2, 'b': 'y'}
>>> # and names is ['a', 'b']
>>> for case in generator.tuple_cases():
...     print(case)
(1, 'x')
(2, 'y')

property values: Mapping[str, Tuple[object, ...]]

Get the selection values for test case generation.

Returns:: A mapping of parameter names to tuples of possible values.
Return type:: Mapping[str, Tuple[object, …]]

Example:

>>> gen = BaseGenerator({'a': [1, 2], 'b': 'x'})
>>> gen.values
{'a': (1, 2), 'b': ('x',)}