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

gha_utils/__init__.py

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

gha_utils/cli.py

@@ -27,7 +27,7 @@ import click
 from click_extra import (
     Choice,
     Context,
-    IntRange,
+    FloatRange,
     argument,
     echo,
     extra_group,
@@ -279,29 +279,38 @@ def mailmap_sync(ctx, source, create_if_missing, destination_mailmap):
     # `file_path` type.
     type=click.Path(exists=True, executable=True, resolve_path=True),
     required=True,
-    help="Path to the binary to test.",
+    metavar="FILE_PATH",
+    help="Path to the binary file to test.",
 )
 @option(
     "--plan",
     type=file_path(exists=True, readable=True, resolve_path=True),
-    help="Test plan in YAML.",
+    metavar="FILE_PATH",
+    help="Path to the test plan file in YAML. If not provided, a default test "
+    "plan will be executed.",
 )
 @option(
     "-t",
     "--timeout",
-    type=IntRange(min=0),
-    default=60,
-    help="Set maximum duration in seconds for each CLI call.",
+    # Timeout passed to subprocess.run() is a float that is silently clamped to
+    # 0.0 is negative values are provided, so we mimic this behavior here:
+    # https://github.com/python/cpython/blob/5740b95076b57feb6293cda4f5504f706a7d622d/Lib/subprocess.py#L1596-L1597
+    type=FloatRange(min=0, clamp=True),
+    metavar="SECONDS",
+    help="Set the default timeout for each CLI call, if not specified in the "
+    "test plan.",
 )
-def test_plan(binary, plan, timeout):
+def test_plan(binary: Path, plan: Path | None, timeout: float | None) -> None:
     # Load test plan from workflow input, or use a default one.
     if plan:
-        logging.debug(f"Read test plan from {plan}")
+        logging.info(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
+        logging.warning("No test plan provided: use default test plan.")
+        test_plan = DEFAULT_TEST_PLAN  # type: ignore[assignment]
+    logging.debug(f"Test plan: {test_plan}")
 
     for index, test_case in enumerate(test_plan):
-        logging.info(f"Run test #{index}")
-        test_case.check_cli_test(binary, timeout=timeout)
+        logging.info(f"Run test #{index + 1}")
+        logging.debug(f"Test case parameters: {test_case}")
+        test_case.check_cli_test(binary, default_timeout=timeout)

gha_utils/metadata.py

@@ -1105,7 +1105,7 @@ class Metadata:
             ).format(**variations)
             matrix.add_includes(bin_name_include)
 
-        return Matrix(matrix)
+        return matrix
 
     @cached_property
     def release_notes(self) -> str | None:

gha_utils/test_plan.py

@@ -16,10 +16,13 @@
 
 from __future__ import annotations
 
+import logging
 import re
+import shlex
+import sys
 from dataclasses import asdict, dataclass, field
 from pathlib import Path
-from subprocess import run
+from subprocess import TimeoutExpired, run
 from typing import Generator, Sequence
 
 import yaml
@@ -33,131 +36,171 @@ class TestCase:
     cli_parameters: tuple[str, ...] | str = field(default_factory=tuple)
     """Parameters, arguments and options to pass to the CLI."""
 
+    timeout: float | str | None = None
     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
+    output_regex_matches: tuple[re.Pattern | str, ...] | str = field(
+        default_factory=tuple
+    )
+    stdout_regex_matches: tuple[re.Pattern | str, ...] | str = field(
+        default_factory=tuple
+    )
+    stderr_regex_matches: tuple[re.Pattern | str, ...] | str = field(
+        default_factory=tuple
+    )
+    output_regex_fullmatch: re.Pattern | str | None = None
+    stdout_regex_fullmatch: re.Pattern | str | None = None
+    stderr_regex_fullmatch: re.Pattern | 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.
+            # Validates and normalize integer properties.
             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}")
 
+            # Validates and normalize float properties.
+            elif field_id == "timeout":
+                if isinstance(field_data, str):
+                    field_data = float(field_data)
+                elif field_data is not None and not isinstance(field_data, float):
+                    raise ValueError(f"timeout is not a float: {field_data}")
+                # Timeout can only be unset or positive.
+                if field_data and field_data < 0:
+                    raise ValueError(f"timeout is negative: {field_data}")
+
+            # Validates and normalize boolean properties.
             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())
+                if field_data:
+                    # Wraps single string and other types into a tuple.
+                    if isinstance(field_data, str) or not isinstance(
+                        field_data, Sequence
+                    ):
+                        # CLI parameters needs to be split on Unix-like systems.
+                        # XXX If we need the same for Windows, have a look at:
+                        # https://github.com/maxpat78/w32lex
+                        if field_id == "cli_parameters" and sys.platform != "win32":
+                            field_data = tuple(shlex.split(field_data))
+                        else:
+                            field_data = (field_data,)
+
+                    for item in field_data:
+                        if not isinstance(item, str):
+                            raise ValueError(f"Invalid string in {field_id}: {item}")
+                    # Ignore blank value.
+                    field_data = tuple(i for i in field_data if i.strip())
 
-            # Validates regexps.
-            if field_data and "_regex_" in field_id:
+            # Validates fields containing one or more regexes.
+            if "_regex_" in field_id and field_data:
+                # Compile all regexes.
+                valid_regexes = []
                 for regex in flatten((field_data,)):
                     try:
-                        re.compile(regex)
+                        # Let dots in regex match newlines.
+                        valid_regexes.append(re.compile(regex, re.DOTALL))
                     except re.error as ex:
                         raise ValueError(
                             f"Invalid regex in {field_id}: {regex}"
                         ) from ex
+                # Normalize single regex to a single element.
+                if field_id.endswith("_fullmatch"):
+                    if valid_regexes:
+                        field_data = valid_regexes.pop()
+                    else:
+                        field_data = None
+                else:
+                    field_data = tuple(valid_regexes)
 
             setattr(self, field_id, field_data)
 
-    def check_cli_test(self, binary: str | Path, timeout: int | None = None):
+    def check_cli_test(self, binary: str | Path, default_timeout: float | 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.
         """
+        if self.timeout is None and default_timeout is not None:
+            logging.info(f"Set default test case timeout to {default_timeout} seconds")
+            self.timeout = default_timeout
+
         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,
-        )
+        try:
+            result = run(
+                clean_args,
+                capture_output=True,
+                timeout=self.timeout,  # type: ignore[arg-type]
+                # 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,
+            )
+        except TimeoutExpired:
+            raise TimeoutError(
+                f"CLI timed out after {self.timeout} seconds: {' '.join(clean_args)}"
+            )
+
         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):
+            if field_id == "exit_code":
+                if field_data is not None:
+                    logging.info(f"Test exit code, expecting: {field_data}")
+                    if result.returncode != field_data:
+                        raise AssertionError(
+                            f"CLI exited with code {result.returncode}, "
+                            f"expected {field_data}"
+                        )
+                # The specific exit code matches, let's proceed to the next test.
                 continue
 
-            if field_id == "exit_code":
-                if result.returncode != field_data:
-                    raise AssertionError(
-                        f"CLI exited with code {result.returncode}, "
-                        f"expected {field_data}"
-                    )
+            # Ignore non-output fields, and empty test cases.
+            elif not (
+                field_id.startswith(("output_", "stdout_", "stderr_")) and field_data
+            ):
+                continue
 
+            # Prepare output and name for comparison.
             output = ""
             name = ""
             if field_id.startswith("output_"):
-                raise NotImplementedError("Output mixing <stdout>/<stderr>")
+                raise NotImplementedError("<stdout>/<stderr> output mix")
                 # output = result.output
                 # name = "output"
             elif field_id.startswith("stdout_"):
@@ -168,10 +211,12 @@ class TestCase:
                 name = "<stderr>"
 
             if self.strip_ansi:
+                logging.info(f"Strip ANSI escape sequences from CLI's {name}")
                 output = strip_ansi(output)
 
             if field_id.endswith("_contains"):
                 for sub_string in field_data:
+                    logging.info(f"Check if CLI's {name} contains: {sub_string!r}")
                     if sub_string not in output:
                         raise AssertionError(
                             f"CLI's {name} does not contain {sub_string!r}"
@@ -179,18 +224,21 @@ class TestCase:
 
             elif field_id.endswith("_regex_matches"):
                 for regex in field_data:
-                    if not re.search(regex, output):
+                    logging.info(f"Check if CLI's {name} matches: {sub_string!r}")
+                    if not regex.search(output):
                         raise AssertionError(
-                            f"CLI's {name} does not match regex {regex!r}"
+                            f"CLI's {name} does not match regex {regex}"
                         )
 
             elif field_id.endswith("_regex_fullmatch"):
                 regex = field_data
-                if not re.fullmatch(regex, output):
+                if not regex.fullmatch(output):
                     raise AssertionError(
-                        f"CLI's {name} does not fully match regex {regex!r}"
+                        f"CLI's {name} does not fully match regex {regex}"
                     )
 
+        logging.info("All tests passed for CLI.")
+
 
 DEFAULT_TEST_PLAN = (
     # Output the version of the CLI.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: gha-utils
-Version: 4.14.0
+Version: 4.14.2
 Summary: ⚙️ CLI helpers for GitHub Actions + reuseable workflows
 Author-email: Kevin Deldycke <kevin@deldycke.com>
 Project-URL: Homepage, https://github.com/kdeldycke/workflows
@@ -103,7 +103,6 @@ Thanks to `uv`, you can install and run `gha-utils` in one command, without poll
 
 ```shell-session
 $ uvx gha-utils
-Installed 45 packages in 45ms
 Usage: gha-utils [OPTIONS] COMMAND [ARGS]...
 
 Options:
@@ -118,8 +117,11 @@ Options:
                             utils/*.{toml,yaml,yml,json,ini,xml}]
   --show-params             Show all CLI parameters, their provenance, defaults
                             and value, then exit.
-  -v, --verbosity LEVEL     Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
+  --verbosity LEVEL         Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                             [default: WARNING]
+  -v, --verbose             Increase the default WARNING verbosity by one level
+                            for each additional repetition of the option.
+                            [default: 0]
   --version                 Show the version and exit.
   -h, --help                Show this message and exit.
 
@@ -127,6 +129,7 @@ Commands:
   changelog     Maintain a Markdown-formatted changelog
   mailmap-sync  Update Git's .mailmap file with missing contributors
   metadata      Output project metadata
+  test-plan     Run a test plan from a file against a binary
 ```
 
 ```shell-session

gha_utils-4.14.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+gha_utils/__init__.py,sha256=dR8lNlVY_u847eZ0CTxmll40WHAkfXzWXN26hheu824,866
+gha_utils/__main__.py,sha256=Dck9BjpLXmIRS83k0mghAMcYVYiMiFLltQdfRuMSP_Q,1703
+gha_utils/changelog.py,sha256=oahY88A9FRV14f1JSFKIiYrN_TS7Jo3QlljXqJbeuaE,5892
+gha_utils/cli.py,sha256=Gq2pGpIOmvXtsexmg6nwN2ZuZ1lpHrJ5A43CeuDjK68,10985
+gha_utils/mailmap.py,sha256=naUqJYJnE3fLTjju1nd6WMm7ODiSaI2SHuJxRtmaFWs,6269
+gha_utils/matrix.py,sha256=_afJD0K-xZLNxwykVnUhD0Gj9cdO0Z43g3VHa-q_tkI,11941
+gha_utils/metadata.py,sha256=Oumkmo4-O549hxlw8zaTWIPkITpUxUjpulj_MXn6fjA,48649
+gha_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gha_utils/test_plan.py,sha256=B6EiiGWVTrNS7jSIO9EE0kebccx10Fn0ZPapJTOOyGA,11928
+gha_utils-4.14.2.dist-info/METADATA,sha256=uPoJ9lj1TvWEt1Izsipp-4R6bsQ-gwHjnqwILdpL0fQ,20514
+gha_utils-4.14.2.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+gha_utils-4.14.2.dist-info/entry_points.txt,sha256=8bJOwQYf9ZqsLhBR6gUCzvwLNI9f8tiiBrJ3AR0EK4o,54
+gha_utils-4.14.2.dist-info/top_level.txt,sha256=C94Blb61YkkyPBwCdM3J_JPDjWH0lnKa5nGZeZ5M6yE,10
+gha_utils-4.14.2.dist-info/RECORD,,

gha_utils-4.14.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-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,,