tenzir-test 0.12.0__py3-none-any.whl

tenzir_test/__init__.py

@@ -0,0 +1,56 @@
+"""Test execution utilities for the Tenzir ecosystem."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from . import run
+from .run import ExecutionResult, HarnessError, ProjectResult, ensure_settings, execute
+from .config import Settings, discover_settings
+from .fixtures import (
+    Executor,
+    FixtureHandle,
+    FixtureSelection,
+    FixtureController,
+    activate,
+    acquire_fixture,
+    fixture,
+    has,
+    register,
+    fixtures_api,
+    require,
+)
+
+fixtures = fixtures_api
+
+__all__ = [
+    "__version__",
+    "Executor",
+    "FixtureHandle",
+    "FixtureSelection",
+    "FixtureController",
+    "activate",
+    "acquire_fixture",
+    "fixture",
+    "fixtures",
+    "Settings",
+    "discover_settings",
+    "ensure_settings",
+    "execute",
+    "has",
+    "register",
+    "require",
+    "ExecutionResult",
+    "ProjectResult",
+    "HarnessError",
+    "run",
+]
+
+
+def _get_version() -> str:
+    """Return the installed package version or a development placeholder."""
+    try:
+        return version("tenzir-test")
+    except PackageNotFoundError:  # pragma: no cover - missing metadata during dev
+        return "0.0.0"
+
+
+__version__ = _get_version()

tenzir_test/_python_runner.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import json
+import os
+import runpy
+import sys
+from contextvars import Token
+from pathlib import Path
+from typing import Any, Dict, cast
+
+from . import fixtures as _fixtures
+from .fixtures import acquire_fixture as _acquire_fixture
+
+
+_EXPORTED_HELPERS: dict[str, Any] = {
+    "fixtures": _fixtures.fixtures_api,
+    "fixtures_module": _fixtures,
+    "fixtures_selection": _fixtures.fixtures,
+    "activate": _fixtures.activate,
+    "require": _fixtures.require,
+    "has": _fixtures.has,
+    "FixtureContext": _fixtures.FixtureContext,
+    "FixtureHandle": _fixtures.FixtureHandle,
+    "FixtureSelection": _fixtures.FixtureSelection,
+    "FixtureController": _fixtures.FixtureController,
+    "Executor": _fixtures.Executor,
+}
+
+_EXPORTED_HELPERS["acquire_fixture"] = _acquire_fixture
+
+
+def _build_init_globals() -> Dict[str, Any]:
+    init_globals: Dict[str, Any] = {}
+    init_globals.update(_EXPORTED_HELPERS)
+    return init_globals
+
+
+def _push_context_from_env() -> Token[Any] | None:
+    payload_raw = os.environ.get("TENZIR_PYTHON_FIXTURE_CONTEXT")
+    if not payload_raw:
+        return None
+    try:
+        payload = json.loads(payload_raw)
+    except json.JSONDecodeError:
+        return None
+    test_path = Path(payload.get("test", ""))
+    config = cast(Dict[str, Any], payload.get("config", {}))
+    coverage = bool(payload.get("coverage", False))
+    config_args_raw = payload.get("config_args", ())
+    config_args = tuple(str(arg) for arg in config_args_raw)
+    env = dict(os.environ)
+    context = _fixtures.FixtureContext(
+        test=test_path,
+        config=config,
+        coverage=coverage,
+        env=env,
+        config_args=config_args,
+        tenzir_binary=env.get("TENZIR_PYTHON_FIXTURE_BINARY") or env.get("TENZIR_BINARY"),
+        tenzir_node_binary=env.get("TENZIR_NODE_BINARY"),
+    )
+    token = _fixtures.push_context(context)
+    return cast(Token[Any], token)
+
+
+def _run_script(script_path: Path, args: list[str]) -> None:
+    sys.argv = [str(script_path), *args]
+    init_globals = _build_init_globals()
+    token = _push_context_from_env()
+    try:
+        runpy.run_path(str(script_path), run_name="__main__", init_globals=init_globals)
+    except KeyboardInterrupt:  # pragma: no cover - forwarded to harness
+        raise SystemExit(130)
+    finally:
+        if token is not None:
+            _fixtures.pop_context(token)
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = list(sys.argv if argv is None else argv)
+    if len(args) < 2:
+        raise SystemExit("usage: python -m tenzir_test._python_runner <path> [args...]")
+
+    script_arg = args[1]
+    script_path = Path(script_arg)
+    if not script_path.exists():
+        raise SystemExit(f"python runner could not find test file: {script_arg}")
+
+    extra_args = args[2:]
+    _run_script(script_path, extra_args)
+
+
+if __name__ == "__main__":
+    main()

tenzir_test/checks.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import shlex
+import subprocess
+from typing import Sequence
+
+_COMMANDS: Sequence[Sequence[str]] = (
+    ("ruff", "check"),
+    ("ruff", "format", "--check"),
+    ("mypy",),
+    ("pytest",),
+    ("uv", "build"),
+)
+
+
+def _run(command: Sequence[str]) -> None:
+    printable = " ".join(shlex.quote(part) for part in command)
+    print(f"> {printable}")
+    result = subprocess.run(command, check=False)
+    if result.returncode != 0:
+        raise SystemExit(result.returncode)
+
+
+def main() -> int:
+    for command in _COMMANDS:
+        _run(command)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tenzir_test/cli.py

@@ -0,0 +1,216 @@
+"""Command line entry point for the tenzir-test runner."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+import sys
+
+import click
+
+from . import __version__, run as runtime
+
+
+def _normalize_exit_code(value: object) -> int:
+    """Cast arbitrary exit codes to integers."""
+
+    if value is None:
+        return 0
+    if isinstance(value, int):
+        return value
+    return 1
+
+
+@click.command(
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+@click.version_option(
+    __version__,
+    "-V",
+    "--version",
+    prog_name="tenzir-test",
+    message="%(prog)s %(version)s",
+)
+@click.option(
+    "root",
+    "--root",
+    type=click.Path(
+        path_type=Path, file_okay=False, dir_okay=True, writable=False, resolve_path=False
+    ),
+    help="Project root to scan for tests.",
+)
+@click.option(
+    "tenzir_binary",
+    "--tenzir-binary",
+    type=click.Path(path_type=Path, dir_okay=False, writable=False, resolve_path=False),
+    help="Path to the tenzir executable.",
+)
+@click.option(
+    "tenzir_node_binary",
+    "--tenzir-node-binary",
+    type=click.Path(path_type=Path, dir_okay=False, writable=False, resolve_path=False),
+    help="Path to the tenzir-node executable.",
+)
+@click.argument(
+    "tests",
+    nargs=-1,
+    type=click.Path(path_type=Path, resolve_path=False),
+)
+@click.option("-u", "--update", is_flag=True, help="Update reference outputs.")
+@click.option(
+    "-d",
+    "--debug",
+    is_flag=True,
+    help="Enable debug logging.",
+)
+@click.option("--purge", is_flag=True, help="Delete cached runner artifacts and exit.")
+@click.option(
+    "--coverage",
+    is_flag=True,
+    help="Enable code coverage collection (increases timeouts by 5x).",
+)
+@click.option(
+    "--coverage-source-dir",
+    type=click.Path(path_type=Path, resolve_path=False),
+    help="Source directory for coverage path mapping (defaults to current directory).",
+)
+@click.option(
+    "--runner-summary",
+    is_flag=True,
+    help="Include per-runner statistics in the summary table.",
+)
+@click.option(
+    "--fixture-summary",
+    is_flag=True,
+    help="Include per-fixture statistics in the summary table.",
+)
+@click.option(
+    "--summary",
+    "show_summary",
+    is_flag=True,
+    help="Show an aggregate table and detailed failure summary after execution.",
+)
+@click.option(
+    "--diff/--no-diff",
+    "show_diff_output",
+    default=True,
+    help="Show unified diffs when expectations differ.",
+)
+@click.option(
+    "--diff-stat/--no-diff-stat",
+    "show_diff_stat",
+    default=True,
+    help="Include per-file diff statistics and change counters when expectations differ.",
+)
+@click.option(
+    "-k",
+    "--keep",
+    "keep_tmp_dirs",
+    is_flag=True,
+    help="Preserve per-test temporary directories instead of deleting them.",
+)
+@click.option(
+    "-j",
+    "--jobs",
+    type=click.IntRange(min=1),
+    default=runtime.get_default_jobs(),
+    show_default=True,
+    metavar="N",
+    help="Number of parallel worker threads.",
+)
+@click.option(
+    "-p",
+    "--passthrough",
+    is_flag=True,
+    help="Stream raw test output directly to the terminal.",
+)
+@click.option(
+    "-a",
+    "--all-projects",
+    is_flag=True,
+    help="Run the root project alongside any selected satellites.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    *,
+    root: Path | None,
+    tenzir_binary: Path | None,
+    tenzir_node_binary: Path | None,
+    tests: tuple[Path, ...],
+    update: bool,
+    debug: bool,
+    purge: bool,
+    coverage: bool,
+    coverage_source_dir: Path | None,
+    runner_summary: bool,
+    fixture_summary: bool,
+    show_summary: bool,
+    show_diff_output: bool,
+    show_diff_stat: bool,
+    keep_tmp_dirs: bool,
+    jobs: int,
+    passthrough: bool,
+    all_projects: bool,
+) -> int:
+    """Execute tenzir-test scenarios."""
+
+    jobs_source = ctx.get_parameter_source("jobs")
+    jobs_overridden = jobs_source is not click.core.ParameterSource.DEFAULT
+
+    try:
+        result = runtime.run_cli(
+            root=root,
+            tenzir_binary=tenzir_binary,
+            tenzir_node_binary=tenzir_node_binary,
+            tests=list(tests),
+            update=update,
+            debug=debug,
+            purge=purge,
+            coverage=coverage,
+            coverage_source_dir=coverage_source_dir,
+            runner_summary=runner_summary,
+            fixture_summary=fixture_summary,
+            show_summary=show_summary,
+            show_diff_output=show_diff_output,
+            show_diff_stat=show_diff_stat,
+            keep_tmp_dirs=keep_tmp_dirs,
+            jobs=jobs,
+            passthrough=passthrough,
+            jobs_overridden=jobs_overridden,
+            all_projects=all_projects,
+        )
+    except runtime.HarnessError as exc:
+        if exc.show_message and exc.args:
+            raise click.ClickException(str(exc)) from exc
+        return exc.exit_code
+    return result.exit_code
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the Click command and translate Click exits to integer codes."""
+
+    command_main = getattr(cli, "main")
+    previous_color_mode = runtime.get_color_mode()
+    runtime.set_color_mode(runtime.ColorMode.AUTO)
+    try:
+        result = command_main(
+            args=list(argv) if argv is not None else None,
+            standalone_mode=False,
+        )
+    except click.exceptions.Exit as exc:  # pragma: no cover - passthrough CLI termination
+        return _normalize_exit_code(exc.exit_code)
+    except click.exceptions.ClickException as exc:
+        exc.show(file=sys.stderr)
+        exit_code = getattr(exc, "exit_code", None)
+        return _normalize_exit_code(exit_code)
+    except SystemExit as exc:  # pragma: no cover - propagate runner exits
+        return _normalize_exit_code(exc.code)
+    else:
+        return _normalize_exit_code(result)
+    finally:
+        runtime.set_color_mode(previous_color_mode)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tenzir_test/config.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+
+@dataclass(slots=True)
+class Settings:
+    """Configuration values steering how the harness discovers binaries and data."""
+
+    root: Path
+    tenzir_binary: str | None
+    tenzir_node_binary: str | None
+
+    @property
+    def inputs_dir(self) -> Path:
+        direct = self.root / "inputs"
+        if direct.exists():
+            return direct
+        nested = self.root / "tests" / "inputs"
+        if nested.exists():
+            return nested
+        return direct
+
+
+def _coerce_binary(value: str | os.PathLike[str] | None) -> str | None:
+    if value is None:
+        return None
+    return str(value)
+
+
+def discover_settings(
+    *,
+    root: Path | None = None,
+    tenzir_binary: str | os.PathLike[str] | None = None,
+    tenzir_node_binary: str | os.PathLike[str] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Settings:
+    """Produce harness settings by combining CLI overrides with environment defaults."""
+
+    environment = dict(env or os.environ)
+
+    chosen_root = root or environment.get("TENZIR_TEST_ROOT") or Path.cwd()
+    root_path = Path(chosen_root).resolve()
+
+    binary_cli = _coerce_binary(tenzir_binary)
+    binary_env = environment.get("TENZIR_BINARY")
+    tenzir_path = binary_cli or binary_env or shutil.which("tenzir")
+
+    node_cli = _coerce_binary(tenzir_node_binary)
+    node_env = environment.get("TENZIR_NODE_BINARY")
+    node_path = node_cli or node_env or shutil.which("tenzir-node")
+
+    return Settings(root=root_path, tenzir_binary=tenzir_path, tenzir_node_binary=node_path)

tenzir_test/engine/__init__.py

@@ -0,0 +1,5 @@
+"""Engine utilities for tenzir-test."""
+
+from .worker import Summary, Worker
+
+__all__ = ["Summary", "Worker"]

tenzir_test/engine/operations.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from tenzir_test import run
+
+stdout_lock = run.stdout_lock
+
+update_registry_metadata = run.update_registry_metadata
+get_allowed_extensions = run.get_allowed_extensions
+get_test_env_and_config_args = run.get_test_env_and_config_args
+parse_test_config = run.parse_test_config
+report_failure = run.report_failure
+handle_skip = run.handle_skip
+run_simple_test = run.run_simple_test
+print_diff = run.print_diff
+success = run.success
+fail = run.fail
+run_subprocess = run.run_subprocess
+is_passthrough_enabled = run.is_passthrough_enabled
+get_harness_mode = run.get_harness_mode
+
+__all__ = [
+    "stdout_lock",
+    "update_registry_metadata",
+    "get_allowed_extensions",
+    "get_test_env_and_config_args",
+    "parse_test_config",
+    "report_failure",
+    "handle_skip",
+    "run_simple_test",
+    "print_diff",
+    "success",
+    "fail",
+    "run_subprocess",
+    "is_passthrough_enabled",
+    "get_harness_mode",
+]

tenzir_test/engine/registry.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from tenzir_test import runners as runner_module
+from tenzir_test.runners import Runner
+
+
+def iter_runners() -> Iterable[Runner]:
+    return runner_module.iter_runners()
+
+
+def get_runner(name: str) -> Runner:
+    return runner_module.runner_map()[name]
+
+
+def has_runner(name: str) -> bool:
+    return name in runner_module.runner_map()
+
+
+def allowed_extensions() -> set[str]:
+    return runner_module.allowed_extensions()
+
+
+__all__ = [
+    "iter_runners",
+    "get_runner",
+    "has_runner",
+    "allowed_extensions",
+]

tenzir_test/engine/state.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from ..config import Settings
+from tenzir_test import run
+
+TENZIR_BINARY: Optional[str] = run.TENZIR_BINARY
+TENZIR_NODE_BINARY: Optional[str] = run.TENZIR_NODE_BINARY
+ROOT: Path = run.ROOT
+INPUTS_DIR: Path = run.INPUTS_DIR
+
+
+def apply_settings(settings: Settings) -> None:
+    run.apply_settings(settings)
+    _refresh()
+
+
+def _refresh() -> None:
+    global TENZIR_BINARY, TENZIR_NODE_BINARY, ROOT, INPUTS_DIR
+    TENZIR_BINARY = run.TENZIR_BINARY
+    TENZIR_NODE_BINARY = run.TENZIR_NODE_BINARY
+    ROOT = run.ROOT
+    INPUTS_DIR = run.INPUTS_DIR
+
+
+# Ensure module state reflects current run module state by default.
+_refresh()
+
+
+def refresh() -> None:
+    _refresh()
+
+
+__all__ = [
+    "TENZIR_BINARY",
+    "TENZIR_NODE_BINARY",
+    "ROOT",
+    "INPUTS_DIR",
+    "apply_settings",
+    "refresh",
+]

tenzir_test/engine/worker.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from tenzir_test import run
+
+Summary = run.Summary
+Worker = run.Worker
+
+__all__ = ["Summary", "Worker"]