gha-utils 4.13.3__py3-none-any.whl → 4.14.0__py3-none-any.whl

gha_utils/__init__.py

@@ -17,4 +17,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.13.3"
+__version__ = "4.14.0"

gha_utils/cli.py

@@ -23,22 +23,24 @@ from datetime import datetime
 from pathlib import Path
 from typing import IO
 
+import click
 from click_extra import (
     Choice,
     Context,
+    IntRange,
     argument,
     echo,
     extra_group,
     file_path,
     option,
     pass_context,
-    path,
 )
 
 from . import __version__
 from .changelog import Changelog
 from .mailmap import Mailmap
 from .metadata import Dialects, Metadata
+from .test_plan import DEFAULT_TEST_PLAN, parse_test_plan
 
 
 def is_stdout(filepath: Path) -> bool:
@@ -167,7 +169,7 @@ def metadata(ctx, format, overwrite, output_path):
 @gha_utils.command(short_help="Maintain a Markdown-formatted changelog")
 @option(
     "--source",
-    type=path(exists=True, readable=True, resolve_path=True),
+    type=file_path(exists=True, readable=True, resolve_path=True),
     default="changelog.md",
     help="Changelog source file in Markdown format.",
 )
@@ -268,3 +270,38 @@ def mailmap_sync(ctx, source, create_if_missing, destination_mailmap):
             ctx.exit()
 
     echo(generate_header(ctx) + new_content, file=prep_path(destination_mailmap))
+
+
+@gha_utils.command(short_help="Run a test plan from a file against a binary")
+@option(
+    "--binary",
+    # XXX Wait for https://github.com/janluke/cloup/issues/185 to use the
+    # `file_path` type.
+    type=click.Path(exists=True, executable=True, resolve_path=True),
+    required=True,
+    help="Path to the binary to test.",
+)
+@option(
+    "--plan",
+    type=file_path(exists=True, readable=True, resolve_path=True),
+    help="Test plan in YAML.",
+)
+@option(
+    "-t",
+    "--timeout",
+    type=IntRange(min=0),
+    default=60,
+    help="Set maximum duration in seconds for each CLI call.",
+)
+def test_plan(binary, plan, timeout):
+    # Load test plan from workflow input, or use a default one.
+    if plan:
+        logging.debug(f"Read test plan from {plan}")
+        test_plan = parse_test_plan(plan)
+    else:
+        logging.warning(f"No test plan provided. Default to: {DEFAULT_TEST_PLAN}")
+        test_plan = DEFAULT_TEST_PLAN
+
+    for index, test_case in enumerate(test_plan):
+        logging.info(f"Run test #{index}")
+        test_case.check_cli_test(binary, timeout=timeout)

gha_utils/mailmap.py

@@ -22,7 +22,7 @@ from dataclasses import dataclass, field
 from functools import cached_property
 from subprocess import run
 
-from boltons.iterutils import unique  # type: ignore[import-untyped]
+from boltons.iterutils import unique
 
 
 @dataclass(order=True, frozen=True)

gha_utils/matrix.py

@@ -0,0 +1,279 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+from __future__ import annotations
+
+import itertools
+import json
+import logging
+from typing import Iterable, Iterator
+
+from boltons.dictutils import FrozenDict
+from boltons.iterutils import unique
+
+RESERVED_MATRIX_KEYWORDS = ["include", "exclude"]
+
+
+class Matrix(FrozenDict):
+    """A matrix as defined by GitHub's actions workflows.
+
+    See GitHub official documentation on `how-to implement variations of jobs in a
+    workflow
+    <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow>`_.
+
+    This Matrix behave like a ``dict`` and works everywhere a ``dict`` would. Only that
+    it is immutable and based on :class:`FrozenDict`. If you want to populate the matrix
+    you have to use the following methods:
+
+    - :meth:`add_variation`
+    - :meth:`add_includes`
+    - :meth:`add_excludes`
+
+    The implementation respects the order in which items were inserted. This provides a
+    natural and visual sorting that should ease the inspection and debugging of large
+    matrix.
+    """
+
+    # Tuples are used to keep track of the insertion order and force immutability.
+    include: tuple[dict[str, str], ...] = tuple()
+    exclude: tuple[dict[str, str], ...] = tuple()
+
+    def matrix(
+        self, ignore_includes: bool = False, ignore_excludes: bool = False
+    ) -> dict[str, str]:
+        """Returns a copy of the matrix.
+
+        The special ``include`` and ``excludes`` directives will be added by default.
+        You can selectively ignore them by passing the corresponding boolean parameters.
+        """
+        dict_copy = dict(self)
+        if not ignore_includes and self.include:
+            dict_copy["include"] = self.include
+        if not ignore_excludes and self.exclude:
+            dict_copy["exclude"] = self.exclude
+        return dict_copy
+
+    def __repr__(self) -> str:
+        return (
+            f"<{self.__class__.__name__}: {super(FrozenDict, self).__repr__()}; "
+            f"include={self.include}; exclude={self.exclude}>"
+        )
+
+    def __str__(self) -> str:
+        """Render matrix as a JSON string."""
+        return json.dumps(self.matrix())
+
+    @staticmethod
+    def _check_ids(*var_ids: str) -> None:
+        for var_id in var_ids:
+            if var_id in RESERVED_MATRIX_KEYWORDS:
+                raise ValueError(f"{var_id} cannot be used as a variation ID")
+
+    def add_variation(self, variation_id: str, values: Iterable[str]) -> None:
+        self._check_ids(variation_id)
+        if not values:
+            raise ValueError(f"No variation values provided: {values}")
+        if any(type(v) is not str for v in values):
+            raise ValueError(f"Only strings are accepted in {values}")
+        # Extend variation with values, and deduplicate them along the way.
+        var_values = list(self.get(variation_id, [])) + list(values)
+        super(FrozenDict, self).__setitem__(variation_id, tuple(unique(var_values)))
+
+    def _add_and_dedup_dicts(
+        self, *new_dicts: dict[str, str]
+    ) -> tuple[dict[str, str], ...]:
+        self._check_ids(*(k for d in new_dicts for k in d))
+        return tuple(
+            dict(items) for items in unique((tuple(d.items()) for d in new_dicts))
+        )
+
+    def add_includes(self, *new_includes: dict[str, str]) -> None:
+        """Add one or more ``include`` special directives to the matrix."""
+        self.include = self._add_and_dedup_dicts(*self.include, *new_includes)
+
+    def add_excludes(self, *new_excludes: dict[str, str]) -> None:
+        """Add one or more ``exclude`` special directives to the matrix."""
+        self.exclude = self._add_and_dedup_dicts(*self.exclude, *new_excludes)
+
+    def all_variations(
+        self,
+        with_matrix: bool = True,
+        with_includes: bool = False,
+        with_excludes: bool = False,
+    ) -> dict[str, tuple[str, ...]]:
+        """Collect all variations encountered in the matrix.
+
+        Extra variations mentioned in the special ``include`` and ``exclude``
+        directives will be ignored by default.
+
+        You can selectively expand or restrict the resulting inventory of variations by
+        passing the corresponding ``with_matrix``, ``with_includes`` and
+        ``with_excludes`` boolean filter parameters.
+        """
+        variations = {}
+        if with_matrix:
+            variations = {k: list(v) for k, v in self.items()}
+
+        for expand, directives in (
+            (with_includes, self.include),
+            (with_excludes, self.exclude),
+        ):
+            if expand:
+                for value in directives:
+                    for k, v in value.items():
+                        variations.setdefault(k, []).append(v)
+
+        return {k: tuple(unique(v)) for k, v in variations.items()}
+
+    def product(
+        self, with_includes: bool = False, with_excludes: bool = False
+    ) -> Iterator[dict[str, str]]:
+        """Only returns the combinations of the base matrix by default.
+
+        You can optionally add any variation referenced in the ``include`` and
+        ``exclude`` special directives.
+
+        Respects the order of variations and their values.
+        """
+        variations = self.all_variations(
+            with_includes=with_includes, with_excludes=with_excludes
+        )
+        if not variations:
+            return
+        yield from map(
+            dict,
+            itertools.product(
+                *(
+                    tuple((variant_id, v) for v in variations)
+                    for variant_id, variations in variations.items()
+                )
+            ),
+        )
+
+    def _count_job(self) -> None:
+        self._job_counter += 1
+        if self._job_counter > 256:
+            logging.critical("GitHub job matrix limit of 256 jobs reached")
+
+    def solve(self, strict: bool = False) -> Iterator[dict[str, str]]:
+        """Returns all combinations and apply ``include`` and ``exclude`` constraints.
+
+        .. caution::
+            As per GitHub specifications, all ``include`` combinations are processed
+            after ``exclude``. This allows you to use ``include`` to add back
+            combinations that were previously excluded.
+        """
+        # GitHub jobs fails with the following message if the exclude directive is
+        # referencing keys that are not present in the original base matrix:
+        #   Invalid workflow file: .github/workflows/tests.yaml#L48
+        #   The workflow is not valid.
+        #   .github/workflows/tests.yaml (Line: 48, Col: 13): Matrix exclude key 'state'
+        #   does not match any key within the matrix
+        if strict:
+            unreferenced_keys = set(
+                self.all_variations(
+                    with_matrix=False, with_includes=True, with_excludes=True
+                )
+            ).difference(self)
+            if unreferenced_keys:
+                raise ValueError(
+                    f"Matrix exclude keys {list(unreferenced_keys)} does not match any "
+                    f"{list(self)} key within the matrix"
+                )
+
+        # Reset the number of combinations.
+        self._job_counter = 0
+
+        applicable_includes = []
+        leftover_includes: list[dict[str, str]] = []
+
+        # The matrix is empty, none of the include directive will match, so condider all
+        # directives as un-applicable.
+        if not self:
+            leftover_includes = list(self.include)
+
+        # Search for include directives that matches the original matrix variations
+        # without overwriting their values. Keep the left overs on the side.
+        else:
+            original_variations = self.all_variations()
+            for include in self.include:
+                # Keys shared between the include directive and the original matrix.
+                keys_overlap = set(include).intersection(original_variations)
+                # Collect include directives applicable to the original matrix.
+                if (
+                    # If all overlapping keys in the directive exactly match any value
+                    # of the original matrix, then we are certain the directive can be
+                    # applied without overwriting the original variations.
+                    all(include[k] in original_variations[k] for k in keys_overlap)
+                    # Same if no keys are shared, in which case these extra variations
+                    # will be added to all original ones.
+                    or not keys_overlap
+                ):
+                    applicable_includes.append(include)
+                # Other directives are considered non-applicable and will be returned
+                # as-is at the end of the process.
+                else:
+                    leftover_includes.append(include)
+
+        # Iterates through all the variations of the original matrix, and act on the
+        # matching exclude and include directives.
+        for base_variations in self.product():
+            # Skip the variation if it is fully matching at least one exclude directive.
+            exclusion_candidate = False
+            if any(
+                all(
+                    exclude[k] == base_variations[k]
+                    for k in set(exclude).intersection(base_variations)
+                )
+                for exclude in self.exclude
+            ):
+                exclusion_candidate = True
+
+            # Expand and/or extend the original variation set with applicable include
+            # directives.
+            updated_variations = base_variations.copy()
+            for include in applicable_includes:
+                # Check if the include directive is completely disjoint to the
+                # variations of the original matrix. If that's the case, then we are
+                # supposed to augment the current variation with this include, at it has
+                # already been identified as applicable. But only do that if the updated
+                # variation has not been already updated with a previously evaluated,
+                # more targeted include directive.
+                if set(include).isdisjoint(base_variations):
+                    if set(include).isdisjoint(updated_variations):
+                        updated_variations.update(include)
+                    continue
+
+                # Expand the base variation set with the fully matching include
+                # directive.
+                if all(
+                    include[k] == base_variations[k]
+                    for k in set(include).intersection(base_variations)
+                ):
+                    # Re-instate the variation set as a valid candidate since we found
+                    # an include directive that is explicitly referring to it,
+                    # resurrecting it from the dead.
+                    exclusion_candidate = False
+                    updated_variations.update(include)
+
+            if not exclusion_candidate:
+                self._count_job()
+                yield updated_variations
+
+        # Return as-is all the includes that were not applied to the original matrix.
+        for variation in leftover_includes:
+            self._count_job()
+            yield variation

gha_utils/metadata.py

@@ -28,7 +28,6 @@ doc_files="changelog.md" "readme.md" "docs/license.md"
 is_python_project=true
 package_name=click-extra
 blacken_docs_params=--target-version py37 --target-version py38
-ruff_py_version=py37
 mypy_params=--python-version 3.7
 current_version=2.0.1
 released_version=2.0.0
@@ -151,7 +150,6 @@ import re
 import sys
 from collections.abc import Iterable
 from functools import cached_property
-from itertools import product
 from pathlib import Path
 from random import randint
 from re import escape
@@ -183,6 +181,8 @@ from wcmatch.glob import (
     iglob,
 )
 
+from .matrix import Matrix
+
 SHORT_SHA_LENGTH = 7
 """Default SHA length hard-coded to ``7``.
 
@@ -192,8 +192,6 @@ SHORT_SHA_LENGTH = 7
     depends on the size of the repository.
 """
 
-RESERVED_MATRIX_KEYWORDS = ["include", "exclude"]
-
 
 WorkflowEvent = StrEnum(
     "WorkflowEvent",
@@ -275,14 +273,6 @@ MYPY_VERSION_MIN: Final = (3, 8)
 """
 
 
-class Matrix(dict):
-    """A matrix to used in a GitHub workflow."""
-
-    def __str__(self) -> str:
-        """Render matrix as a JSON string."""
-        return json.dumps(self)
-
-
 class Metadata:
     """Metadata class."""
 
@@ -437,22 +427,24 @@ class Metadata:
                 f"No need to look into the commit history: repository is already checked out at {current_commit}"
             )
 
-        sha_list = []
-        include_list = []
+        matrix = Matrix()
         for commit in commits:
             if past_commit_lookup:
                 logging.debug(f"Checkout to commit {commit.hash}")
                 git.checkout(commit.hash)
 
+            commit_metadata = {
+                "commit": commit.hash,
+                "short_sha": commit.hash[:SHORT_SHA_LENGTH],
+            }
+
             logging.debug(f"Extract project version at commit {commit.hash}")
             current_version = Metadata.get_current_version()
+            if current_version:
+                commit_metadata["current_version"] = current_version
 
-            sha_list.append(commit.hash)
-            include_list.append({
-                "commit": commit.hash,
-                "short_sha": commit.hash[:SHORT_SHA_LENGTH],
-                "current_version": current_version,
-            })
+            matrix.add_variation("commit", [commit.hash])
+            matrix.add_includes(commit_metadata)
 
         # Restore the repository to its initial state.
         if past_commit_lookup:
@@ -462,10 +454,7 @@ class Metadata:
                 logging.debug("Unstash local changes that were previously saved.")
                 git.repo.git.stash("pop")
 
-        return Matrix({
-            "commit": sha_list,
-            "include": include_list,
-        })
+        return matrix
 
     @cached_property
     def event_type(self) -> WorkflowEvent | None:  # type: ignore[valid-type]
@@ -779,23 +768,6 @@ class Metadata:
             )
         return None
 
-    @cached_property
-    def ruff_py_version(self) -> str | None:
-        """Returns the oldest Python version targeted.
-
-        .. caution::
-
-            Unlike ``blacken-docs``, `ruff doesn't support multiple
-            --target-version values
-            <https://github.com/astral-sh/ruff/issues/2857#issuecomment-1428100515>`_,
-            and `only supports the minimum Python version
-            <https://github.com/astral-sh/ruff/issues/2519>`_.
-        """
-        if self.py_target_versions:
-            version = self.py_target_versions[0]
-            return f"py{version.major}{version.minor}"
-        return None
-
     @cached_property
     def mypy_params(self) -> str | None:
         """Generates `mypy` parameters.
@@ -1035,48 +1007,40 @@ class Metadata:
         if not self.script_entries:
             return None
 
-        # In the future, we might support and bridge that matrix with the full CPython
-        # platform support list. See target triples at:
-        # https://peps.python.org/pep-0011/
-        # https://snarky.ca/webassembly-and-its-platform-targets/
-        matrix: dict[str, list[Any]] = {
-            "entry_point": [],
-            # Run the compilation only on the latest supported version of each OS.
-            # The exception is macOS, as macos-15 is arm64 and macos-13 is x64, so we
-            # need both to target the two architectures.
-            # XXX Windows arm64 Windows is considered:
-            # https://github.com/actions/runner-images/issues/10820
-            "os": [
+        matrix = Matrix()
+
+        # Run the compilation only on the latest supported version of each OS. The
+        # exception is macOS, as macos-15 is arm64-only and macos-13 is x64-only, so we
+        # need both to target the two architectures.
+        # XXX arm64 Windows is planned for the future:
+        # https://github.com/actions/runner-images/issues/10820
+        matrix.add_variation(
+            "os",
+            (
                 "ubuntu-24.04",  # x64
                 "ubuntu-24.04-arm",  # arm64
                 "macos-15",  # arm64
                 "macos-13",  # x64
                 "windows-2022",  # x64
-            ],
-            # Extra parameters.
-            "include": [],
-        }
+            ),
+        )
 
         # Augment each entry point with some metadata.
-        extra_entry_point_params = []
         for cli_id, module_id, callable_id in self.script_entries:
             # CLI ID is supposed to be unique, we'll use that as a key.
-            matrix["entry_point"].append(cli_id)
+            matrix.add_variation("entry_point", [cli_id])
             # Derive CLI module path from its ID.
             # XXX We consider here the module is directly callable, because Nuitka
             # doesn't seems to support the entry-point notation.
             module_path = Path(f"{module_id.replace('.', '/')}.py")
             assert module_path.exists()
-            extra_entry_point_params.append(
-                {
-                    "entry_point": cli_id,
-                    "cli_id": cli_id,
-                    "module_id": module_id,
-                    "callable_id": callable_id,
-                    "module_path": str(module_path),
-                },
-            )
-        matrix["include"].extend(extra_entry_point_params)
+            matrix.add_includes({
+                "entry_point": cli_id,
+                "cli_id": cli_id,
+                "module_id": module_id,
+                "callable_id": callable_id,
+                "module_path": str(module_path),
+            })
 
         # We'd like to run a build for each new commit bundled in the action trigger.
         # If no new commits are detected, it's because we are not in a GitHub workflow
@@ -1088,15 +1052,15 @@ class Metadata:
         )
         assert build_commit_matrix
         # Extend the matrix with a new dimension: a list of commits.
-        matrix["commit"] = build_commit_matrix["commit"]
-        matrix["include"].extend(build_commit_matrix["include"])
+        matrix.add_variation("commit", build_commit_matrix["commit"])
+        matrix.add_includes(*build_commit_matrix.include)
 
         # Add platform-specific variables.
         # Arch values are inspired from those specified for self-hosted runners:
         # https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners#architectures
         # Arch is not a matrix variant because support is not widely distributed
         # between different OS.
-        extra_os_params = [
+        matrix.add_includes(
             {
                 "os": "ubuntu-24.04",
                 "platform_id": "linux",
@@ -1127,54 +1091,19 @@ class Metadata:
                 "arch": "x64",
                 "extension": "exe",
             },
-        ]
-        matrix["include"].extend(extra_os_params)
-
-        # Check no extra parameter in reserved directive do not override themselves.
-        all_extra_keys = set().union(
-            *(
-                extras.keys()
-                for reserved_key in RESERVED_MATRIX_KEYWORDS
-                if reserved_key in matrix
-                for extras in matrix[reserved_key]
-            ),
-        )
-        assert all_extra_keys.isdisjoint(RESERVED_MATRIX_KEYWORDS)
-
-        # Produce all variations encoded by the matrix, by skipping the special
-        # directives.
-        all_variations = tuple(
-            tuple((variant_id, value) for value in variant_values)
-            for variant_id, variant_values in matrix.items()
-            if variant_id not in RESERVED_MATRIX_KEYWORDS
         )
 
-        # Emulate collection and aggregation of the 'include' directive to all
-        # variations produced by the matrix.
-        for variant in product(*all_variations):
-            variant_dict = dict(variant)
-
-            # Check each extra parameters from the 'include' directive and accumulate
-            # the matching ones to the variant.
-            full_variant = variant_dict.copy()
-            for extra_params in matrix["include"]:
-                # Check if the variant match the extra parameters.
-                dimensions_to_match = set(variant_dict).intersection(extra_params)
-                d0 = {key: variant_dict[key] for key in dimensions_to_match}
-                d1 = {key: extra_params[key] for key in dimensions_to_match}
-                # Extra parameters are matching the current variant, merge their values.
-                if d0 == d1:
-                    full_variant.update(extra_params)
-
-            # Add to the 'include' directive a new extra parameter that match the
-            # current variant.
-            extra_name_param = variant_dict.copy()
-            # Generate for Nuitka the binary file name to be used that is unique to
-            # this variant.
-            extra_name_param["bin_name"] = (
+        # Augment each variation set of the matrix with a the binary name to be produced
+        # by Nuitka. Itererate over all matrix variation sets so we have all metadata
+        # necessary to generate a unique name specific to these variations.
+        for variations in matrix.solve():
+            # We will re-attach back this binary name to the with an include directive,
+            # so we need a copy the main variants it corresponds to.
+            bin_name_include = {k: variations[k] for k in matrix}
+            bin_name_include["bin_name"] = (
                 "{cli_id}-{platform_id}-{arch}-build-{short_sha}.{extension}"
-            ).format(**full_variant)
-            matrix["include"].append(extra_name_param)
+            ).format(**variations)
+            matrix.add_includes(bin_name_include)
 
         return Matrix(matrix)
 
@@ -1268,7 +1197,6 @@ class Metadata:
             "is_python_project": self.is_python_project,
             "package_name": self.package_name,
             "blacken_docs_params": self.blacken_docs_params,
-            "ruff_py_version": self.ruff_py_version,
             "mypy_params": self.mypy_params,
             "current_version": self.current_version,
             "released_version": self.released_version,
@@ -1296,7 +1224,7 @@ class Metadata:
                     delimiter = f"ghadelimiter_{randint(10**8, (10**9) - 1)}"
                     content += f"{env_name}<<{delimiter}\n{env_value}\n{delimiter}\n"
         else:
-            assert dialect == Dialects.PLAIN
+            assert dialect == Dialects.plain
             content = repr(metadata)
 
         logging.debug(f"Formatted metadata:\n{content}")

gha_utils/test_plan.py

@@ -0,0 +1,226 @@
+# Copyright Kevin Deldycke <kevin@deldycke.com> and contributors.
+#
+# This program is Free Software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
+
+from __future__ import annotations
+
+import re
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from subprocess import run
+from typing import Generator, Sequence
+
+import yaml
+from boltons.iterutils import flatten
+from boltons.strutils import strip_ansi
+from click_extra.testing import args_cleanup, print_cli_run
+
+
+@dataclass(order=True)
+class TestCase:
+    cli_parameters: tuple[str, ...] | str = field(default_factory=tuple)
+    """Parameters, arguments and options to pass to the CLI."""
+
+    exit_code: int | str | None = None
+    strip_ansi: bool = False
+    output_contains: tuple[str, ...] | str = field(default_factory=tuple)
+    stdout_contains: tuple[str, ...] | str = field(default_factory=tuple)
+    stderr_contains: tuple[str, ...] | str = field(default_factory=tuple)
+    output_regex_matches: tuple[str, ...] | str = field(default_factory=tuple)
+    stdout_regex_matches: tuple[str, ...] | str = field(default_factory=tuple)
+    stderr_regex_matches: tuple[str, ...] | str = field(default_factory=tuple)
+    output_regex_fullmatch: str | None = None
+    stdout_regex_fullmatch: str | None = None
+    stderr_regex_fullmatch: str | None = None
+
+    def __post_init__(self) -> None:
+        """Normalize all fields."""
+        for field_id, field_data in asdict(self).items():
+            # Validates and normalize exit code.
+            if field_id == "exit_code":
+                if isinstance(field_data, str):
+                    field_data = int(field_data)
+                elif field_data is not None and not isinstance(field_data, int):
+                    raise ValueError(f"exit_code is not an integer: {field_data}")
+
+            elif field_id == "strip_ansi":
+                if not isinstance(field_data, bool):
+                    raise ValueError(f"strip_ansi is not a boolean: {field_data}")
+
+            # Validates and normalize regex fullmatch fields.
+            elif field_id.endswith("_fullmatch"):
+                if field_data:
+                    if not isinstance(field_data, str):
+                        raise ValueError(f"{field_id} is not a string: {field_data}")
+                # Normalize empty strings to None.
+                else:
+                    field_data = None
+
+            # Validates and normalize tuple of strings.
+            else:
+                # Wraps single string into a tuple.
+                if isinstance(field_data, str):
+                    field_data = (field_data,)
+                if not isinstance(field_data, Sequence):
+                    raise ValueError(
+                        f"{field_id} is not a tuple or a list: {field_data}"
+                    )
+                if not all(isinstance(i, str) for i in field_data):
+                    raise ValueError(
+                        f"{field_id} contains non-string elements: {field_data}"
+                    )
+                # Ignore blank value.
+                field_data = tuple(i.strip() for i in field_data if i.strip())
+
+            # Validates regexps.
+            if field_data and "_regex_" in field_id:
+                for regex in flatten((field_data,)):
+                    try:
+                        re.compile(regex)
+                    except re.error as ex:
+                        raise ValueError(
+                            f"Invalid regex in {field_id}: {regex}"
+                        ) from ex
+
+            setattr(self, field_id, field_data)
+
+    def check_cli_test(self, binary: str | Path, timeout: int | None = None):
+        """Run a CLI command and check its output against the test case.
+
+        ..todo::
+            Add support for environment variables.
+
+        ..todo::
+            Add support for ANSI code stripping.
+
+        ..todo::
+            Add support for proper mixed stdout/stderr stream as a single,
+            intertwined output.
+        """
+        clean_args = args_cleanup(binary, self.cli_parameters)
+        result = run(
+            clean_args,
+            capture_output=True,
+            timeout=timeout,
+            # XXX Do not force encoding to let CLIs figure out by themselves the
+            # contextual encoding to use. This avoid UnicodeDecodeError on output in
+            # Window's console which still defaults to legacy encoding (e.g. cp1252,
+            # cp932, etc...):
+            #
+            #   Traceback (most recent call last):
+            #     File "…\__main__.py", line 49, in <module>
+            #     File "…\__main__.py", line 45, in main
+            #     File "…\click\core.py", line 1157, in __call__
+            #     File "…\click_extra\commands.py", line 347, in main
+            #     File "…\click\core.py", line 1078, in main
+            #     File "…\click_extra\commands.py", line 377, in invoke
+            #     File "…\click\core.py", line 1688, in invoke
+            #     File "…\click_extra\commands.py", line 377, in invoke
+            #     File "…\click\core.py", line 1434, in invoke
+            #     File "…\click\core.py", line 783, in invoke
+            #     File "…\cloup\_context.py", line 47, in new_func
+            #     File "…\mpm\cli.py", line 570, in managers
+            #     File "…\mpm\output.py", line 187, in print_table
+            #     File "…\click_extra\tabulate.py", line 97, in render_csv
+            #     File "encodings\cp1252.py", line 19, in encode
+            #   UnicodeEncodeError: 'charmap' codec can't encode character
+            #   '\u2713' in position 128: character maps to <undefined>
+            #
+            # encoding="utf-8",
+            text=True,
+        )
+        print_cli_run(clean_args, result)
+
+        for field_id, field_data in asdict(self).items():
+            if field_id == "cli_parameters" or (not field_data and field_data != 0):
+                continue
+
+            if field_id == "exit_code":
+                if result.returncode != field_data:
+                    raise AssertionError(
+                        f"CLI exited with code {result.returncode}, "
+                        f"expected {field_data}"
+                    )
+
+            output = ""
+            name = ""
+            if field_id.startswith("output_"):
+                raise NotImplementedError("Output mixing <stdout>/<stderr>")
+                # output = result.output
+                # name = "output"
+            elif field_id.startswith("stdout_"):
+                output = result.stdout
+                name = "<stdout>"
+            elif field_id.startswith("stderr_"):
+                output = result.stderr
+                name = "<stderr>"
+
+            if self.strip_ansi:
+                output = strip_ansi(output)
+
+            if field_id.endswith("_contains"):
+                for sub_string in field_data:
+                    if sub_string not in output:
+                        raise AssertionError(
+                            f"CLI's {name} does not contain {sub_string!r}"
+                        )
+
+            elif field_id.endswith("_regex_matches"):
+                for regex in field_data:
+                    if not re.search(regex, output):
+                        raise AssertionError(
+                            f"CLI's {name} does not match regex {regex!r}"
+                        )
+
+            elif field_id.endswith("_regex_fullmatch"):
+                regex = field_data
+                if not re.fullmatch(regex, output):
+                    raise AssertionError(
+                        f"CLI's {name} does not fully match regex {regex!r}"
+                    )
+
+
+DEFAULT_TEST_PLAN = (
+    # Output the version of the CLI.
+    TestCase(cli_parameters="--version"),
+    # Test combination of version and verbosity.
+    TestCase(cli_parameters=("--verbosity", "DEBUG", "--version")),
+    # Test help output.
+    TestCase(cli_parameters="--help"),
+)
+
+
+def parse_test_plan(plan_path: Path) -> Generator[TestCase, None, None]:
+    plan = yaml.full_load(plan_path.read_text(encoding="UTF-8"))
+
+    # Validates test plan structure.
+    if not plan:
+        raise ValueError(f"Empty test plan file {plan_path}")
+    if not isinstance(plan, list):
+        raise ValueError(f"Test plan is not a list: {plan}")
+
+    directives = frozenset(TestCase.__dataclass_fields__.keys())
+
+    for index, test_case in enumerate(plan):
+        # Validates test case structure.
+        if not isinstance(test_case, dict):
+            raise ValueError(f"Test case #{index + 1} is not a dict: {test_case}")
+        if not directives.issuperset(test_case):
+            raise ValueError(
+                f"Test case #{index + 1} contains invalid directives:"
+                f"{set(test_case) - directives}"
+            )
+
+        yield TestCase(**test_case)

{gha_utils-4.13.3.dist-info → gha_utils-4.14.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: gha-utils
-Version: 4.13.3
+Version: 4.14.0
 Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
 Author-email: Kevin Deldycke <kevin@deldycke.com>
 Project-URL: Homepage, https://github.com/kdeldycke/workflows
@@ -48,10 +48,11 @@ Description-Content-Type: text/markdown
 Requires-Dist: backports.strenum~=1.3.1; python_version < "3.11"
 Requires-Dist: boltons>=24.0.0
 Requires-Dist: bump-my-version>=0.21.0
-Requires-Dist: click-extra~=4.13.2
+Requires-Dist: click-extra~=4.14.1
 Requires-Dist: packaging~=24.1
 Requires-Dist: PyDriller~=2.6
 Requires-Dist: pyproject-metadata~=0.9.0
+Requires-Dist: pyyaml~=6.0.0
 Requires-Dist: tomli~=2.0.1; python_version < "3.11"
 Requires-Dist: wcmatch>=8.5
 Provides-Extra: test
@@ -61,6 +62,8 @@ Requires-Dist: pytest-cases~=3.8.3; extra == "test"
 Requires-Dist: pytest-cov~=6.0.0; extra == "test"
 Requires-Dist: pytest-github-actions-annotate-failures~=0.3.0; extra == "test"
 Requires-Dist: pytest-randomly~=3.16.0; extra == "test"
+Provides-Extra: typing
+Requires-Dist: types-PyYAML~=6.0.12.9; extra == "typing"
 
 # `gha-utils` CLI + reusable workflows
 

gha_utils-4.14.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+gha_utils/__init__.py,sha256=XhzcFkFs63M5SvQuWYvvNyqSQ8Z5nylmJq0ga2xTJGo,866
+gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
+gha_utils/changelog.py,sha256=oahY88A9FRV14f1JSFKIiYrN_TS7Jo3QlljXqJbeuaE,5892
+gha_utils/cli.py,sha256=J6cqO-LlVXmLq0Z5Mmpv34ySbvVzVPqU1-c7iHqqITA,10348
+gha_utils/mailmap.py,sha256=naUqJYJnE3fLTjju1nd6WMm7ODiSaI2SHuJxRtmaFWs,6269
+gha_utils/matrix.py,sha256=_afJD0K-xZLNxwykVnUhD0Gj9cdO0Z43g3VHa-q_tkI,11941
+gha_utils/metadata.py,sha256=YbWPxNwWxcTMj67q6I4adFXgLF11YBv6urAzNopWYHE,48657
+gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gha_utils/test_plan.py,sha256=6Anw8Aa7rlIdJH4XdfZddWjh_Q2VK7Ehq4UJ0cHAt2c,9467
+gha_utils-4.14.0.dist-info/METADATA,sha256=aLM8hgjGOfr2tLuparflwcPmYp21mKW8bKSp3BNMMc8,20288
+gha_utils-4.14.0.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+gha_utils-4.14.0.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
+gha_utils-4.14.0.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
+gha_utils-4.14.0.dist-info/RECORD,,

gha_utils-4.13.3.dist-info/RECORD

@@ -1,12 +0,0 @@
-gha_utils/__init__.py,sha256=G5wydTPH8gma2O_DIBo9f3tS3KUnJNeWKrLBxfSqltw,866
-gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
-gha_utils/changelog.py,sha256=oahY88A9FRV14f1JSFKIiYrN_TS7Jo3QlljXqJbeuaE,5892
-gha_utils/cli.py,sha256=1sgNwDQS9vL5eTUjFXWQVYxtV6LTLRyo4kMnl4Joqg4,9175
-gha_utils/mailmap.py,sha256=snSQBn1BDZ21783l4yCkQc3RLIxh5X6QCunFRkDj-24,6301
-gha_utils/metadata.py,sha256=jREHEbkwDm4OU4Pw_Q0KMRMbOy93_8Gjnccq3DWHq3s,51540
-gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-gha_utils-4.13.3.dist-info/METADATA,sha256=A75KxK1e2Y-5S2vJGtJXWFrAwOSbeEaNGDBRtVi22QY,20179
-gha_utils-4.13.3.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-gha_utils-4.13.3.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
-gha_utils-4.13.3.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
-gha_utils-4.13.3.dist-info/RECORD,,