apte 0.3.0__py3-none-any.whl

apte/__init__.py

@@ -0,0 +1,55 @@
+from apte import console
+from apte.api import collect_tests, list_tags, run_session
+from apte.assertions import ExceptionInfo, RaisesContext, raises, warns
+from apte.core.session import ApteSession
+from apte.core.suite import ApteSuite
+from apte.di.decorators import factory, fixture
+from apte.di.factory import FixtureFactory
+from apte.di.markers import ForEach, From, Use
+from apte.entities import FixtureCallable, Retry, Skip, Xfail
+from apte.exceptions import ApteError, CircularDependencyError, FixtureError
+from apte.fixtures.builtins import caplog, mocker, tmp_path
+from apte.fixtures.mocker import AsyncMockType, Mocker, MockType
+from apte.loader import LoadError, load_session
+from apte.plugin import PluginBase
+from apte.shell import CommandResult, Shell
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "ApteError",
+    "ApteSession",
+    "ApteSuite",
+    "AsyncMockType",
+    "CircularDependencyError",
+    "CommandResult",
+    "ExceptionInfo",
+    "FixtureCallable",
+    "FixtureError",
+    "FixtureFactory",
+    "ForEach",
+    "From",
+    "LoadError",
+    "MockType",
+    "Mocker",
+    "PluginBase",
+    "RaisesContext",
+    "Retry",
+    "Shell",
+    "Skip",
+    "Use",
+    "Xfail",
+    "__version__",
+    "caplog",
+    "collect_tests",
+    "console",
+    "factory",
+    "fixture",
+    "list_tags",
+    "load_session",
+    "mocker",
+    "raises",
+    "run_session",
+    "tmp_path",
+    "warns",
+]

apte/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running apte as: python -m apte / coverage run -m apte."""
+
+from apte.cli.main import main
+
+main()

apte/api.py

@@ -0,0 +1,194 @@
+"""Public API for running Apte sessions.
+
+This module provides the main entry points for running tests programmatically,
+independent of any CLI or adapter implementation.
+
+Example:
+    from apte import ApteSession
+    from apte.api import run_session
+
+    session = ApteSession()
+
+    @session.test()
+    def test_example():
+        assert True
+
+    success = run_session(session)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from apte.core.collector import Collector
+from apte.core.runner import TestRunner
+from apte.core.suite import (
+    ApteSuite,  # noqa: TC001 - used at runtime in list_tags
+)
+from apte.events.types import Event
+from apte.filters.keyword import KeywordFilterPlugin
+from apte.filters.kind import KindFilterPlugin
+from apte.filters.suite import SuiteFilterPlugin
+from apte.plugin import PluginBase, PluginContext
+from apte.tags.plugin import TagFilterPlugin
+
+if TYPE_CHECKING:
+    from apte.core.session import ApteSession
+    from apte.entities import RunResult, TestItem
+
+
+def run_session(  # noqa: PLR0913 - public API with many optional params
+    session: ApteSession,
+    concurrency: int | None = None,
+    exitfirst: bool = False,
+    last_failed: bool = False,
+    cache_clear: bool = False,
+    include_tags: set[str] | None = None,
+    exclude_tags: set[str] | None = None,
+    capture: bool = True,
+    suite_filter: str | None = None,
+    keyword_patterns: list[str] | None = None,
+    log_file: bool = True,
+    force_no_color: bool = False,
+    *,
+    ctx: PluginContext | None = None,
+) -> RunResult:
+    """Run a test session and return result with success and interrupted status.
+
+    This is the main entry point for running tests programmatically.
+
+    Args:
+        session: The ApteSession to run.
+        concurrency: Number of concurrent workers (None = use session default).
+        exitfirst: Stop after first failure.
+        last_failed: Only run tests that failed in the last run.
+        cache_clear: Clear the cache before running.
+        include_tags: Only run tests with these tags (OR logic).
+        exclude_tags: Exclude tests with these tags.
+        capture: Capture stdout/stderr during tests (default: True).
+        suite_filter: Only run tests in this suite (::SuiteName syntax).
+        keyword_patterns: Only run tests matching these patterns (-k flag).
+        log_file: Write output to .apte/last_run.log (default: True).
+        force_no_color: Disable colors (--no-color flag).
+        ctx: Plugin context (if provided, overrides individual params above).
+
+    Returns:
+        RunResult with success status and interrupted flag.
+    """
+    # Apply session-level settings from ctx or params
+    if ctx is not None:
+        if ctx.get("concurrency") is not None:
+            session.concurrency = ctx.get("concurrency")
+        session.exitfirst = ctx.get("exitfirst", False)
+        session.capture = not ctx.get("no_capture", False)
+    else:
+        if concurrency is not None:
+            session.concurrency = concurrency
+        session.exitfirst = exitfirst
+        session.capture = capture
+
+    # Register default plugins if none registered
+    if not session.plugin_classes:
+        session.register_default_plugins()
+
+    # Build context from parameters if not provided
+    if ctx is None:
+        ctx = PluginContext(
+            args={
+                "last_failed": last_failed,
+                "cache_clear": cache_clear,
+                "tags": list(include_tags) if include_tags else [],
+                "exclude_tags": list(exclude_tags) if exclude_tags else [],
+                "target_suite": suite_filter,
+                "keywords": keyword_patterns or [],
+                "no_log_file": not log_file,
+                "no_color": force_no_color,
+            }
+        )
+
+    session.activate_plugins(ctx)
+
+    runner = TestRunner(session)
+    return runner.run()
+
+
+def collect_tests(  # noqa: PLR0913 - public API with many optional params
+    session: ApteSession,
+    include_tags: set[str] | None = None,
+    exclude_tags: set[str] | None = None,
+    suite_filter: str | None = None,
+    keyword_patterns: list[str] | None = None,
+    *,
+    ctx: PluginContext | None = None,
+) -> list[TestItem]:
+    """Collect tests from a session without running them.
+
+    Args:
+        session: The ApteSession to collect from.
+        include_tags: Only include tests with these tags.
+        exclude_tags: Exclude tests with these tags.
+        suite_filter: Only include tests in this suite.
+        keyword_patterns: Only include tests matching these patterns.
+        ctx: Plugin context (if provided, overrides individual params above).
+
+    Returns:
+        List of collected TestItem objects.
+    """
+    # Build context from parameters if not provided
+    if ctx is None:
+        ctx = PluginContext(
+            args={
+                "tags": list(include_tags) if include_tags else [],
+                "exclude_tags": list(exclude_tags) if exclude_tags else [],
+                "target_suite": suite_filter,
+                "keywords": keyword_patterns or [],
+            }
+        )
+
+    # Activate filter plugins
+    filter_plugins: list[type[PluginBase]] = [
+        TagFilterPlugin,
+        SuiteFilterPlugin,
+        KeywordFilterPlugin,
+        KindFilterPlugin,
+    ]
+    for plugin_class in filter_plugins:
+        instance = plugin_class.activate(ctx)
+        if instance is not None:
+            session.register_plugin(instance)
+
+    collector = Collector()
+    items = collector.collect(session)
+    return asyncio.run(session.events.emit_and_collect(Event.COLLECTION_FINISH, items))
+
+
+def list_tags(session: ApteSession) -> set[str]:
+    """List all declared tags in a session.
+
+    Args:
+        session: The ApteSession to inspect.
+
+    Returns:
+        Set of all tag names declared on fixtures, suites, and tests.
+    """
+    all_tags: set[str] = set()
+
+    for fixture_reg in session.fixtures:
+        all_tags.update(fixture_reg.tags)
+
+    for test_reg in session.tests:
+        all_tags.update(test_reg.tags)
+
+    def collect_from_suites(suites: list[ApteSuite]) -> None:
+        for suite in suites:
+            all_tags.update(suite.tags)
+            for fixture_reg in suite.fixtures:
+                all_tags.update(fixture_reg.tags)
+            for test_reg in suite.tests:
+                all_tags.update(test_reg.tags)
+            collect_from_suites(suite.suites)
+
+    collect_from_suites(session.suites)
+
+    return all_tags

apte/assertions.py

@@ -0,0 +1,152 @@
+import re
+import warnings
+from contextlib import contextmanager
+from re import Pattern
+from types import TracebackType
+from typing import TYPE_CHECKING, Generic, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+E = TypeVar("E", bound=BaseException)
+
+
+class ExceptionInfo(Generic[E]):
+    def __init__(self) -> None:
+        self._value: E | None = None
+        self._type: type[E] | None = None
+        self._traceback: TracebackType | None = None
+
+    def _populate(
+        self,
+        exc_type: type[E],
+        exc_value: E,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self._type = exc_type
+        self._value = exc_value
+        self._traceback = exc_tb
+
+    @property
+    def value(self) -> E:
+        if self._value is None:
+            raise AssertionError("No exception captured yet")
+        return self._value
+
+    @property
+    def type(self) -> type[E]:
+        if self._type is None:
+            raise AssertionError("No exception captured yet")
+        return self._type
+
+    @property
+    def traceback(self) -> TracebackType | None:
+        return self._traceback
+
+    def match(self, pattern: str | Pattern[str]) -> re.Match[str]:
+        compiled = re.compile(pattern) if isinstance(pattern, str) else pattern
+        result = compiled.search(str(self.value))
+        if result is None:
+            raise AssertionError(
+                f"Pattern '{pattern}' not found in '{self.value}'"
+            ) from self._value
+        return result
+
+
+class RaisesContext(Generic[E]):
+    def __init__(
+        self,
+        expected_exception: type[E],
+        match: str | Pattern[str] | None,
+    ) -> None:
+        self._expected = expected_exception
+        self._match_pattern: Pattern[str] | None = None
+        if match is not None:
+            self._match_pattern = re.compile(match) if isinstance(match, str) else match
+        self._exc_info: ExceptionInfo[E] = ExceptionInfo()
+
+    def __enter__(self) -> ExceptionInfo[E]:
+        return self._exc_info
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool:
+        if exc_type is None:
+            raise AssertionError(f"DID NOT RAISE {self._expected.__name__}")
+
+        if not issubclass(exc_type, self._expected):
+            return False
+
+        self._exc_info._populate(exc_type, exc_val, exc_tb)  # type: ignore[arg-type]
+
+        if self._match_pattern is not None:
+            result = self._match_pattern.search(str(exc_val))
+            if result is None:
+                raise AssertionError(
+                    f"Pattern '{self._match_pattern.pattern}' not found in '{exc_val}'"
+                ) from exc_val
+
+        return True
+
+
+def raises(
+    expected_exception: type[E],
+    match: str | Pattern[str] | None = None,
+) -> RaisesContext[E]:
+    return RaisesContext(expected_exception, match=match)
+
+
+@contextmanager
+def warns(
+    expected_warning: type[Warning] | tuple[type[Warning], ...] | None = None,
+    match: str | Pattern[str] | None = None,
+) -> "Generator[list[warnings.WarningMessage], None, None]":
+    """Context manager for capturing and validating warnings.
+
+    Args:
+        expected_warning: Warning type(s) expected. If None, captures all warnings.
+        match: Optional regex pattern to match against warning messages.
+
+    Yields:
+        List of captured warnings (stdlib warnings.WarningMessage objects).
+
+    Raises:
+        AssertionError: If expected warning not raised or pattern not matched.
+
+    Examples:
+        with warns(DeprecationWarning):
+            warnings.warn("deprecated", DeprecationWarning)
+
+        with warns(UserWarning, match=r"value.*\\d+"):
+            warnings.warn("value is 42", UserWarning)
+
+        with warns() as record:
+            warnings.warn("hello", UserWarning)
+        assert record[0].category is UserWarning
+    """
+    with warnings.catch_warnings(record=True) as record:
+        warnings.simplefilter("always")
+        yield record
+
+        if expected_warning is None:
+            return
+
+        matching = [w for w in record if issubclass(w.category, expected_warning)]
+
+        if not matching:
+            if isinstance(expected_warning, tuple):
+                names = ", ".join(e.__name__ for e in expected_warning)
+            else:
+                names = expected_warning.__name__
+            raise AssertionError(f"DID NOT WARN with {names}")
+
+        if match is not None:
+            pattern = re.compile(match) if isinstance(match, str) else match
+            if not any(pattern.search(str(w.message)) for w in matching):
+                messages = [str(w.message) for w in matching]
+                raise AssertionError(
+                    f"Pattern '{pattern.pattern}' not found in: {messages}"
+                )

apte/cache/__init__.py

@@ -0,0 +1,6 @@
+"""Cache module for Apte."""
+
+from apte.cache.plugin import CachePlugin
+from apte.cache.storage import CacheStorage, TestCacheEntry
+
+__all__ = ["CachePlugin", "CacheStorage", "TestCacheEntry"]

apte/cache/plugin.py

@@ -0,0 +1,94 @@
+"""Cache plugin for --lf (last-failed) and --cache-clear functionality."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from typing_extensions import Self
+
+from apte.plugin import PluginBase, PluginContext
+
+if TYPE_CHECKING:
+    from argparse import ArgumentParser
+
+    from apte.cache.storage import CacheStorage
+    from apte.core.session import ApteSession
+    from apte.entities import SessionResult, TestItem, TestResult
+
+
+class CachePlugin(PluginBase):
+    """Plugin that caches test results and provides --lf filtering."""
+
+    name = "cache"
+    description = "Test result caching with --lf support"
+
+    def __init__(self, last_failed: bool = False, cache_clear: bool = False) -> None:
+        self._last_failed = last_failed
+        self._cache_clear = cache_clear
+        self._cache: CacheStorage | None = None
+
+    @classmethod
+    def add_cli_options(cls, parser: ArgumentParser) -> None:
+        group = parser.add_argument_group(f"{cls.name} - {cls.description}")
+        group.add_argument(
+            "--lf",
+            "--last-failed",
+            dest="last_failed",
+            action="store_true",
+            help="Re-run only failed tests from last run",
+        )
+        group.add_argument(
+            "--cache-clear",
+            dest="cache_clear",
+            action="store_true",
+            help="Clear cache before run",
+        )
+
+    @classmethod
+    def activate(cls, ctx: PluginContext) -> Self:
+        return cls(
+            last_failed=ctx.get("last_failed", False),
+            cache_clear=ctx.get("cache_clear", False),
+        )
+
+    def setup(self, session: ApteSession) -> None:
+        self._cache = session.cache
+        if self._cache_clear:
+            self._cache.clear()
+        else:
+            self._cache.load()
+
+    def on_collection_finish(self, items: list[TestItem]) -> list[TestItem]:
+        """Filter tests based on --lf flag."""
+        if self._last_failed and self._cache is not None:
+            return self._filter_last_failed(items)
+        return items
+
+    def on_test_pass(self, result: TestResult) -> None:
+        if self._cache is not None:
+            self._cache.set_result(result.node_id, "passed", result.duration)
+
+    def on_test_fail(self, result: TestResult) -> None:
+        if self._cache is not None:
+            status = "error" if result.is_fixture_error else "failed"
+            self._cache.set_result(result.node_id, status, result.duration)
+
+    def on_session_end(self, result: SessionResult) -> None:
+        if self._cache is not None:
+            self._cache.save()
+
+    def _filter_last_failed(self, items: list[TestItem]) -> list[TestItem]:
+        """Keep only tests that failed in the last run.
+
+        If no failed tests exist in cache, returns all items.
+        If failed tests exist but none match current items, returns empty list.
+        """
+        if self._cache is None:
+            raise RuntimeError(
+                "CachePlugin improperly configured: setup() must be called before "
+                "filtering. This indicates a bug in the plugin lifecycle."
+            )
+        failed_ids = self._cache.get_failed_node_ids()
+        if not failed_ids:
+            return items
+        return [item for item in items if item.node_id in failed_ids]

apte/cache/storage.py

@@ -0,0 +1,132 @@
+"""Shared cache storage for inter-plugin data sharing."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class TestCacheEntry:
+    status: str
+    duration: float
+
+
+class CacheStorage:
+    """Shared cache storage accessible via session.cache.
+
+    Provides a clean API for plugins to read/write cached test data
+    without direct file dependencies.
+
+    Example:
+        # In a plugin
+        def setup(self, session: ApteSession) -> None:
+            results = session.cache.get_results()
+            durations = session.cache.get_durations()
+
+        def on_test_pass(self, result: TestResult) -> None:
+            session.cache.set_result(result.node_id, "passed", result.duration)
+    """
+
+    DEFAULT_DIR = Path(".apte")
+    DEFAULT_FILE = "cache.json"
+
+    def __init__(
+        self, cache_dir: Path | None = None, cache_file: str | None = None
+    ) -> None:
+        self._cache_dir = cache_dir or self.DEFAULT_DIR
+        self._cache_file = self._cache_dir / (cache_file or self.DEFAULT_FILE)
+        self._data: dict[str, Any] = {}
+        self._results: dict[str, TestCacheEntry] = {}
+        self._dirty = False
+
+    @property
+    def cache_dir(self) -> Path:
+        return self._cache_dir
+
+    @property
+    def cache_file(self) -> Path:
+        return self._cache_file
+
+    def load(self) -> None:
+        """Load cache from disk."""
+        if self._cache_file.exists():
+            try:
+                raw_data = json.loads(self._cache_file.read_text())
+                self._data = raw_data
+                self._load_results_from_data(raw_data)
+            except json.JSONDecodeError:
+                self._data = {}
+                self._results = {}
+
+    def _load_results_from_data(self, data: dict[str, Any]) -> None:
+        raw_results = data.get("results", {})
+        if not isinstance(raw_results, dict):
+            self._results = {}
+            return
+        self._results = {}
+        for node_id, entry in raw_results.items():
+            if isinstance(entry, dict):
+                self._results[node_id] = TestCacheEntry(
+                    status=entry.get("status", "unknown"),
+                    duration=float(entry.get("duration", 0.0)),
+                )
+
+    def save(self) -> None:
+        """Save cache to disk."""
+        self._cache_dir.mkdir(exist_ok=True)
+        results_dict = {
+            node_id: {"status": entry.status, "duration": entry.duration}
+            for node_id, entry in self._results.items()
+        }
+        data = {
+            "version": 1,
+            "timestamp": time.time(),
+            "results": results_dict,
+        }
+        self._cache_file.write_text(json.dumps(data, indent=2))
+        self._dirty = False
+
+    def clear(self) -> None:
+        """Clear all cached data."""
+        if self._cache_file.exists():
+            self._cache_file.unlink()
+        self._data = {}
+        self._results = {}
+        self._dirty = False
+
+    def get_results(self) -> dict[str, TestCacheEntry]:
+        """Get all cached test results."""
+        return dict(self._results)
+
+    def get_result(self, node_id: str) -> TestCacheEntry | None:
+        """Get cached result for a specific test."""
+        return self._results.get(node_id)
+
+    def set_result(self, node_id: str, status: str, duration: float) -> None:
+        """Set a test result in the cache."""
+        self._results[node_id] = TestCacheEntry(status=status, duration=duration)
+        self._dirty = True
+
+    def get_durations(self) -> dict[str, float]:
+        """Get all cached test durations (useful for duration-based ordering)."""
+        return {node_id: entry.duration for node_id, entry in self._results.items()}
+
+    def get_failed_node_ids(self) -> set[str]:
+        """Get node IDs of tests that failed in the last run."""
+        return {
+            node_id
+            for node_id, entry in self._results.items()
+            if entry.status in ("failed", "error")
+        }
+
+    def get_passed_node_ids(self) -> set[str]:
+        """Get node IDs of tests that passed in the last run."""
+        return {
+            node_id
+            for node_id, entry in self._results.items()
+            if entry.status == "passed"
+        }