tenzir-test 1.0.2__py3-none-any.whl → 1.1.0__py3-none-any.whl

tenzir_test/run.py

@@ -587,6 +587,7 @@ def run_subprocess(
     check: bool = False,
     text: bool = False,
     force_capture: bool = False,
+    stdin_data: bytes | None = None,
     **kwargs: Any,
 ) -> subprocess.CompletedProcess[bytes] | subprocess.CompletedProcess[str]:
     """Execute a subprocess honoring passthrough configuration.
@@ -597,10 +598,30 @@ def run_subprocess(
 
     Runner authors should prefer this helper over direct ``subprocess`` calls so
     passthrough semantics remain consistent across implementations.
+
+    Args:
+        args: Command and arguments to execute.
+        capture_output: Whether to capture stdout/stderr (ignored in passthrough mode).
+        check: If True, raise CalledProcessError on non-zero exit.
+        text: If True, decode stdout/stderr as text. Note: stdin_data must still
+            be bytes even when text=True, as subprocess.run expects bytes for input.
+        force_capture: Capture output even in passthrough mode.
+        stdin_data: Bytes to send to the process's stdin. Use :func:`get_stdin_content`
+            to read from a .stdin file. When None, stdin is not connected.
+        **kwargs: Additional arguments passed to subprocess.run. The keys 'stdout',
+            'stderr', 'capture_output', and 'input' are managed by this function
+            and will raise TypeError if provided.
+
+    Returns:
+        A CompletedProcess instance with returncode, stdout, and stderr.
+
+    Raises:
+        TypeError: If stdout, stderr, capture_output, or input are passed in kwargs.
+        subprocess.CalledProcessError: If check=True and process exits non-zero.
     """
 
-    if any(key in kwargs for key in {"stdout", "stderr", "capture_output"}):
-        raise TypeError("run_subprocess manages stdout/stderr automatically")
+    if any(key in kwargs for key in {"stdout", "stderr", "capture_output", "input"}):
+        raise TypeError("run_subprocess manages stdout/stderr/input automatically")
 
     passthrough = is_passthrough_enabled()
     stream_output = passthrough and not force_capture
@@ -622,6 +643,7 @@ def run_subprocess(
         stdout=stdout,
         stderr=stderr,
         text=text,
+        input=stdin_data,
         **kwargs,
     )
 
@@ -1144,11 +1166,10 @@ def _format_relative_path(path: Path, base: Path) -> str:
 
 
 def _marker_for_selection(selection: ProjectSelection) -> str:
+    is_package = packages.is_package_dir(selection.root)
     if selection.kind == "root":
-        return "■"
-    if packages.is_package_dir(selection.root):
-        return "○"
-    return "□"
+        return "●" if is_package else "■"
+    return "○" if is_package else "□"
 
 
 def _print_execution_plan(plan: ExecutionPlan, *, display_base: Path) -> int:
@@ -1166,8 +1187,12 @@ def _print_execution_plan(plan: ExecutionPlan, *, display_base: Path) -> int:
         return 0
 
     print(f"{INFO} found {len(active)} projects")
+    root_base = plan.root.root
     for marker, selection in active:
-        name = selection.root.name or selection.root.as_posix()
+        if selection.kind == "satellite":
+            name = _format_relative_path(selection.root, root_base)
+        else:
+            name = selection.root.name or selection.root.as_posix()
         print(f"{INFO}   {marker} {name}")
     return len(active)
 
@@ -1198,6 +1223,7 @@ def _default_test_config() -> TestConfig:
         "retry": 1,
         "suite": None,
         "package_dirs": tuple(),
+        "pre_compare": tuple(),
     }
 
 
@@ -1206,13 +1232,17 @@ def _canonical_config_key(key: str) -> str:
         return "fixtures"
     if key in {"package_dirs", "package-dirs"}:
         return "package_dirs"
+    if key in {"pre_compare", "pre-compare"}:
+        return "pre_compare"
     return key
 
 
 ConfigOrigin = Literal["directory", "frontmatter"]
 
 
-def _raise_config_error(location: Path | str, message: str, line_number: int | None = None) -> None:
+def _raise_config_error(
+    location: Path | str, message: str, line_number: int | None = None
+) -> typing.NoReturn:
     base = str(location)
     if line_number is not None:
         base = f"{base}:{line_number}"
@@ -1243,7 +1273,6 @@ def _normalize_fixtures_value(
             f"Invalid value for 'fixtures', expected string or list, got '{value}'",
             line_number,
         )
-        return tuple()
 
     fixtures: list[str] = []
     for entry in raw:
@@ -1304,7 +1333,6 @@ def _normalize_inputs_value(
         f"Invalid value for 'inputs', expected string, got '{value}'",
         line_number,
     )
-    return None
 
 
 def _normalize_package_dirs_value(
@@ -1321,7 +1349,6 @@ def _normalize_package_dirs_value(
             f"Invalid value for 'package-dirs', expected list of strings, got '{value}'",
             line_number,
         )
-        return tuple()
     base_dir = _extract_location_path(location).parent
     normalized: list[str] = []
     for entry in value:
@@ -1331,7 +1358,6 @@ def _normalize_package_dirs_value(
                 f"Invalid package-dirs entry '{entry}', expected string",
                 line_number,
             )
-            continue
         raw = os.fspath(entry).strip()
         if not raw:
             _raise_config_error(
@@ -1339,7 +1365,6 @@ def _normalize_package_dirs_value(
                 "Invalid package-dirs entry: must be non-empty string",
                 line_number,
             )
-            continue
         path = Path(raw)
         if not path.is_absolute():
             path = base_dir / path
@@ -1351,6 +1376,58 @@ def _normalize_package_dirs_value(
     return tuple(normalized)
 
 
+def _normalize_pre_compare_value(
+    value: typing.Any,
+    *,
+    location: Path | str,
+    line_number: int | None = None,
+) -> tuple[str, ...]:
+    entries: typing.Any
+    if isinstance(value, list):
+        entries = value
+    elif isinstance(value, str):
+        try:
+            parsed = yaml.safe_load(value)
+        except yaml.YAMLError:
+            parsed = None
+        if isinstance(parsed, list):
+            entries = parsed
+        else:
+            entries = [value]
+    else:
+        _raise_config_error(
+            location,
+            f"Invalid value for 'pre-compare', expected string or list, got '{value}'",
+            line_number,
+        )
+
+    transforms: list[str] = []
+    valid_names = set(_TRANSFORMS.keys())
+    for entry in entries:
+        if not isinstance(entry, str):
+            _raise_config_error(
+                location,
+                f"Invalid pre-compare entry '{entry}', expected string",
+                line_number,
+            )
+        name = entry.strip()
+        if not name:
+            _raise_config_error(
+                location,
+                "Pre-compare transform names must be non-empty strings",
+                line_number,
+            )
+        if name not in valid_names:
+            valid_list = ", ".join(sorted(valid_names))
+            _raise_config_error(
+                location,
+                f"Unknown pre-compare transform '{name}', valid transforms: {valid_list}",
+                line_number,
+            )
+        transforms.append(name)
+    return tuple(transforms)
+
+
 def _assign_config_option(
     config: TestConfig,
     key: str,
@@ -1370,6 +1447,7 @@ def _assign_config_option(
         "inputs",
         "retry",
         "package_dirs",
+        "pre_compare",
     }
     if origin == "directory":
         valid_keys.add("suite")
@@ -1416,7 +1494,6 @@ def _assign_config_option(
             f"Invalid value for '{canonical}', expected 'true' or 'false', got '{value}'",
             line_number,
         )
-        return
 
     if canonical == "timeout":
         if isinstance(value, int):
@@ -1429,7 +1506,6 @@ def _assign_config_option(
                 f"Invalid value for 'timeout', expected integer, got '{value}'",
                 line_number,
             )
-            return
         if timeout_value <= 0:
             _raise_config_error(
                 location,
@@ -1485,7 +1561,6 @@ def _assign_config_option(
                 f"Invalid value for 'retry', expected integer, got '{value}'",
                 line_number,
             )
-            return
         if retry_value <= 0:
             _raise_config_error(
                 location,
@@ -1495,6 +1570,11 @@ def _assign_config_option(
         config[canonical] = retry_value
         return
 
+    if canonical == "pre_compare":
+        transforms = _normalize_pre_compare_value(value, location=location, line_number=line_number)
+        config[canonical] = transforms
+        return
+
     if canonical == "runner":
         if not isinstance(value, str):
             _raise_config_error(
@@ -1857,10 +1937,18 @@ def get_test_env_and_config_args(
             candidate = test.parent / candidate
         inputs_path = str(candidate.resolve())
     env["TENZIR_INPUTS"] = inputs_path
-    # Check for inline input file (.input extension)
+    # Check for inline input file (.input extension).
+    # Note: .input and .stdin extensions are reserved; see RESERVED_EXTENSIONS
+    # in tenzir_test.runners.ext_runner for the authoritative list.
     inline_input = test.with_suffix(".input")
     if inline_input.is_file():
-        env["TENZIR_INPUT"] = str(inline_input.resolve())
+        validated_input = _validate_path_within_root(inline_input, "input file")
+        env["TENZIR_INPUT"] = str(validated_input)
+    # Check for stdin file (.stdin extension)
+    stdin_file = test.with_suffix(".stdin")
+    if stdin_file.is_file():
+        validated_stdin = _validate_path_within_root(stdin_file, "stdin file")
+        env["TENZIR_STDIN"] = str(validated_stdin)
     if config_file.exists():
         env.setdefault("TENZIR_CONFIG", str(config_file))
     if node_config_file.exists():
@@ -1875,6 +1963,32 @@ def get_test_env_and_config_args(
     return env, config_args
 
 
+def _validate_path_within_root(path: Path, description: str) -> Path:
+    """Validate that a resolved path is within the project ROOT.
+
+    This provides defense-in-depth against symlink traversal attacks where a
+    malicious .stdin or .input file could be a symlink pointing outside the
+    project directory.
+
+    Args:
+        path: The path to validate (will be resolved to follow symlinks).
+        description: Human-readable description for error messages (e.g., "stdin file").
+
+    Returns:
+        The resolved path if validation passes.
+
+    Raises:
+        RuntimeError: If the resolved path is outside the project root.
+    """
+    resolved = path.resolve()
+    try:
+        resolved.relative_to(ROOT.resolve())
+    except ValueError:
+        rel_path = _relativize_path(path)
+        raise RuntimeError(f"{description} '{rel_path}' resolves outside project root") from None
+    return resolved
+
+
 def _apply_fixture_env(env: dict[str, str], fixtures: tuple[str, ...]) -> None:
     if fixtures:
         env["TENZIR_TEST_FIXTURES"] = ",".join(fixtures)
@@ -1882,6 +1996,45 @@ def _apply_fixture_env(env: dict[str, str], fixtures: tuple[str, ...]) -> None:
         env.pop("TENZIR_TEST_FIXTURES", None)
 
 
+def get_stdin_content(env: dict[str, str]) -> bytes | None:
+    """Read stdin content from a file specified by TENZIR_STDIN environment variable.
+
+    This function is intended for runner authors who need to provide stdin content
+    to test processes. The TENZIR_STDIN variable is automatically set by the test
+    harness when a ``.stdin`` file exists alongside the test file.
+
+    Args:
+        env: Environment dictionary, typically from :func:`get_test_env_and_config_args`.
+
+    Returns:
+        The file contents as bytes if TENZIR_STDIN is set and the file exists,
+        otherwise None. Empty files return empty bytes (b"").
+
+    Raises:
+        RuntimeError: If TENZIR_STDIN is set but the file cannot be read
+            (e.g., file not found, permission denied).
+
+    Example:
+        Runner authors can use this with :func:`run_subprocess`::
+
+            env, config_args = get_test_env_and_config_args(test)
+            stdin_content = get_stdin_content(env)
+            completed = run_subprocess(
+                ["my-command"],
+                env=env,
+                stdin_data=stdin_content,
+                ...
+            )
+    """
+    stdin_path = env.get("TENZIR_STDIN")
+    if not stdin_path:
+        return None
+    try:
+        return Path(stdin_path).read_bytes()
+    except OSError as e:
+        raise RuntimeError(f"Failed to read stdin file '{stdin_path}': {e.strerror}") from e
+
+
 def set_debug_logging(enabled: bool) -> None:
     global _debug_logging
     _debug_logging = enabled
@@ -2795,6 +2948,43 @@ def _format_lines_changed(total: int) -> str:
     return f"{_BLOCK_INDENT}└ {total} {line} changed"
 
 
+def _transform_sort(output: bytes) -> bytes:
+    """Sort output lines lexicographically.
+
+    Uses surrogateescape to preserve undecodable bytes as surrogate escapes,
+    allowing the transform to handle binary data gracefully.
+    """
+    if not output:
+        return output
+    has_trailing_newline = output.endswith(b"\n")
+    text = output.decode("utf-8", errors="surrogateescape")
+    lines = text.splitlines(keepends=False)
+    sorted_lines = sorted(lines)
+    result = "\n".join(sorted_lines)
+    if has_trailing_newline:
+        result += "\n"
+    return result.encode("utf-8", errors="surrogateescape")
+
+
+# Transforms are intentionally simple and hardcoded rather than using the plugin
+# architecture (like runners and fixtures). Rationale:
+# - Transforms are core comparison utilities, not user-extensible features
+# - Currently only one transform exists; extensibility can be added if needed
+# - Pre-compare transforms are rarely customized per-project compared to runners
+# - If custom transforms become necessary, this can be refactored to use a
+#   registry pattern similar to runners/__init__.py
+_TRANSFORMS: dict[str, typing.Callable[[bytes], bytes]] = {
+    "sort": _transform_sort,
+}
+
+
+def apply_pre_compare(output: bytes, transforms: tuple[str, ...]) -> bytes:
+    """Apply pre-compare transforms in order."""
+    for name in transforms:
+        output = _TRANSFORMS[name](output)
+    return output
+
+
 def print_diff(expected: bytes, actual: bytes, path: Path) -> None:
     if should_suppress_failure_output():
         return
@@ -2960,12 +3150,14 @@ def run_simple_test(
                 "-f",
                 str(test),
             ]
+            stdin_content = get_stdin_content(env)
             completed = run_subprocess(
                 cmd,
                 timeout=timeout,
                 env=env,
                 capture_output=not passthrough_mode,
                 cwd=str(ROOT),
+                stdin_data=stdin_content,
             )
         good = completed.returncode == 0
         output = b""
@@ -3038,12 +3230,15 @@ def run_simple_test(
             return False
         log_comparison(test, ref_path, mode="comparing")
         expected = ref_path.read_bytes()
-        if expected != output:
+        pre_compare = cast(tuple[str, ...], test_config.get("pre_compare", tuple()))
+        expected_transformed = apply_pre_compare(expected, pre_compare)
+        output_transformed = apply_pre_compare(output, pre_compare)
+        if expected_transformed != output_transformed:
             if interrupt_requested():
                 report_interrupted_test(test)
             else:
                 report_failure(test, "")
-                print_diff(expected, output, ref_path)
+                print_diff(expected_transformed, output_transformed, ref_path)
             return False
     success(test)
     return True

tenzir_test/runners/__init__.py

@@ -133,7 +133,7 @@ def get_runner_for_test(test_path: Path) -> Runner:
         runner_name = runner_value
     if runner_name in RUNNERS_BY_NAME:
         return RUNNERS_BY_NAME[runner_name]
-    raise ValueError(f"Runner '{runner_name}' not found - this is a bug")
+    raise ValueError(f"runner '{runner_name}' not found; define it in <project>/runners/")
 
 
 register(ShellRunner())

tenzir_test/runners/custom_python_fixture_runner.py

@@ -106,12 +106,14 @@ class CustomPythonFixture(ExtRunner):
                     env["TENZIR_PYTHON_FIXTURE_TIMEOUT"] = str(timeout)
                     if node_requested and endpoint:
                         env["TENZIR_PYTHON_FIXTURE_ENDPOINT"] = endpoint
+                    stdin_content = run_mod.get_stdin_content(env)
                     completed = run_mod.run_subprocess(
                         cmd,
                         timeout=timeout,
                         env=env,
                         capture_output=not passthrough,
                         check=True,
+                        stdin_data=stdin_content,
                     )
                 ref_path = test.with_suffix(".txt")
                 if completed.returncode != 0:

tenzir_test/runners/ext_runner.py

@@ -5,9 +5,22 @@ from pathlib import Path
 from ._utils import get_run_module
 from .runner import Runner
 
+# Extensions reserved by the framework and not available for custom runners.
+# These extensions have special meaning in the test harness:
+#   - .txt: baseline output file for comparison
+#   - .input: inline input data exposed via TENZIR_INPUT env var
+#   - .stdin: stdin content fed to test process via stdin_data parameter
+#
+# Custom runner authors who need stdin support should use get_stdin_content()
+# and pass the result to run_subprocess(stdin_data=...). See the ShellRunner
+# and CustomPythonFixture implementations for reference.
+RESERVED_EXTENSIONS = frozenset({"input", "stdin", "txt"})
+
 
 class ExtRunner(Runner):
     def __init__(self, *, name: str, ext: str) -> None:
+        if ext in RESERVED_EXTENSIONS:
+            raise ValueError(f"runner '{name}' uses reserved extension '.{ext}'")
         super().__init__(name=name)
         self._ext = ext
 

tenzir_test/runners/shell_runner.py

@@ -49,6 +49,7 @@ class ShellRunner(ExtRunner):
                     env["PATH"] = shell_path_prefix
 
                 try:
+                    stdin_content = run_mod.get_stdin_content(env)
                     completed = run_mod.run_subprocess(
                         ["sh", "-eu", str(test)],
                         env=env,
@@ -57,6 +58,7 @@ class ShellRunner(ExtRunner):
                         check=not expect_error,
                         text=False,
                         cwd=str(run_mod.ROOT),
+                        stdin_data=stdin_content,
                     )
                 except subprocess.CalledProcessError as exc:
                     completed = exc  # treat like CompletedProcess for diagnostics

{tenzir_test-1.0.2.dist-info → tenzir_test-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tenzir-test
-Version: 1.0.2
+Version: 1.1.0
 Summary: Reusable test execution framework extracted from the Tenzir repository.
 Project-URL: Homepage, https://github.com/tenzir/test
 Project-URL: Repository, https://github.com/tenzir/test

{tenzir_test-1.0.2.dist-info → tenzir_test-1.1.0.dist-info}/RECORD

@@ -4,7 +4,7 @@ tenzir_test/cli.py,sha256=WwddXpkjg3OIT5E54LOobaibDkGH9UvTLzZ9iMKw-qQ,6241
 tenzir_test/config.py,sha256=z4ayS62SfOLNwrEgNktVeulyQ2QW4KUlN1KX0Za1NDM,2110
 tenzir_test/packages.py,sha256=cTCQdGjCS1XmuKyiwh0ew-z9tHn6J-xZ6nvBP-hU8bc,948
 tenzir_test/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-tenzir_test/run.py,sha256=LuDT4XWZzglUY3p3GBVUNV6aDJcD3SzbYbte_QvtObM,133079
+tenzir_test/run.py,sha256=EhMzfiJN7MjY6Dt5nQXkCnzq6RvlMktD0HrEEaW1yVc,140759
 tenzir_test/engine/__init__.py,sha256=5APwy90YDm7rmL_qCZfToAcfbQthcZ8yV2_ExXKqaqE,110
 tenzir_test/engine/operations.py,sha256=OCYjuMHyMAaay4s08u2Sl7oE-PmgeXumylp7R8GYIH4,950
 tenzir_test/engine/registry.py,sha256=LXCr6TGlv1sR1m1eboTk7SrbS2IVErc3PqUuHxGA2xk,594
@@ -12,17 +12,17 @@ tenzir_test/engine/state.py,sha256=zolKmUWpTEajoq4gY8KYv_puCeS_DOpOTExBwLulNjo,8
 tenzir_test/engine/worker.py,sha256=WwIkx1m_ANNveQjNisy5-qpbUZl_DfDXxVIfdxABKjc,140
 tenzir_test/fixtures/__init__.py,sha256=H8deAoYg7HMPsZZ2UTO2KE1N82CbCQqN0bXk8q7B9ww,18441
 tenzir_test/fixtures/node.py,sha256=iNT3H0y_9g-CzJO7-EPrAYBOX69O-g3lnuQiAvGqThc,11524
-tenzir_test/runners/__init__.py,sha256=M3p-TsDp231Dy58miDb467bA1kLYzgpa0pqVr_KP1ro,4616
+tenzir_test/runners/__init__.py,sha256=q68F75vsPwUrnzRZzu2PMuQystpVUFhmsZQPPxfvBtU,4633
 tenzir_test/runners/_utils.py,sha256=BWv7UEPGa01l4tGTCg5i_22NblIyRw8vjk_5NIf1x_c,467
-tenzir_test/runners/custom_python_fixture_runner.py,sha256=kJ4NYfLnB2ntZguv1pzIge_ith7D49YHKM35CJXU8MA,7321
+tenzir_test/runners/custom_python_fixture_runner.py,sha256=xTc0x8_Y5DhkCz85ePmrpoWWAVEnzD9ZiFPNxEKppFY,7438
 tenzir_test/runners/diff_runner.py,sha256=zRLeoqwqLdIpP5weq20K0VQdIXPy7QFmZ462Hlg0L0k,5477
-tenzir_test/runners/ext_runner.py,sha256=sKL9Mw_ksVVBWnrdIJR2WS5ueVnLKuNYYWZ22FTZIPo,730
+tenzir_test/runners/ext_runner.py,sha256=jO-eDqzCQY1pM_5W2Uvci8xy-oTel1kVA2hDSAo-05w,1449
 tenzir_test/runners/runner.py,sha256=LtlD8huQOSmD7RyYDnKeCuI4Y6vhxGXMKsHA2qgfWN0,989
-tenzir_test/runners/shell_runner.py,sha256=OuofgHeZN2FaO6xRI3uyqstLBymc6rmWC4HAnSn91AE,6068
+tenzir_test/runners/shell_runner.py,sha256=vWCNTWQGVoatM98jN1UJaVrZJR2oPnqpPUs0-ud7rrc,6185
 tenzir_test/runners/tenzir_runner.py,sha256=464FFYS_mh6l-ehccc-S8cIUO1MxdapwQL5X3PmMkMI,1006
 tenzir_test/runners/tql_runner.py,sha256=2ZLMf3TIKwcOvaOFrVvvhzK-EcWmGOUZxKkbSoByyQA,248
-tenzir_test-1.0.2.dist-info/METADATA,sha256=3rn-0w3yHvjMBeds7Qa_W0t3TCi7bPAdPNCjlEtfOTc,3065
-tenzir_test-1.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-tenzir_test-1.0.2.dist-info/entry_points.txt,sha256=l8DJgiEVrjScdTTo613cZ3PKodOmqrUVIbz-3awfV8w,53
-tenzir_test-1.0.2.dist-info/licenses/LICENSE,sha256=ajMbpcBiSTXI8Rr4t17pvowV-On8DktghfZKxY_A22Q,10750
-tenzir_test-1.0.2.dist-info/RECORD,,
+tenzir_test-1.1.0.dist-info/METADATA,sha256=n9yH11WQuTx4rX0DoK2Qz8alBPZlbBM9GrABHIQ7vsA,3065
+tenzir_test-1.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+tenzir_test-1.1.0.dist-info/entry_points.txt,sha256=l8DJgiEVrjScdTTo613cZ3PKodOmqrUVIbz-3awfV8w,53
+tenzir_test-1.1.0.dist-info/licenses/LICENSE,sha256=ajMbpcBiSTXI8Rr4t17pvowV-On8DktghfZKxY_A22Q,10750
+tenzir_test-1.1.0.dist-info/RECORD,,