apte 0.3.0__py3-none-any.whl

apte/cli/main.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+import argparse
+import functools
+import sys
+from typing import TYPE_CHECKING, Any
+
+from apte.api import collect_tests, list_tags, run_session
+from apte.core.session import ApteSession
+from apte.loader import LoadError, load_session, parse_target
+from apte.plugin import PluginContext
+from apte.reporting.verbosity import Verbosity
+
+if TYPE_CHECKING:
+    from apte.entities import TestItem
+
+HELP_EPILOG = """
+Examples:
+  apte run demo:session              Run all tests
+  apte run demo:session::API         Run tests in API suite only
+  apte run demo:session -k login     Run tests matching 'login'
+  apte run demo:session -n 4         Run with 4 concurrent workers
+  apte run demo:session --lf         Re-run only failed tests
+  apte run demo:session --collect-only   List tests without running
+  apte run demo:session --tag slow   Run tests with 'slow' tag
+  apte run demo:session -s           Disable capture (show print output)
+  apte eval demo:session             Run all evaluations
+  apte eval demo:session --show-output  Show inputs/output/expected per case
+  apte live                          Start live reporter server
+  apte tags list demo:session        List all available tags
+"""
+
+
+def _handle_tags_command() -> None:
+    """Handle 'apte tags' subcommand."""
+    parser = argparse.ArgumentParser(
+        prog="apte tags",
+        description="Tag inspection commands",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", required=True)
+
+    list_parser = subparsers.add_parser("list", help="List all available tags")
+    list_parser.add_argument(
+        "target",
+        help="Module and session: 'module:session' (e.g., 'demo:session')",
+    )
+    list_parser.add_argument(
+        "--app-dir",
+        default=".",
+        help="Look for module in this directory (default: .)",
+    )
+    list_parser.add_argument(
+        "-r",
+        "--recursive",
+        action="store_true",
+        help="Show effective tags per test (including inherited from fixtures)",
+    )
+
+    args = parser.parse_args(sys.argv[2:])
+
+    if args.subcommand == "list":
+        _list_tags(args.target, app_dir=args.app_dir, recursive=args.recursive)
+
+
+def _list_tags(target: str, app_dir: str, recursive: bool = False) -> None:
+    """List all tags in a session."""
+    try:
+        session = load_session(target, app_dir)
+    except LoadError as exc:
+        print(f"Error: {exc}")
+        sys.exit(1)
+
+    if recursive:
+        items = collect_tests(session)
+        _print_tags_recursive(items)
+    else:
+        tags = list_tags(session)
+        _print_tags_summary(tags)
+
+
+def _print_tags_summary(tags: set[str]) -> None:
+    """Print summary of all declared tags."""
+    for tag in sorted(tags):
+        print(tag)
+
+
+def _print_tags_recursive(items: list[TestItem]) -> None:
+    """Print effective tags per test."""
+    if not items:
+        print("No tests found.")
+        return
+
+    print(f"Effective tags for {len(items)} test(s):\n")
+    for item in items:
+        tags_str = ", ".join(sorted(item.tags)) if item.tags else "(none)"
+        print(f"  {item.node_id}")
+        print(f"    tags: {tags_str}\n")
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        _print_help()
+        return
+
+    command = sys.argv[1]
+
+    if command in ("--help", "-h"):
+        _print_help()
+        return
+
+    commands: dict[str, Any] = {
+        "tags": _handle_tags_command,
+        "run": functools.partial(_handle_run_command, kind_filter="test"),
+        "eval": functools.partial(_handle_run_command, kind_filter="eval"),
+        "live": _handle_live_command,
+    }
+
+    handler = commands.get(command)
+    if handler:
+        handler()
+        return
+
+    valid = ", ".join(f"'{c}'" for c in commands)
+    print(f"Error: Unknown command '{command}'. Use {valid}.")
+    sys.exit(1)
+
+
+def _handle_live_command() -> None:
+    """Handle 'apte live' subcommand - starts persistent live server."""
+    parser = argparse.ArgumentParser(
+        prog="apte live",
+        description="Start live reporter server (keeps running for multiple test runs)",
+    )
+    parser.add_argument(
+        "-p",
+        "--port",
+        type=int,
+        default=8765,
+        help="Port to listen on (default: 8765)",
+    )
+    args = parser.parse_args(sys.argv[2:])
+
+    from apte.reporting.web import run_live_server  # noqa: PLC0415 - optional dep
+
+    run_live_server(port=args.port)
+
+
+def _print_help() -> None:
+    """Print main help."""
+    print("Apte - Async-first Python test framework\n")
+    print("Commands:")
+    print("  run      Run tests")
+    print("  eval     Run evaluations")
+    print("  live     Start live reporter server")
+    print("  tags     Tag inspection commands")
+    print(HELP_EPILOG)
+
+
+def _create_base_parser() -> argparse.ArgumentParser:
+    """Parser with just target and app-dir for initial loading."""
+    parser = argparse.ArgumentParser(
+        prog="apte run",
+        description="Run tests",
+        add_help=False,  # We'll add help to the full parser
+    )
+    parser.add_argument(
+        "target",
+        nargs="?",
+        help="Module and session: 'module:session' (e.g., 'demo:session')",
+    )
+    parser.add_argument(
+        "--app-dir",
+        default=".",
+        help="Look for module in this directory (default: .)",
+    )
+    return parser
+
+
+def _create_run_parser(
+    *,
+    include_eval_options: bool = False,
+) -> argparse.ArgumentParser:
+    """Base parser with core run options. Plugin options added dynamically.
+
+    `include_eval_options=True` adds eval-only flags (e.g. ``--show-output``).
+    Set when building the parser for ``apte eval``; left False for
+    ``apte run`` so the eval-only flags don't pollute the test help/parsing.
+    """
+    parser = argparse.ArgumentParser(
+        prog="apte eval" if include_eval_options else "apte run",
+        description="Run evals" if include_eval_options else "Run tests",
+    )
+    parser.add_argument(
+        "target",
+        help="Module and session: 'module:session' (e.g., 'demo:session')",
+    )
+    parser.add_argument(
+        "--app-dir",
+        default=".",
+        help="Look for module in this directory (default: .)",
+    )
+    parser.add_argument(
+        "-n",
+        "--concurrency",
+        type=int,
+        default=1,
+        help="Number of concurrent tests (default: 1)",
+    )
+    parser.add_argument(
+        "--collect-only",
+        dest="collect_only",
+        action="store_true",
+        help="Only collect and list tests, don't run them",
+    )
+    parser.add_argument(
+        "-x",
+        "--exitfirst",
+        action="store_true",
+        help="Exit after first failed test",
+    )
+    parser.add_argument(
+        "-s",
+        "--no-capture",
+        dest="no_capture",
+        action="store_true",
+        help="Disable stdout/stderr capture (show print output)",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        dest="quiet",
+        action="store_true",
+        help="Minimal output (summary only)",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        dest="verbosity",
+        action="count",
+        default=0,
+        help="Increase verbosity (-v for lifecycle, -vv for fixtures)",
+    )
+    parser.add_argument(
+        "--show-logs",
+        dest="show_logs",
+        nargs="?",
+        const="INFO",
+        default=None,
+        metavar="LEVEL",
+        help="Show captured log records (default: INFO+)",
+    )
+    if include_eval_options:
+        parser.add_argument(
+            "--show-output",
+            dest="show_output",
+            action="store_true",
+            help="Show eval inputs/output/expected per case",
+        )
+        parser.add_argument(
+            "--short",
+            dest="short",
+            action="store_true",
+            help="Compact eval output: only print scores that failed per case",
+        )
+    return parser
+
+
+def _handle_run_command(kind_filter: str | None = None) -> None:
+    """Handle 'apte run' / 'apte eval' with two-phase parsing."""
+    argv = sys.argv[2:]
+    include_eval_options = kind_filter == "eval"
+
+    # Phase 1: Parse base args to get target
+    base_parser = _create_base_parser()
+    base_args, remaining = base_parser.parse_known_args(argv)
+
+    # If --help without target, show full help with all plugin options
+    if ("--help" in remaining or "-h" in remaining) and not base_args.target:
+        full_parser = _create_run_parser(include_eval_options=include_eval_options)
+        for plugin_class in ApteSession.default_plugin_classes():
+            plugin_class.add_cli_options(full_parser)
+        full_parser.parse_args(["--help"])
+        return
+
+    if not base_args.target:
+        _create_run_parser(include_eval_options=include_eval_options).print_help()
+        sys.exit(1)
+
+    # Phase 2: Load session and register default plugins
+    session_target, suite_filter = parse_target(base_args.target)
+    try:
+        session = load_session(session_target, base_args.app_dir)
+    except LoadError as exc:
+        print(f"Error: {exc}")
+        sys.exit(1)
+
+    session.register_default_plugins()
+
+    # Phase 3: Build full parser with plugin options
+    full_parser = _create_run_parser(include_eval_options=include_eval_options)
+    for plugin_class in session.plugin_classes:
+        plugin_class.add_cli_options(full_parser)
+
+    # Phase 4: Full parse
+    args = full_parser.parse_args(argv)
+
+    # Phase 5: Build context
+    effective_verbosity = Verbosity.QUIET if args.quiet else args.verbosity
+    ctx_args: dict[str, Any] = {
+        **vars(args),
+        "target_suite": suite_filter,
+        "verbosity": effective_verbosity,
+    }
+    if kind_filter:
+        ctx_args["kind_filter"] = kind_filter
+    ctx = PluginContext(args=ctx_args)
+
+    # Phase 6: Run tests (api.run_session handles plugin activation)
+    run_tests(session, ctx, collect_only=args.collect_only)
+
+
+def run_tests(
+    session: ApteSession,
+    ctx: PluginContext,
+    collect_only: bool = False,
+) -> None:
+    if collect_only:
+        items = collect_tests(session, ctx=ctx)
+        print(f"Collected {len(items)} test(s):\n")
+        for item in items:
+            print(f"  {item.node_id}")
+        sys.exit(0)
+
+    result = run_session(session, ctx=ctx)
+    exit_code_interrupted = 130
+    if result.interrupted:
+        sys.exit(exit_code_interrupted)
+    sys.exit(0 if result.success else 1)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

apte/compat.py

@@ -0,0 +1,15 @@
+"""Compatibility imports for typing features across Python versions."""
+
+import sys
+
+if sys.version_info >= (3, 11):
+    from typing import LiteralString, Self
+else:
+    from typing_extensions import LiteralString, Self
+
+if sys.version_info >= (3, 13):
+    from typing import TypeIs
+else:
+    from typing_extensions import TypeIs
+
+__all__ = ["LiteralString", "Self", "TypeIs"]

apte/console.py

@@ -0,0 +1,85 @@
+"""apte.console - progress output that bypasses test capture.
+
+Usage::
+
+    from apte import console
+
+    @fixture()
+    async def pipeline():
+        for i, scene in enumerate(scenes):
+            console.print(f"[bold]pipeline:[/] importing {scene.name} ({i+1}/{len(scenes)})")
+            await import_scene(scene)
+
+    # Raw mode - no markup processing
+    console.print("debug: raw bytes here", raw=True)
+
+    # Section mode - no per-test prefix (use for suite/session-level lines)
+    console.print(f"  Results: {run_dir}", prefix=False)
+
+Messages go through the event bus → reporters display them inline.
+If no event bus is available (outside a apte session), falls back to stderr.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import re
+
+from apte.events.types import Event
+from apte.execution.capture import get_event_bus, real_stderr
+
+
+def print(msg: str, *, raw: bool = False, prefix: bool = True) -> None:
+    """Print a message that bypasses test capture.
+
+    Goes through the event bus so reporters display it at the right place.
+    Supports Rich markup (stripped for ASCII reporter).
+
+    Args:
+        msg: The message to print. Supports Rich markup unless raw=True.
+        raw: If True, no markup processing - message passed as-is.
+        prefix: If False, omit the per-test indent/bar prefix. Use for
+            suite-level or session-level lines (e.g. "Results: <dir>") that
+            visually belong outside any single case's output block.
+    """
+    bus = get_event_bus()
+    if bus is None:
+        _fallback_print(msg, raw)
+        return
+
+    # Intentional private access to `bus._handlers`: we need sync dispatch
+    # so messages appear immediately (not after the test). An earlier public
+    # `EventBus.emit_sync` was removed (commit e14ffd5) because its signal-
+    # handler use case was async-signal-unsafe, and we don't want to offer
+    # that API to users. Kept private here - the framework itself is the
+    # only caller, and console.print is never invoked from a signal handler.
+    for handler_entry in bus._handlers.get(Event.USER_PRINT, []):
+        try:
+            handler_entry.func((msg, raw, prefix))
+        except Exception as exc:
+            # Surface handler failures (typically: malformed Rich markup) on
+            # real stderr so users don't conclude `console.print` is silently
+            # broken. Wrapped in suppress() to guarantee the loop continues
+            # even if the fallback write itself raises.
+            with contextlib.suppress(Exception):
+                stream = real_stderr()
+                stream.write(f"console.print: handler raised {exc!r}\n")
+                stream.flush()
+
+
+def _fallback_print(msg: str, raw: bool) -> None:
+    """Fallback when no event bus - write to real stderr (bypassing capture)."""
+    text = msg if raw else strip_markup(msg)
+    stream = real_stderr()
+    stream.write(text + "\n")
+    stream.flush()
+
+
+def strip_markup(msg: str) -> str:
+    """Strip Rich markup tags from a string.
+
+    Handles escaped brackets (``\\[text]`` → ``[text]``).
+    """
+    msg = msg.replace("\\[", "\x00")
+    msg = re.sub(r"\[/?[^\]]*\]", "", msg)
+    return msg.replace("\x00", "[")

apte/core/collector.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+from inspect import signature
+from itertools import groupby, product
+from typing import TYPE_CHECKING, Annotated, Any, get_args, get_origin
+
+from apte.di.decorators import get_fixture_marker, unwrap_fixture
+from apte.di.hints import get_type_hints_compat
+from apte.di.markers import Use
+from apte.di.validation import _extract_from_params
+from apte.entities import FixtureCallable, SuitePath, TestItem, TestRegistration
+from apte.evals.evaluator import EvalCase
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from apte.core.session import ApteSession
+    from apte.core.suite import ApteSuite
+
+
+def _extract_use_fixtures(func: Callable[..., Any]) -> list[FixtureCallable]:
+    """Extract fixtures referenced via Use() markers in function parameters."""
+    type_hints = get_type_hints_compat(func)
+
+    fixtures: list[FixtureCallable] = []
+    for param_name in signature(func).parameters:
+        annotation = type_hints.get(param_name)
+        if annotation is not None and get_origin(annotation) is Annotated:
+            for metadata in get_args(annotation)[1:]:
+                if isinstance(metadata, Use):
+                    # Unwrap FixtureWrapper to get the original function
+                    fixtures.append(unwrap_fixture(metadata.dependency))
+                    break
+    return fixtures
+
+
+def get_transitive_fixtures(
+    func: Callable[..., Any],
+    visited: set[FixtureCallable] | None = None,
+) -> set[FixtureCallable]:
+    """Get all fixtures (direct + transitive) used by a function.
+
+    Recursively follows Use() markers to collect all fixtures in the
+    dependency chain. Handles cycles via visited set.
+
+    Args:
+        func: The function to analyze (test or fixture).
+        visited: Set of already-visited fixtures (for cycle prevention).
+
+    Returns:
+        Set of all fixture functions used directly or transitively.
+    """
+    if visited is None:
+        visited = set()
+
+    result: set[FixtureCallable] = set()
+    direct = _extract_use_fixtures(func)
+
+    for fixture_func in direct:
+        if fixture_func in visited:
+            continue
+        visited.add(fixture_func)
+        result.add(fixture_func)
+        # Recursively get fixtures used by this fixture
+        result.update(get_transitive_fixtures(fixture_func, visited))
+
+    return result
+
+
+class Collector:
+    """Collects tests from a session, recursively traversing nested suites."""
+
+    def __init__(self) -> None:
+        self._fixture_tags: dict[FixtureCallable, set[str]] = {}
+        self._fixture_deps: dict[FixtureCallable, list[FixtureCallable]] = {}
+
+    def collect(self, session: ApteSession) -> list[TestItem]:
+        """Collect all tests from session and nested suites into TestItems."""
+        self._build_fixture_index(session)
+
+        items: list[TestItem] = []
+
+        for test_reg in session.tests:
+            items.extend(self._expand_registration(test_reg, suite=None))
+
+        for suite in session.suites:
+            items.extend(self._collect_from_suite(suite))
+
+        return items
+
+    def _build_fixture_index(self, session: ApteSession) -> None:
+        """Build index of all fixtures with their tags and dependencies."""
+        for fixture_reg in session.fixtures:
+            self._fixture_tags[fixture_reg.func] = fixture_reg.tags
+            self._fixture_deps[fixture_reg.func] = _extract_use_fixtures(
+                fixture_reg.func
+            )
+
+        self._index_suite_fixtures(session.suites)
+
+    def _index_suite_fixtures(self, suites: list[ApteSuite]) -> None:
+        """Recursively index fixtures from suites."""
+        for suite in suites:
+            for fixture_reg in suite.fixtures:
+                self._fixture_tags[fixture_reg.func] = fixture_reg.tags
+                self._fixture_deps[fixture_reg.func] = _extract_use_fixtures(
+                    fixture_reg.func
+                )
+            self._index_suite_fixtures(suite.suites)
+
+    def _get_transitive_fixture_tags(
+        self, func: FixtureCallable, visited: set[FixtureCallable] | None = None
+    ) -> set[str]:
+        """Get all tags from a fixture and its dependencies (transitive)."""
+        if visited is None:
+            visited = set()
+        if func in visited:
+            return set()
+        visited.add(func)
+
+        # Try indexed tags first, fallback to marker for unbound fixtures
+        if func in self._fixture_tags:
+            tags = self._fixture_tags[func].copy()
+        else:
+            marker = get_fixture_marker(func)
+            tags = set(marker.tags) if marker else set()
+
+        # Get dependencies: indexed or extract from signature for unbound
+        deps = self._fixture_deps.get(func) or _extract_use_fixtures(func)
+        for dep_func in deps:
+            tags.update(self._get_transitive_fixture_tags(dep_func, visited))
+
+        return tags
+
+    def _compute_test_tags(
+        self, test_reg: TestRegistration, suite: ApteSuite | None
+    ) -> set[str]:
+        """Compute all tags for a test: explicit + suite + fixture (transitive)."""
+        tags = test_reg.tags.copy()
+
+        if suite:
+            tags.update(suite.all_tags)
+
+        for fixture_func in _extract_use_fixtures(test_reg.func):
+            tags.update(self._get_transitive_fixture_tags(fixture_func))
+
+        return tags
+
+    def _expand_registration(
+        self, test_reg: TestRegistration, suite: ApteSuite | None
+    ) -> list[TestItem]:
+        """Expand a TestRegistration into TestItems with computed tags."""
+        tags = self._compute_test_tags(test_reg, suite)
+        from_params = _extract_from_params(test_reg.func)
+
+        if not from_params:
+            return [
+                TestItem(
+                    func=test_reg.func,
+                    suite=suite,
+                    tags=tags,
+                    skip=test_reg.skip,
+                    xfail=test_reg.xfail,
+                    timeout=test_reg.timeout,
+                    retry=test_reg.retry,
+                    is_eval=test_reg.is_eval,
+                )
+            ]
+
+        param_names = list(from_params.keys())
+        sources = [from_params[name] for name in param_names]
+
+        items: list[TestItem] = []
+        for combination in product(*sources):
+            case_kwargs = dict(zip(param_names, combination, strict=True))
+            case_ids = [
+                sources[index].get_id(value) for index, value in enumerate(combination)
+            ]
+
+            item_tags = tags.copy()
+            for value in combination:
+                if isinstance(value, EvalCase) and value.tags:
+                    item_tags.update(value.tags)
+
+            items.append(
+                TestItem(
+                    func=test_reg.func,
+                    suite=suite,
+                    tags=item_tags,
+                    case_kwargs=case_kwargs,
+                    case_ids=case_ids,
+                    skip=test_reg.skip,
+                    xfail=test_reg.xfail,
+                    timeout=test_reg.timeout,
+                    retry=test_reg.retry,
+                    is_eval=test_reg.is_eval,
+                )
+            )
+
+        return items
+
+    def _collect_from_suite(self, suite: ApteSuite) -> list[TestItem]:
+        """Recursively collect tests from suite and its children."""
+        items: list[TestItem] = []
+
+        for test_reg in suite.tests:
+            items.extend(self._expand_registration(test_reg, suite))
+
+        for child in suite.suites:
+            items.extend(self._collect_from_suite(child))
+
+        return items
+
+
+def chunk_by_suite(items: list[TestItem]) -> list[list[TestItem]]:
+    """Group contiguous tests by suite."""
+    if not items:
+        return []
+    return [list(group) for _, group in groupby(items, key=lambda item: item.suite)]
+
+
+def get_last_chunk_index_per_suite(
+    chunks: list[list[TestItem]],
+) -> dict[SuitePath, int]:
+    """For each suite, return the index of its last chunk (including descendants)."""
+    last_indices: dict[SuitePath, int] = {}
+    for chunk_idx, chunk in enumerate(chunks):
+        suite = chunk[0].suite
+        if suite:
+            last_indices[suite.full_path] = chunk_idx
+            _update_parent_indices(last_indices, suite, chunk_idx)
+    return last_indices
+
+
+def _update_parent_indices(
+    last_indices: dict[SuitePath, int], suite: ApteSuite, chunk_idx: int
+) -> None:
+    """Update parent suite indices when a child chunk is seen."""
+    parent = suite._parent_suite
+    while parent:
+        last_indices[parent.full_path] = chunk_idx
+        parent = parent._parent_suite

apte/core/execution/__init__.py

@@ -0,0 +1,7 @@
+"""Execution components extracted from runner.py."""
+
+from apte.core.execution.parallel import ParallelExecutor
+from apte.core.execution.suite_manager import SuiteManager
+from apte.core.execution.test_executor import TestExecutor
+
+__all__ = ["ParallelExecutor", "SuiteManager", "TestExecutor"]