qa-testing-utils 0.1.0__py3-none-any.whl

qa_testing_utils-0.1.0.dist-info/METADATA

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: qa-testing-utils
+Version: 0.1.0
+Summary: Testing utilities library for QA automation
+Author-email: Adrian Herscu <adrian.herscu@gmail.com>
+Requires-Python: >=3.13
+Requires-Dist: allure-pytest
+Requires-Dist: more-itertools
+Requires-Dist: ppretty
+Requires-Dist: pyfunctional
+Requires-Dist: pyhamcrest
+Requires-Dist: returns
+Description-Content-Type: text/markdown
+
+# qa-testing-utils

qa_testing_utils-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+utils/__init__.py,sha256=evRL7IFTg2oPJ1I9Xh10Iz6x6CmVp7QhpOKjtfcf8oA,85
+utils/exception_utils.py,sha256=e-AT0jZmtCoNd3esv9U-A8YElu7Nj4qVwJ1aHqyPJyE,1340
+utils/exceptions.py,sha256=_s7es20G9-ET2HeLqU0yhuDAXpnQQs_ecjBmztz94Pk,441
+utils/file_utils.py,sha256=UITm-8RbEajIeCKASJVqyK-l0xN29iNwOl5UeZngTKg,6311
+utils/logger.py,sha256=iuar3asVT4VnK4pqaOTdUetP7vaBsan9-Za_4nDMsCI,4123
+utils/matchers.py,sha256=7O22-tNiS-j1k8xBHDeAyH5aEEpwWlq_fopL-e-AlRY,12510
+utils/object_utils.py,sha256=0CtfGPrR-s9d2OHlOwfzUfWH-NLvS7rwelSvM2mS6Rg,5807
+utils/stream_utils.py,sha256=nbAwL7Nh2jhA6qoTkyAfCX5UNJHjHBNo-4kOGszLqjc,729
+utils/string_utils.py,sha256=L2hRnwnRciaW5rwY_kmuBRb9zC65VPyAGcYt-HnXt18,2616
+utils/thread_utils.py,sha256=73oW55OAJNqoZ-6y7B7te07CLLT4y-9sQJ831fcWpUk,293
+utils/tuple_utils.py,sha256=pIcJntr-PNvaOIP0Pv4sBwO7oIbTVFmGwr9Ic5nJDA0,1851
+qa_testing_utils-0.1.0.dist-info/METADATA,sha256=L9rw_9O9NlKG7VFuwYiGrq3m3B6WHxFPNq5Q7eL-pGc,410
+qa_testing_utils-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+qa_testing_utils-0.1.0.dist-info/RECORD,,

qa_testing_utils-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

utils/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0

utils/exception_utils.py

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import functools
+import logging
+from typing import Any, Callable
+
+from returns.maybe import Maybe, Nothing, Some
+from qa.testing.utils.object_utils import Supplier
+
+
+def safely[T](supplier: Supplier[T]) -> Maybe[T]:
+    """
+    Calls a function safely, wrapping its result in Maybe, and swallowing any exceptions.
+    The function should be a no-argument callable::
+
+        safely(lambda: call_something_that_may_fail(params))
+
+    Args:
+        supplier (Supplier[T]): The supplier to be called.
+
+    Returns:
+        Maybe[T]: The result wrapped in Maybe, or Nothing if an exception occurs.
+    """
+    try:
+        result = supplier()
+        return Some(result)
+    except Exception as e:
+        logging.exception(f"Exception occurred: {e}")
+        return Nothing
+
+
+def swallow(func: Callable[..., Any]) -> Callable[..., Any]:
+    """
+    Decorates a function to swallow any exceptions.
+
+    If an exception will occur, None will be returned.
+
+    Args:
+        func (Callable): the function, supplied by the run-time
+
+    Returns:
+        Callable: the decorated function
+    """
+    @functools.wraps(func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return safely(lambda: func(*args, **kwargs)).value_or(None)
+
+    return wrapper

utils/exceptions.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+class TestException(Exception):
+    """
+    Marks an exception raised by tests infrastructure. Useful to differentiate
+    between unexpected run-time exceptions, which should be handled as
+    programming errors, and legitimate run-time exceptions such as time-out,
+    not found, etc. The former might be handled via a retry mechanism.
+    """
+    pass

utils/file_utils.py

@@ -0,0 +1,196 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import csv
+from io import DEFAULT_BUFFER_SIZE, BufferedReader, RawIOBase
+from lzma import LZMADecompressor
+from pathlib import Path
+from tarfile import TarInfo, open
+from typing import BinaryIO, Iterable, Iterator, Tuple, final, override
+from zlib import crc32
+
+from more_itertools import peekable
+from qa.testing.utils.logger import *
+from qa.testing.utils.object_utils import *
+from qa.testing.utils.string_utils import *
+
+LAUNCHING_DIR = Path.cwd()
+
+
+@final
+class IterableReader(RawIOBase, LoggerMixin, ImmutableMixin):
+    """
+    I/O read-only stream over iterable of bytes, enabling streaming mode.
+    """
+
+    def __init__(self, chunks: Iterable[bytes]):
+        self._chunks = iter(chunks)
+        self._accumulated_buffer = bytearray()
+
+    @override
+    def readable(self) -> bool:
+        return True
+
+    @override
+    def readinto(self, output_buffer: memoryview) -> int:  # type: ignore
+        # consume chunks, accumulating their bytes up to size of output buffer
+        while len(self._accumulated_buffer) < len(output_buffer) \
+                and (chunk := next(self._chunks, None)) is not None:
+            self.log.debug(f"buffered chunk with length={len(chunk)}")
+            self._accumulated_buffer.extend(chunk)
+
+        # consume accumulated bytes up to size of output buffer
+        consumed_bytes = min(len(self._accumulated_buffer), len(output_buffer))
+        output_buffer[:consumed_bytes] = self._accumulated_buffer[:consumed_bytes]
+
+        # delete consumed bytes, shifting left the accumulated buffer
+        del self._accumulated_buffer[:consumed_bytes]
+
+        self.log.debug(f"consumed {consumed_bytes} bytes")
+        return consumed_bytes
+
+    @staticmethod
+    def from_(
+            chunks: Iterable[bytes],
+            buffer_size: int = DEFAULT_BUFFER_SIZE) -> BinaryIO:
+        """
+        Converts a stream of binary chunks into a BufferedReader.
+
+        You should ensure closing.
+
+        Args:
+            chunks (Iterable[bytes]): stream of binary chunks
+
+        Returns:
+            io.BufferedReader: buffered reader around stream of binary chunks.
+        """
+        return BufferedReader(IterableReader(chunks), buffer_size)
+
+
+# TODO perhaps there should be a writable stream to iterator utility too...
+
+
+def stream_file(
+        file_path: Path,
+        chunk_size: int = DEFAULT_BUFFER_SIZE) -> Iterator[bytes]:
+    """
+    Streams a binary file from disk into an iterator.
+
+    If the iterator is not consumed, the file will be closed when the iterator
+    will be garbage collected.
+
+    Args:
+        file_path (Path): path to file
+        chunk_size (int, optional): the chunk size. Defaults to 8192.
+
+    Yields:
+        Iterator[bytes]: the binary chunks stream
+    """
+    with file_path.open('rb') as f:
+        yield from iter(lambda: f.read(chunk_size), EMPTY_BYTE_STRING)
+
+
+def read_lines(
+        byte_stream: Iterable[bytes],
+        encoding: str = UTF_8,
+        eol: str = LF) -> Iterator[str]:
+    """
+    Converts a stream of binary chunks into stream of text lines.
+    Handles cases where lines are split across chunks.
+
+    Args:
+        byte_stream (Iterable[bytes]): the binary (chunks) stream
+        encoding (str, optional): expected text encoding. Defaults to 'utf-8'.
+        eol (str, optional): expected line-ending. Default to LF.
+
+    Yields:
+        Iterator[str]: stream of text lines, not terminated by EOL marker
+    """
+    has_content = False
+    buffer = bytearray()
+    eol_bytes = eol.encode(encoding)
+
+    for chunk in byte_stream:
+        print(DOT, end=SPACE)
+        has_content = True
+        buffer.extend(chunk)
+        *lines, buffer = buffer.split(eol_bytes)  # keep partial line in buffer
+        trace(f"streaming {len(lines)} lines; leftover {len(buffer)} chars")
+        yield from (line.decode(encoding) for line in lines)
+
+    if buffer:  # yield the leftover
+        yield buffer.decode(encoding)
+
+    if not has_content:
+        trace("no lines")
+
+
+def decompress_xz_stream(compressed_chunks: Iterable[bytes]) -> Iterator[bytes]:
+    """
+    Decompresses XZ stream.
+
+    Args:
+        compressed_chunks (Iterable[bytes]): stream of binary compressed chunks
+
+    Yields:
+        Iterator[bytes]: the decompressed stream
+    """
+    decompressor = LZMADecompressor()
+    return map(decompressor.decompress, compressed_chunks)
+
+
+def extract_files_from_tar(tar_chunks: Iterable[bytes]) -> Iterator[Tuple[TarInfo, bytes]]:
+    """
+    Extracts files from decompressed TAR stream.
+
+    Args:
+        tar_chunks (Iterable[bytes]): stream of decompressed TAR chunks
+
+    Yields:
+        Iterator[Tuple[tarfile.TarInfo, bytes]]: \
+            streams tuples of meta-data and data for each file
+    """
+    with open(fileobj=IterableReader.from_(tar_chunks),
+              mode='r|*') as tar:
+        for member in tar:
+            if member.isfile():
+                extracted_file = tar.extractfile(member)
+                if extracted_file:
+                    yield member, extracted_file.read()
+
+
+def crc32_of(file: BinaryIO, chunk_size: int = DEFAULT_BUFFER_SIZE) -> int:
+    """
+    Calculate the CRC of a binary stream from its current position to its tail,
+    using chunked reading.
+
+    Args:
+        file (BinaryIO): The file object to read data from, starting from its current position.
+        chunk_size (int): The size of chunks to read at a time (default is 8192).
+
+    Returns:
+        int: Calculated CRC value of the remaining file content.
+    """
+    crc_value = 0
+
+    while chunk := file.read(chunk_size):
+        crc_value = crc32(chunk, crc_value)
+
+    return crc_value & 0xFFFFFFFF  # ensure 32-bit unsigned
+
+
+def write_csv(file_path: Path, data_stream: Iterable[dict]):
+    """
+    Writes a stream of flattened telemetry packets to a CSV file.
+
+    Args:
+        file_path: Path to the CSV file to be written.
+        data_stream: Iterable of dictionaries representing the rows to be written.
+    """
+    stream = peekable(data_stream)  # Allow peeking to extract headers
+    with file_path.open(mode="w", newline="") as csv_file:
+        writer = csv.DictWriter(
+            csv_file, fieldnames=list(stream.peek().keys()))
+        writer.writeheader()
+        writer.writerows(stream)

utils/logger.py

@@ -0,0 +1,140 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import inspect
+import logging
+from functools import cached_property, wraps
+from typing import Callable, ParamSpec, TypeVar, cast, final
+
+import allure
+from qa.testing.utils.string_utils import EMPTY, LF
+
+
+def trace[T](value: T) -> T:
+    """Logs at debug level using the invoking module name as the logger."""
+    frame = inspect.currentframe()
+    try:
+        if frame is not None:
+            caller_frame = frame.f_back
+            if caller_frame is not None:
+                caller_module = inspect.getmodule(caller_frame)
+                logger_name = caller_module.__name__ if caller_module else '__main__'
+                logger = logging.getLogger(logger_name)
+                logger.debug(f"=== {value}")
+            else:
+                logging.getLogger(__name__).debug(f"=== {value}")
+        else:
+            logging.getLogger(__name__).debug(f"=== {value}")
+    finally:
+        del frame
+
+    return value
+
+
+def logger[T:type](cls: T) -> T:
+    """
+    Class decorator that injects a logger into annotated class.
+
+    Args:
+        cls (type): automatically provided by the runtime
+
+    Returns:
+        _type_: the decorated class
+    """
+    cls._logger = logging.getLogger(cls.__name__)
+
+    @property
+    def log(self: T) -> logging.Logger:
+        return cast(logging.Logger, getattr(self, '_logger', None))
+
+    cls.log = log
+
+    return cls
+
+
+class LoggerMixin:
+    """
+    Yet another way of adding logging by deriving from this one.
+    """
+    @final
+    @cached_property
+    def log(self) -> logging.Logger:
+        return logging.getLogger(self.__class__.__name__)
+
+    @final
+    def trace[T](self, value: T) -> T:
+        """
+        Logs value at DEBUG level using this logger.
+
+        Use to log something as a value, usually in a lambda expression::
+
+            then.eventually_assert_that(
+                lambda: self.trace(...call some API...),
+                greater_that(0)) \
+
+                .and_....other verifications may follow...
+
+        Args:
+            value (T): the value
+
+        Returns:
+            T: the value
+        """
+        self.log.debug(f"=== {value}")
+        return value
+
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+
+def traced(func: Callable[P, R]) -> Callable[P, R]:
+    """
+    Method decorator that logs the function call with its arguments and the
+    return value.
+
+    Args:
+        func (Callable[P, R]): The function to be decorated.
+        *args (Any): Positional arguments to be passed to the function.
+        **kwargs (Any): Keyword arguments to be passed to the function.
+
+    Returns:
+        Callable[P, R]: The result of the function call.
+    """
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        # NOTE: each time a decorated function is called this logic will be
+        # re-evaluated.
+        signature = inspect.signature(func)
+        parameters = list(signature.parameters.keys())
+
+        if parameters and parameters[0] == 'self' and len(args) > 0:
+            instance = args[0]
+            logger = logging.getLogger(f"{instance.__class__.__name__}")
+            logger.debug(
+                f">>> {func.__name__} "
+                f"{", ".join([str(arg) for arg in args[1:]])} "
+                f"{LF.join(
+                    f"{key}={str(value)}"
+                    for key, value in kwargs.items()) if kwargs else EMPTY}")
+
+            with allure.step(  # type: ignore
+                    f"{func.__name__} "
+                    f"{', '.join([str(arg) for arg in args[1:]])}"):
+                result = func(*args, **kwargs)
+
+            if result == instance:
+                logger.debug(f"<<< {func.__name__}")
+            else:
+                logger.debug(f"<<< {func.__name__} {result}")
+
+            return result
+        else:
+            logger = logging.getLogger(func.__name__)
+            logger.debug(f">>> {func.__name__} {args} {kwargs}")
+            result = func(*args, **kwargs)
+            logger.debug(f"<<< {func.__name__} {result}")
+            return result
+
+    return wrapper

utils/matchers.py

@@ -0,0 +1,371 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from datetime import date, datetime
+from typing import (Any, Callable, Iterable, Iterator, List, Optional, Sequence,
+                    Union, cast, final, override)
+
+from hamcrest.core.base_matcher import BaseMatcher
+from hamcrest.core.description import Description
+from hamcrest.core.helpers.wrap_matcher import wrap_matcher
+from hamcrest.core.matcher import Matcher
+
+from qa.testing.utils.logger import LoggerMixin
+
+
+class TracingMatcher[T](BaseMatcher[T], LoggerMixin):
+    """
+    A matcher wrapper that adds debug logging around another matcher.
+    """
+
+    def __init__(self, matcher: Matcher[T]) -> None:
+        self._matcher = matcher
+
+    def _matches(self, item: Any) -> bool:
+        result = self._matcher.matches(item)
+        self.log.debug(f"{item!r} -> {result}")
+        return result
+
+    def describe_to(self, description: Description) -> None:
+        self._matcher.describe_to(description)
+
+
+def traced[T](matcher: Matcher[T]) -> TracingMatcher[T]:
+    """
+    Wraps a matcher with TraceMatcher to enable debug logging.
+
+    Usage:
+        assert_that(actual, trace(contains_string("hello")))
+    """
+    return TracingMatcher(matcher)
+
+
+class ContainsStringIgnoringCase(BaseMatcher[str]):
+    def __init__(self, substring: str) -> None:
+        self.substring: str = substring.lower()
+
+    def _matches(self, item: Any) -> bool:
+        if not isinstance(item, str):
+            return False
+        return self.substring in item.lower()
+
+    def describe_to(self, description: Description) -> None:
+        description.append_text(
+            f"a string containing (case-insensitive) '{self.substring}'")
+
+
+def contains_string_ignoring_case(substring: str) -> ContainsStringIgnoringCase:
+    return ContainsStringIgnoringCase(substring)
+
+
+@final
+class IsIteratorYielding[T](BaseMatcher[Iterator[T]]):
+    """
+    Matcher for data yielded by iterators.
+    """
+
+    def __init__(self, element_matcher: Matcher[T]) -> None:
+        self.element_matcher = element_matcher
+
+    @override
+    def _matches(self, item: Iterable[T]) -> bool:
+        try:
+            for element in item:
+                if self.element_matcher.matches(element):
+                    return True
+        except TypeError:  # not an iterator
+            pass
+        return False
+
+    @override
+    def describe_to(self, description: Description) -> None:
+        description.append_text("a stream containing ") \
+            .append_description_of(self.element_matcher)
+
+# TODO IsStreamContainingEvery
+
+
+@final
+class IsStreamContainingEvery[T](BaseMatcher[Iterator[T]]):
+    """
+    Matcher to ensure every element yielded by an iterator matches a given matcher.
+    """
+
+    def __init__(self, element_matcher: Matcher[T]) -> None:
+        self.element_matcher = element_matcher
+
+    @override
+    def _matches(self, item: Iterable[T]) -> bool:
+        try:
+            for element in item:
+                if not self.element_matcher.matches(element):
+                    return False  # One non-matching element means failure
+            return True  # All elements matched
+        except TypeError:  # not an iterator
+            pass
+        return False
+
+    @override
+    def describe_to(self, description: Description) -> None:
+        description.append_text("a stream where every item is ") \
+            .append_description_of(self.element_matcher)
+
+
+@final
+class IsIteratorYieldingAll[T](BaseMatcher[Iterator[T]]):
+    """
+    Matcher to ensure that the iterator yields at least one instance of each specified matcher.
+    """
+
+    def __init__(self, element_matchers: List[Matcher[T]]) -> None:
+        self.element_matchers = element_matchers
+
+    @override
+    def _matches(self, item: Iterable[T]) -> bool:
+        unmatched_matchers = set(self.element_matchers)
+        try:
+            for element in item:
+                unmatched_matchers = {
+                    m for m in unmatched_matchers if not m.matches(element)}
+                if not unmatched_matchers:  # All matchers have been satisfied
+                    return True
+        except TypeError:  # not an iterator
+            pass
+        return False
+
+    @override
+    def describe_to(self, description: Description) -> None:
+        description.append_text("a stream containing each of: ")
+        for index, matcher in enumerate(self.element_matchers):
+            if index > 0:
+                description.append_text(", ")
+            description.append_description_of(matcher)
+
+
+DateOrDateTime = Union[date, datetime]
+
+
+class IsWithinDates(BaseMatcher[DateOrDateTime]):
+    def __init__(
+            self, start_date: Optional[DateOrDateTime],
+            end_date: Optional[DateOrDateTime]) -> None:
+        self.start_date = start_date
+        self.end_date = end_date
+
+    def _matches(self, item: Optional[DateOrDateTime]) -> bool:
+        if not isinstance(item, (date, datetime)):
+            return False
+
+        # Convert item to a consistent type for comparison
+        if isinstance(item, datetime):
+            item = item.date() if isinstance(
+                self.start_date, date) or isinstance(
+                self.end_date, date) else item
+        elif isinstance(item, date) and (isinstance(self.start_date, datetime) or isinstance(self.end_date, datetime)):
+            item = datetime.combine(item, datetime.min.time())
+
+        # Convert start_date and end_date to compatible types if they are not None
+        start = self.start_date
+        if start is not None:
+            start = start.date() if isinstance(
+                start, datetime) and isinstance(item, date) else start
+
+        end = self.end_date
+        if end is not None:
+            end = end.date() if isinstance(
+                end, datetime) and isinstance(
+                item, date) else end
+
+        # Perform the comparison, handling open-ended ranges
+        if start is None and end is not None:
+            return item <= end
+        elif start is not None and end is None:
+            return item >= start
+        elif start is not None and end is not None:
+            return start <= item <= end
+
+        # If both start_date and end_date are None, return False (no valid range)
+        return False
+
+    def describe_to(self, description: Description) -> None:
+        if self.start_date is None:
+            description.append_text(f"a date before {self.end_date}")
+        elif self.end_date is None:
+            description.append_text(f"a date after {self.start_date}")
+        else:
+            description.append_text(
+                f"a date within {self.start_date} and {self.end_date}")
+
+
+def within_dates(
+        start_date: Optional[DateOrDateTime],
+        end_date: Optional[DateOrDateTime]) -> IsWithinDates:
+    return IsWithinDates(start_date, end_date)
+
+
+def yields_item[T](match: Union[Matcher[T], T]) -> Matcher[Iterator[T]]:
+    """
+    Matches if any element of yielded by iterator matches a given matcher.
+
+    :param match: The matcher to satisfy, or an expected value for
+        :py:func:`~hamcrest.core.core.isequal.equal_to` matching.
+
+    This matcher iterates the evaluated iterator, searching for any element
+    that satisfies a given matcher. If a matching element is found,
+    ``has_item`` is satisfied.
+
+    If the ``match`` argument is not a matcher, it is implicitly wrapped in an
+    :py:func:`~hamcrest.core.core.isequal.equal_to` matcher to check for
+    equality.
+    """
+    return IsIteratorYielding(wrap_matcher(match))
+
+
+def yields_every[T](match: Union[Matcher[T], T]) -> Matcher[Iterator[T]]:
+    """
+    Matches if every element yielded by the iterator matches a given matcher.
+
+    :param match: The matcher to satisfy, or an expected value for equality matching.
+
+    This matcher iterates through the evaluated iterator, checking that every
+    element satisfies the given matcher. If any element does not match, the matcher fails.
+
+    If the `match` argument is not a matcher, it is implicitly wrapped in an
+    equality matcher.
+    """
+    return IsStreamContainingEvery(wrap_matcher(match))
+
+
+def yields_items[T](matches: Iterable[Union[Matcher[T],
+                                            T]]) -> Matcher[Iterator[T]]:
+    """
+    Matches if each specified item is yielded at least once by the iterator.
+
+    :param matches: An iterable of matchers or values, each of which should be yielded
+                    at least once in the iterator for this matcher to succeed.
+
+    This matcher will iterate through the evaluated iterator and check if it yields
+    at least one instance of each specified matcher or value.
+    """
+    wrapped_matchers = [wrap_matcher(match) for match in matches]
+    return IsIteratorYieldingAll(wrapped_matchers)
+
+
+def adapted_object[T, R](
+        converter: Callable[[T], R],
+        matcher: Matcher[R]) -> Matcher[T]:
+    """
+    Hamcrest matcher adapting an object of type T by specified converter and
+    applying specified matcher. For example::
+
+        adapt_object( lambda message: message.id,
+                    is_greater_than(0) )
+
+    where id being a number, and is_greater_than being a matcher that can be
+    applied on numbers.
+
+    See more on `PyHamcrest <https://github.com/hamcrest/PyHamcrest>`
+
+    Args:
+        converter (Callable[[T], R]): function converting T into R
+        matcher (Matcher[R]): matcher for adapted type R
+
+    Returns:
+        Matcher[T]: matcher for target type T
+    """
+    @final
+    class AdaptedMatcher(BaseMatcher[T]):
+        @override
+        def _matches(self, item: T) -> bool:
+            return False if item is None \
+                else matcher.matches(converter(item))
+
+        @override
+        def describe_to(self, description: Description) -> None:
+            description.append_description_of(matcher)
+
+    return AdaptedMatcher()
+
+
+def adapted_sequence[T, R](
+        converter: Callable[[T], R],
+        matcher: Matcher[Sequence[R]]) -> Matcher[Sequence[T]]:
+    """
+    Hamcrest matcher adapting a Sequence of type T by specified converter and
+    applying specified matcher. For example::
+
+        adapt_sequence( lambda message: message.id,
+                    has_item(is_greater_than(0)) )
+
+    where id being a number, and is_greater_than being a matcher that can be
+    applied on numbers.
+
+    See more on `PyHamcrest <https://github.com/hamcrest/PyHamcrest>`
+
+    Args:
+        converter (Callable[[T], R]): function converting T into R
+        matcher (Matcher[Sequence[R]): matcher for adapted Sequence of R
+
+    Returns:
+        Matcher[Sequence[T]]: matcher for target Sequence of type T
+    """
+    @final
+    class AdaptedMatcher(BaseMatcher[Sequence[T]]):
+        @override
+        def _matches(self, item: Sequence[T]) -> bool:
+            return matcher.matches([converter(x) for x in item])
+
+        @override
+        def describe_to(self, description: Description) -> None:
+            description.append_description_of(matcher)
+
+    return AdaptedMatcher()
+
+
+def adapted_iterator[T, R](
+        converter: Callable[[T], R],
+        matcher: Matcher[Iterator[R]]) -> Matcher[Iterator[T]]:
+    """
+    Hamcrest matcher adapting an Iterator of type T by specified converter and
+    applying specified matcher. For example::
+
+        adapt_iterator( lambda message: message.id,
+                    yields_item(is_greater_than(0)) )
+
+    where id being a number, and is_greater_than being a matcher that can be
+    applied on numbers.
+
+    See more on `PyHamcrest <https://github.com/hamcrest/PyHamcrest>`
+
+    Args:
+        converter (Callable[[T], R]): function converting T into R
+        matcher (Matcher[Iterator[R]): matcher for adapted Iterator of R
+
+    Returns:
+        Matcher[Iterator[T]]: matcher for target Iterator of type T
+    """
+    @final
+    class AdaptedMatcher(BaseMatcher[Iterator[T]]):
+        @override
+        def _matches(self, item: Iterable[T]) -> bool:
+            return matcher.matches(map(converter, item))
+
+        @override
+        def describe_to(self, description: Description) -> None:
+            description.append_description_of(matcher)
+
+    return AdaptedMatcher()
+
+
+def match_as[T](matcher: Matcher[object]) -> Matcher[T]:  # type: ignore
+    """
+    Utility function to cast a generic matcher to the specific type Matcher[T].
+
+    Args:
+        matcher: The original matcher that needs to be cast.
+
+    Returns:
+        A matcher cast to Matcher[T].
+    """
+    return cast(Matcher[T], matcher)

utils/object_utils.py

@@ -0,0 +1,185 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import threading
+from dataclasses import asdict, fields, is_dataclass, replace
+from enum import Enum
+from typing import (Any, Callable, Dict, Protocol, Type, final)
+
+# TODO: move to stream_utils module
+type Supplier[T] = Callable[[], T]
+type Predicate[T] = Callable[[T], bool]
+
+
+class Valid(Protocol):
+    """
+    Specifies a method for validating objects.
+    """
+
+    def is_valid(self) -> bool:
+        """
+        Should be implemented by objects that need validation.
+
+        Returns:
+            bool: true, if the object is valid
+        """
+        ...
+
+
+class ImmutableMixin:
+    """
+    Enforces immutability by overriding __setattr__ to raise AttributeError.
+
+    This implementation does not work with the WithMixin if the attributes are
+    initialized with default values.
+
+    It also does not work when applied to a super type for which the __init__
+    is overridden.
+
+    Use it with non-dataclasses.
+    """
+
+    def __setattr__(self, key: str, value: Any) -> None:
+        if hasattr(self, key):
+            raise AttributeError(f"Can't modify attribute '{
+                                 key}' after initialization")
+        super().__setattr__(key, value)  # Properly sets the attribute
+
+
+class WithMixin:
+    '''
+    Supports immutability by copying on change.
+
+    For example, instead of mutating like this::
+
+        obj.field = a_new_value
+
+    use::
+
+        dup_object_with_changes = obj.with_(field=a_new_value)
+
+    This will ensure that the changes are applied on a duplicate of `obj`.
+
+    Can be applied on plain Python classes, and on `dataclases` too.
+    '''
+    @final
+    def with_[T:WithMixin](self: T, **changes: Any) -> T:
+        if is_dataclass(self):
+            # Directly use replace for dataclasses; it will raise an error for invalid fields
+            return replace(self, **changes)
+
+        duplicated_object = self.__class__(**self.__dict__)
+        for key, value in changes.items():
+            # Get the current attribute to determine its type
+            current_attr = getattr(self, key, None)
+            if isinstance(current_attr, Enum):
+                # If the current attribute is an enum,
+                # convert the value to the corresponding enum
+                value = current_attr.__class__(value)
+            setattr(duplicated_object, key, value)
+        return duplicated_object
+
+
+class ToDictMixin:
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Converts a dataclass instance (with nested dataclasses) to a dictionary.
+        """
+        def convert(value):
+            if isinstance(value, ToDictMixin):
+                return value.to_dict()
+            elif isinstance(value, list):
+                return [convert(v) for v in value]
+            elif isinstance(value, dict):
+                return {k: convert(v) for k, v in value.items()}
+            return value
+
+        if not is_dataclass(self):
+            raise TypeError("not a dataclass instance")
+
+        return {key: convert(value) for key, value in asdict(self).items()}
+
+    def flatten(self, prefix: str = "") -> Dict[str, Any]:
+        """
+        Flattens the nested structure into a flat dictionary for CSV serialization.
+        """
+        flat_dict = {}
+
+        def flatten_value(key: str, value: Any):
+            if isinstance(value, ToDictMixin):
+                # Flatten nested ToDictMixin dataclasses
+                nested_flat = value.flatten(prefix=f"{key}_")
+                flat_dict.update(nested_flat)
+            elif isinstance(value, list):
+                # Serialize lists as JSON strings or expand into multiple columns
+                for idx, item in enumerate(value):
+                    flat_dict[f"{key}[{idx}]"] = item
+            elif isinstance(value, dict):
+                # Serialize dicts as JSON strings or expand into multiple columns
+                for sub_key, sub_val in value.items():
+                    flat_dict[f"{key}_{sub_key}"] = sub_val
+            else:
+                # Directly add non-nested fields
+                flat_dict[key] = value
+
+        if not is_dataclass(self):
+            raise TypeError("not a dataclass instance")
+
+        for field in fields(self):
+            value = getattr(self, field.name)
+            flatten_value(f"{prefix}{field.name}", value)
+
+        return flat_dict
+
+
+class SingletonMeta(type):
+    """
+    A thread-safe implementation of a Singleton metaclass.
+    """
+    _instances: Dict[Type['SingletonBase'], 'SingletonBase'] = {}
+    _lock: threading.Lock = threading.Lock()  # Ensure thread-safety
+
+    def __call__(cls, *args: Any, **kwargs: Any) -> 'SingletonBase':
+        with SingletonMeta._lock:
+            if cls not in SingletonMeta._instances:
+                instance = super().__call__(*args, **kwargs)
+                SingletonMeta._instances[cls] = instance
+        return SingletonMeta._instances[cls]
+
+
+class SingletonBase(metaclass=SingletonMeta):
+    """
+    Base class for singletons using SingletonMeta.
+    """
+    pass
+
+
+class InvalidValueException(ValueError):
+    pass
+
+
+def valid[T:Valid](value: T) -> T:
+    """
+    Validates specified object, assuming that it supports the Valid protocol.
+
+    Args:
+        value (T:Valid): the object
+
+    Raises:
+        TypeError: if the object does not support the Valid protocol
+        InvalidValueException: if the object is invalid
+
+    Returns:
+        T:Valid: the validated object
+    """
+    if not (hasattr(value, 'is_valid') and callable(
+            getattr(value, 'is_valid'))):
+        raise TypeError(
+            f"{value.__class__.__name__} does not conform to the Valid protocol")
+
+    if value.is_valid():
+        return value
+    else:
+        raise InvalidValueException(value)

utils/stream_utils.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Iterator
+
+from qa.testing.utils.object_utils import Predicate
+
+
+def process_next[T](i: Iterator[T], p: Predicate[T]) -> Iterator[T]:
+    # DELETEME -- not needed so far
+    """
+    Processes next items per specified predicate. Useful, for cases in which
+    first item in a stream decides the meaning of rest of items.
+
+    Args:
+        i (Iterator[T]): the iterator to process
+        p (Predicate[T]): the predicate to be applied on `next(i)`
+
+    Returns:
+        Iterator[T]: the original iterator if the predicate evaluated true, \
+            otherwise empty iterator
+    """
+    return i if p(next(i)) else iter([])

utils/string_utils.py

@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Callable, Type
+
+from ppretty import ppretty  # type: ignore
+
+EMPTY = ""
+SPACE = " "
+DOT = "."
+LF = "\n"
+UTF_8 = "utf-8"
+EMPTY_BYTE_STRING = b''
+
+
+def to_string[T](indent: str = '    ',
+                 depth: int = 1,
+                 width: int = 72,
+                 seq_length: int = 15,
+                 show_protected: bool = False,
+                 show_private: bool = False,
+                 show_static: bool = False,
+                 show_properties: bool = True,
+                 show_address: bool = False,
+                 str_length: int = 50) -> Callable[[Type[T]], Type[T]]:
+    """
+    Class decorator providing a readable __str__ implementation.
+
+    The default Python __str__ implementation, returns the type and the memory
+    address of instance.
+
+    Important for diagnostics, actually every object that is logged, must
+    provide such readable __str__.
+
+    Args:
+        indent (str, optional): indentation; Defaults to '    '.
+        depth (int, optional): depth in object hierarchy; defaults to 1.
+        width (int, optional): width of line before line-feed; defaults to 72.
+        seq_length (int, optional): how many items to include; defaults to 15.
+        show_protected (bool, optional): include protected; Defaults to False.
+        show_private (bool, optional): include private; defaults to False.
+        show_static (bool, optional): include static; defaults to False.
+        show_properties (bool, optional): include properties; defaults to True.
+        show_address (bool, optional): include object's memory address; defaults to False.
+        str_length (int, optional): maximum string length per item; defaults to 50.
+
+    Returns:
+        Callable[[Type[T]], Type[T]]: _description_
+    """
+    def decorator(cls: Type[T]) -> Type[T]:
+        def __str__(self: T) -> str:
+            # IMPORTANT: must not use something that calls __str__
+            return ppretty(self,
+                           indent=indent,
+                           depth=depth,
+                           width=width,
+                           seq_length=seq_length,
+                           show_protected=show_protected,
+                           show_private=show_private,
+                           show_static=show_static,
+                           show_properties=show_properties,
+                           show_address=show_address,
+                           str_length=str_length)  # type: ignore
+
+        cls.__str__ = __str__
+        return cls
+
+    return decorator

utils/thread_utils.py

@@ -0,0 +1,13 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import concurrent.futures
+import time
+from datetime import timedelta
+
+COMMON_EXECUTOR = concurrent.futures.ThreadPoolExecutor()
+
+
+def sleep_for(duration: timedelta):
+    time.sleep(duration.total_seconds())

utils/tuple_utils.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: 2025 Adrian Herscu
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from dataclasses import is_dataclass, replace, fields
+from typing import Any, Self, Tuple, Type
+
+
+class FromTupleMixin:
+    """
+    Class decorator adding a `from_tuple` method allowing instantiation from
+    a tuple matching the order of decorated class fields.
+
+    Works with frozen dataclasses too.
+    """
+    @classmethod
+    def from_tuple(cls: Type[Self], data: Tuple[Any, ...]) -> Self:
+        if is_dataclass(cls):
+            # Retrieve all fields, including inherited ones
+            cls_fields = [f.name for f in fields(cls)]
+
+            # Create a dictionary of field names to values from the tuple
+            field_values = {name: value for name,
+                            value in zip(cls_fields, data)}
+
+            # Create a new instance using `__new__`
+            instance = cls.__new__(cls)
+
+            # If the dataclass is frozen, use `replace` to set the attributes
+            if getattr(cls, '__dataclass_params__').frozen:
+                return replace(instance, **field_values)
+            else:
+                # If the dataclass is not frozen, use setattr to set attributes
+                for key, value in field_values.items():
+                    setattr(instance, key, value)
+
+                # Call __init__ if defined
+                instance.__init__(*data)
+                return instance
+        else:
+            # For vanilla classes, assume fields are defined in __init__
+            # Using `__init__` directly as the custom initializer
+            instance = cls.__new__(cls)
+            for attr, value in zip(cls.__annotations__.keys(), data):
+                setattr(instance, attr, value)
+
+            # Call __init__ if it expects parameters
+            instance.__init__(*data)
+            return instance