hbutils.testing.generator.matrix

Matrix combination generator for test case construction.

This module implements a matrix-based test case generator similar to the matrix strategy of GitHub Actions. It produces the cartesian product of parameter values and supports additional inclusion and exclusion rules to fine-tune the resulting cases.

The module exposes the following public component:

• MatrixGenerator - Generate all matrix combinations with optional include and exclude rules.

Example:

>>> from hbutils.testing.generator.matrix import MatrixGenerator
>>> gen = MatrixGenerator(
...     {'a': [1, 2], 'b': ['x', 'y']},
...     includes=[{'a': 3, 'b': 'z'}],
...     excludes=[{'a': 1, 'b': 'x'}]
... )
>>> for case in gen.cases():
...     print(case)
{'a': 1, 'b': 'y'}
{'a': 2, 'b': 'x'}
{'a': 2, 'b': 'y'}
{'a': 3, 'b': 'z'}

Note

Include and exclude items are normalized to tuples internally to align with the behavior of the base generator.

MatrixGenerator

class hbutils.testing.generator.matrix.MatrixGenerator(values: Mapping[str, Any], names: List[str] | None = None, includes: List[Mapping[str, Any]] | None = None, excludes: List[Mapping[str, Any]] | None = None)

Full matrix model, all the cases in this matrix will be iterated.

This generator creates a cartesian product of all provided parameter values, with optional inclusions and exclusions to customize the generated test cases.

__init__(values: Mapping[str, Any], names: List[str] | None = None, includes: List[Mapping[str, Any]] | None = None, excludes: List[Mapping[str, Any]] | None = None) → None

Constructor of the MatrixGenerator class.

It is similar to GitHub Action’s matrix strategy, generating all combinations of the provided values with support for custom inclusions and exclusions. Include and exclude mappings are normalized so that every value is a tuple.

Parameters:

• values (Mapping[str, Any]) – Matrix values, such as {'a': [2, 3], 'b': ['b', 'c']}.

• names (Optional[List[str]]) – Names of the given generator, default is None which means use the sorted key set of the values.

• includes (Optional[List[Mapping[str, Any]]]) – Include items, such as [{'a': 4, 'b': 'b'}], default is None which means no extra inclusions.

• excludes (Optional[List[Mapping[str, Any]]]) – Exclude Items, such as [{'a': 2, 'b': 'c'}], default is None which means no extra exclusions.

Raises:

KeyError – If include or exclude items contain keys not in values.

Example::

>>> gen = MatrixGenerator(
...     {'a': [1, 2], 'b': ['x', 'y']},
...     includes=[{'a': 3, 'b': 'z'}],
...     excludes=[{'a': 1, 'b': 'x'}]
... )

cases() → Iterator[Mapping[str, Any]]

Get the cases in this matrix.

Generates all possible combinations of the matrix values, applying exclusions and inclusions as specified. The method performs a cartesian product of all parameter values, then filters based on exclude rules, and finally adds any specified include cases.

Returns:

Iterator yielding dictionaries representing each test case.

Return type:

Iterator[Mapping[str, Any]]

Examples::

>>> from hbutils.testing import MatrixGenerator
>>> for p in MatrixGenerator(
...         {'a': [1, 2, 3], 'b': ['a', 'b'], 'r': [3, 4, 5]},
...         includes=[{'a': 4, 'r': 7}],
...         excludes=[{'a': 1, 'r': 3}, {'a': 3, 'b': 'b'}, {'a': 4, 'b': 'a', 'r': 7}]
... ).cases():
...     print(p)
{'a': 1, 'b': 'a', 'r': 4}
{'a': 1, 'b': 'a', 'r': 5}
{'a': 1, 'b': 'b', 'r': 4}
{'a': 1, 'b': 'b', 'r': 5}
{'a': 2, 'b': 'a', 'r': 3}
{'a': 2, 'b': 'a', 'r': 4}
{'a': 2, 'b': 'a', 'r': 5}
{'a': 2, 'b': 'b', 'r': 3}
{'a': 2, 'b': 'b', 'r': 4}
{'a': 2, 'b': 'b', 'r': 5}
{'a': 3, 'b': 'a', 'r': 3}
{'a': 3, 'b': 'a', 'r': 4}
{'a': 3, 'b': 'a', 'r': 5}
{'a': 4, 'b': 'b', 'r': 7}

property excludes: List[Mapping[str, Tuple[Any, ...]]]

Get the exclude items.

Exclude items are parameter combinations that will be filtered out from the generated cases. A case is excluded if it matches all key-value pairs in any exclude item. Each value in the mapping is normalized to a tuple of values.

Returns:

List of exclude item mappings.

Return type:

List[Mapping[str, Tuple[Any, …]]]

property includes: List[Mapping[str, Tuple[Any, ...]]]

Get the include items.

Include items are additional parameter combinations that will be added to the generated cases, even if they don’t fit the original matrix values. Each value in the mapping is normalized to a tuple of values.

Returns:

List of include item mappings.

Return type:

List[Mapping[str, Tuple[Any, …]]]