rustest 0.5.0__cp312-cp312-win_amd64.whl

rustest/__init__.py

@@ -0,0 +1,28 @@
+"""Public Python API for rustest."""
+
+from __future__ import annotations
+
+from . import decorators
+from .approx import approx
+from .cli import main
+from .reporting import RunReport, TestResult
+from .core import run
+
+fixture = decorators.fixture
+mark = decorators.mark
+parametrize = decorators.parametrize
+raises = decorators.raises
+skip = decorators.skip
+
+__all__ = [
+    "RunReport",
+    "TestResult",
+    "approx",
+    "fixture",
+    "main",
+    "mark",
+    "parametrize",
+    "raises",
+    "run",
+    "skip",
+]

rustest/__main__.py

@@ -0,0 +1,10 @@
+"""Module executed when running ``python -m rustest``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

rustest/approx.py

@@ -0,0 +1,160 @@
+"""Approximate comparison for floating-point numbers.
+
+This module provides the `approx` class for comparing floating-point numbers
+with a tolerance, similar to pytest.approx.
+"""
+
+from typing import Any, Mapping, Sequence, Union
+
+# Type alias for values that can be approximated
+ApproxValue = Union[float, int, complex, Sequence[Any], Mapping[str, Any]]
+
+
+class approx:
+    """Assert that two numbers (or collections of numbers) are equal to each other
+    within some tolerance.
+
+    This is similar to pytest.approx and is useful for comparing floating-point
+    numbers that may have small rounding errors.
+
+    Usage:
+        assert 0.1 + 0.2 == approx(0.3)
+        assert 0.1 + 0.2 == approx(0.3, rel=1e-6)
+        assert 0.1 + 0.2 == approx(0.3, abs=1e-9)
+        assert [0.1 + 0.2, 0.3] == approx([0.3, 0.3])
+        assert {"a": 0.1 + 0.2} == approx({"a": 0.3})
+
+    Args:
+        expected: The expected value to compare against
+        rel: The relative tolerance (default: 1e-6)
+        abs: The absolute tolerance (default: 1e-12)
+
+    By default, numbers are considered close if the difference between them is
+    less than or equal to:
+        abs(expected * rel) + abs_tolerance
+    """
+
+    def __init__(
+        self,
+        expected: ApproxValue,
+        rel: float = 1e-6,
+        abs: float = 1e-12,
+    ) -> None:
+        """Initialize approx with expected value and tolerances.
+
+        Args:
+            expected: The expected value to compare against
+            rel: The relative tolerance (default: 1e-6)
+            abs: The absolute tolerance (default: 1e-12)
+        """
+        super().__init__()
+        self.expected = expected
+        self.rel = rel
+        self.abs = abs
+
+    def __repr__(self) -> str:
+        """Return a string representation of the approx object."""
+        return f"approx({self.expected!r}, rel={self.rel}, abs={self.abs})"
+
+    def __eq__(self, actual: Any) -> bool:
+        """Compare actual value with expected value within tolerance.
+
+        Args:
+            actual: The actual value to compare
+
+        Returns:
+            True if the values are approximately equal, False otherwise
+        """
+        return self._approx_compare(actual, self.expected)
+
+    def _approx_compare(self, actual: Any, expected: Any) -> bool:
+        """Recursively compare actual and expected values.
+
+        Args:
+            actual: The actual value
+            expected: The expected value
+
+        Returns:
+            True if values are approximately equal, False otherwise
+        """
+        # Handle None
+        if actual is None or expected is None:
+            return actual == expected
+
+        # Handle dictionaries
+        if isinstance(expected, dict):
+            if not isinstance(actual, dict):
+                return False
+            if set(actual.keys()) != set(expected.keys()):
+                return False
+            return all(self._approx_compare(actual[k], expected[k]) for k in expected.keys())
+
+        # Handle sequences (lists, tuples, etc.) but not strings
+        if isinstance(expected, (list, tuple)) and not isinstance(expected, str):
+            # Check that actual is the same type (list vs tuple matters)
+            if type(actual) is not type(expected):
+                return False
+            if len(actual) != len(expected):
+                return False
+            return all(self._approx_compare(a, e) for a, e in zip(actual, expected))
+
+        # Handle numbers (float, int, complex)
+        if isinstance(expected, (float, int, complex)) and isinstance(
+            actual, (float, int, complex)
+        ):
+            return self._is_close(actual, expected)
+
+        # For other types, use exact equality
+        return actual == expected
+
+    def _is_close(
+        self, actual: Union[float, int, complex], expected: Union[float, int, complex]
+    ) -> bool:
+        """Check if two numbers are close within tolerance.
+
+        Uses the formula: |actual - expected| <= max(rel * max(|actual|, |expected|), abs)
+
+        Args:
+            actual: The actual number
+            expected: The expected number
+
+        Returns:
+            True if numbers are close, False otherwise
+        """
+        # Handle infinities and NaN
+        if isinstance(actual, complex) or isinstance(expected, complex):
+            # For complex numbers, compare real and imaginary parts separately
+            if isinstance(actual, complex) and isinstance(expected, complex):
+                return self._is_close(actual.real, expected.real) and self._is_close(
+                    actual.imag, expected.imag
+                )
+            # One is complex, the other is not
+            if isinstance(actual, complex):
+                return self._is_close(actual.real, expected) and abs(actual.imag) <= self.abs
+            else:  # expected is complex
+                return self._is_close(actual, expected.real) and abs(expected.imag) <= self.abs
+
+        # Convert to float for comparison
+        actual_float = float(actual)
+        expected_float = float(expected)
+
+        # Handle special float values
+        if actual_float == expected_float:
+            # This handles infinities and zeros
+            return True
+
+        # Check for NaN - NaN should never be equal to anything
+        import math
+
+        if math.isnan(actual_float) or math.isnan(expected_float):
+            return False
+
+        # Check for infinities
+        if math.isinf(actual_float) or math.isinf(expected_float):
+            return actual_float == expected_float
+
+        # Calculate tolerance
+        abs_diff = abs(actual_float - expected_float)
+        tolerance = max(self.rel * max(abs(actual_float), abs(expected_float)), self.abs)
+
+        return abs_diff <= tolerance

rustest/cli.py

@@ -0,0 +1,273 @@
+"""Command line interface helpers."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from .reporting import RunReport, TestResult
+from .core import run
+
+
+# ANSI color codes
+class _ColorsNamespace:
+    """Namespace for ANSI color codes."""
+
+    def __init__(self) -> None:  # pyright: ignore[reportMissingSuperCall]
+        self.green = "\033[92m"
+        self.red = "\033[91m"
+        self.yellow = "\033[93m"
+        self.cyan = "\033[96m"
+        self.bold = "\033[1m"
+        self.dim = "\033[2m"
+        self.reset = "\033[0m"
+
+    def disable(self) -> None:
+        """Disable all colors."""
+        self.green = ""
+        self.red = ""
+        self.yellow = ""
+        self.cyan = ""
+        self.bold = ""
+        self.dim = ""
+        self.reset = ""
+
+
+Colors = _ColorsNamespace()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="rustest",
+        description="Run Python tests at blazing speed with a Rust powered core.",
+    )
+    _ = parser.add_argument(
+        "paths",
+        nargs="*",
+        default=(".",),
+        help="Files or directories to collect tests from.",
+    )
+    _ = parser.add_argument(
+        "-k",
+        "--pattern",
+        help="Substring to filter tests by (case insensitive).",
+    )
+    _ = parser.add_argument(
+        "-m",
+        "--marks",
+        dest="mark_expr",
+        help='Run tests matching the given mark expression (e.g., "slow", "not slow", "slow and integration").',
+    )
+    _ = parser.add_argument(
+        "-n",
+        "--workers",
+        type=int,
+        help="Number of worker slots to use (experimental).",
+    )
+    _ = parser.add_argument(
+        "--no-capture",
+        dest="capture_output",
+        action="store_false",
+        help="Do not capture stdout/stderr during test execution.",
+    )
+    _ = parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Show verbose output with hierarchical test structure.",
+    )
+    _ = parser.add_argument(
+        "--ascii",
+        action="store_true",
+        help="Use ASCII characters instead of Unicode symbols for output.",
+    )
+    _ = parser.add_argument(
+        "--no-color",
+        dest="color",
+        action="store_false",
+        help="Disable colored output.",
+    )
+    _ = parser.add_argument(
+        "--no-codeblocks",
+        dest="enable_codeblocks",
+        action="store_false",
+        help="Disable code block tests from markdown files.",
+    )
+    _ = parser.set_defaults(capture_output=True, color=True, enable_codeblocks=True)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # Disable colors if requested
+    if not args.color:
+        Colors.disable()
+
+    report = run(
+        paths=list(args.paths),
+        pattern=args.pattern,
+        mark_expr=args.mark_expr,
+        workers=args.workers,
+        capture_output=args.capture_output,
+        enable_codeblocks=args.enable_codeblocks,
+    )
+    _print_report(report, verbose=args.verbose, ascii_mode=args.ascii)
+    return 0 if report.failed == 0 else 1
+
+
+def _print_report(report: RunReport, verbose: bool = False, ascii_mode: bool = False) -> None:
+    """Print test report with configurable output format.
+
+    Args:
+        report: The test run report
+        verbose: If True, show hierarchical verbose output (vitest-style)
+        ascii_mode: If True, use ASCII characters instead of Unicode symbols
+    """
+    if verbose:
+        _print_verbose_report(report, ascii_mode)
+    else:
+        _print_default_report(report, ascii_mode)
+
+    # Print summary line with colors
+    passed_str = (
+        f"{Colors.green}{report.passed} passed{Colors.reset}"
+        if report.passed > 0
+        else f"{report.passed} passed"
+    )
+    failed_str = (
+        f"{Colors.red}{report.failed} failed{Colors.reset}"
+        if report.failed > 0
+        else f"{report.failed} failed"
+    )
+    skipped_str = (
+        f"{Colors.yellow}{report.skipped} skipped{Colors.reset}"
+        if report.skipped > 0
+        else f"{report.skipped} skipped"
+    )
+
+    summary = (
+        f"\n{Colors.bold}{report.total} tests:{Colors.reset} "
+        f"{passed_str}, "
+        f"{failed_str}, "
+        f"{skipped_str} in {Colors.dim}{report.duration:.3f}s{Colors.reset}"
+    )
+    print(summary)
+
+
+def _print_default_report(report: RunReport, ascii_mode: bool) -> None:
+    """Print pytest-style progress indicators followed by failure details."""
+    # Define symbols
+    if ascii_mode:
+        # pytest-style: . (pass), F (fail), s (skip)
+        pass_symbol = "."
+        fail_symbol = "F"
+        skip_symbol = "s"
+    else:
+        # Unicode symbols (no spaces, with colors)
+        pass_symbol = f"{Colors.green}✓{Colors.reset}"
+        fail_symbol = f"{Colors.red}✗{Colors.reset}"
+        skip_symbol = f"{Colors.yellow}⊘{Colors.reset}"
+
+    # Print progress indicators
+    for result in report.results:
+        if result.status == "passed":
+            print(pass_symbol, end="")
+        elif result.status == "failed":
+            print(fail_symbol, end="")
+        elif result.status == "skipped":
+            print(skip_symbol, end="")
+    print()  # Newline after progress indicators
+
+    # Print failure details
+    failures = [r for r in report.results if r.status == "failed"]
+    if failures:
+        print(f"\n{Colors.red}{'=' * 70}")
+        print(f"{Colors.bold}FAILURES{Colors.reset}")
+        print(f"{Colors.red}{'=' * 70}{Colors.reset}")
+        for result in failures:
+            print(
+                f"\n{Colors.bold}{result.name}{Colors.reset} ({Colors.cyan}{result.path}{Colors.reset})"
+            )
+            print(f"{Colors.red}{'-' * 70}{Colors.reset}")
+            if result.message:
+                print(result.message.rstrip())
+
+
+def _print_verbose_report(report: RunReport, ascii_mode: bool) -> None:
+    """Print vitest-style hierarchical output with nesting and timing."""
+    # Define symbols
+    if ascii_mode:
+        pass_symbol = "PASS"
+        fail_symbol = "FAIL"
+        skip_symbol = "SKIP"
+    else:
+        pass_symbol = f"{Colors.green}✓{Colors.reset}"
+        fail_symbol = f"{Colors.red}✗{Colors.reset}"
+        skip_symbol = f"{Colors.yellow}⊘{Colors.reset}"
+
+    # Group tests by file path and organize hierarchically
+    from collections import defaultdict
+
+    tests_by_file: dict[str, list[TestResult]] = defaultdict(list)
+    for result in report.results:
+        tests_by_file[result.path].append(result)
+
+    # Print hierarchical structure
+    for file_path in sorted(tests_by_file.keys()):
+        print(f"\n{Colors.bold}{file_path}{Colors.reset}")
+
+        # Group tests by class within this file
+        tests_by_class: dict[str | None, list[tuple[TestResult, str | None]]] = defaultdict(list)
+        for result in tests_by_file[file_path]:
+            # Parse test name to extract class if present
+            # Format can be: "test_name" or "ClassName.test_name" or "module::Class::test"
+            class_name: str | None
+            if "::" in result.name:
+                parts = result.name.split("::")
+                class_name = "::".join(parts[:-1]) if len(parts) > 1 else None
+            elif "." in result.name:
+                parts = result.name.split(".")
+                class_name = parts[0] if len(parts) > 1 else None
+            else:
+                class_name = None
+            tests_by_class[class_name].append((result, class_name))
+
+        # Print tests organized by class
+        for class_name in sorted(tests_by_class.keys(), key=lambda x: (x is None, x)):
+            # Print class name if present
+            if class_name:
+                print(f"  {Colors.cyan}{class_name}{Colors.reset}")
+
+            for result, _ in tests_by_class[class_name]:
+                # Get symbol based on status
+                if result.status == "passed":
+                    symbol = pass_symbol
+                elif result.status == "failed":
+                    symbol = fail_symbol
+                elif result.status == "skipped":
+                    symbol = skip_symbol
+                else:
+                    symbol = "?"
+
+                # Extract just the test method name
+                if "::" in result.name:
+                    display_name = result.name.split("::")[-1]
+                elif "." in result.name:
+                    display_name = result.name.split(".")[-1]
+                else:
+                    display_name = result.name
+
+                # Indent based on whether it's in a class
+                indent = "    " if class_name else "  "
+
+                # Print with symbol, name, and timing
+                duration_str = f"{Colors.dim}{result.duration * 1000:.0f}ms{Colors.reset}"
+                print(f"{indent}{symbol} {display_name} {duration_str}")
+
+                # Show error message for failures
+                if result.status == "failed" and result.message:
+                    error_lines = result.message.rstrip().split("\n")
+                    for line in error_lines:
+                        print(f"{indent}  {line}")

rustest/core.py

@@ -0,0 +1,38 @@
+"""High level Python API wrapping the Rust extension."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from . import rust
+from .reporting import RunReport
+
+
+def run(
+    *,
+    paths: Sequence[str],
+    pattern: str | None = None,
+    mark_expr: str | None = None,
+    workers: int | None = None,
+    capture_output: bool = True,
+    enable_codeblocks: bool = True,
+) -> RunReport:
+    """Execute tests and return a rich report.
+
+    Args:
+        paths: Files or directories to collect tests from
+        pattern: Substring to filter tests by (case insensitive)
+        mark_expr: Mark expression to filter tests (e.g., "slow", "not slow", "slow and integration")
+        workers: Number of worker slots to use (experimental)
+        capture_output: Whether to capture stdout/stderr during test execution
+        enable_codeblocks: Whether to enable code block tests from markdown files
+    """
+    raw_report = rust.run(
+        paths=list(paths),
+        pattern=pattern,
+        mark_expr=mark_expr,
+        workers=workers,
+        capture_output=capture_output,
+        enable_codeblocks=enable_codeblocks,
+    )
+    return RunReport.from_py(raw_report)

rustest/decorators.py

@@ -0,0 +1,423 @@
+"""User facing decorators mirroring the most common pytest helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable[..., object])
+
+# Valid fixture scopes
+VALID_SCOPES = frozenset(["function", "class", "module", "session"])
+
+
+def fixture(
+    func: F | None = None,
+    *,
+    scope: str = "function",
+) -> F | Callable[[F], F]:
+    """Mark a function as a fixture with a specific scope.
+
+    Args:
+        func: The function to decorate (when used without parentheses)
+        scope: The scope of the fixture. One of:
+            - "function": New instance for each test function (default)
+            - "class": Shared across all test methods in a class
+            - "module": Shared across all tests in a module
+            - "session": Shared across all tests in the session
+
+    Usage:
+        @fixture
+        def my_fixture():
+            return 42
+
+        @fixture(scope="module")
+        def shared_fixture():
+            return expensive_setup()
+    """
+    if scope not in VALID_SCOPES:
+        valid = ", ".join(sorted(VALID_SCOPES))
+        msg = f"Invalid fixture scope '{scope}'. Must be one of: {valid}"
+        raise ValueError(msg)
+
+    def decorator(f: F) -> F:
+        setattr(f, "__rustest_fixture__", True)
+        setattr(f, "__rustest_fixture_scope__", scope)
+        return f
+
+    # Support both @fixture and @fixture(scope="...")
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+def skip(reason: str | None = None) -> Callable[[F], F]:
+    """Skip a test or fixture."""
+
+    def decorator(func: F) -> F:
+        setattr(func, "__rustest_skip__", reason or "skipped via rustest.skip")
+        return func
+
+    return decorator
+
+
+def parametrize(
+    arg_names: str | Sequence[str],
+    values: Sequence[Sequence[object] | Mapping[str, object]],
+    *,
+    ids: Sequence[str] | None = None,
+) -> Callable[[F], F]:
+    """Parametrise a test function."""
+
+    normalized_names = _normalize_arg_names(arg_names)
+
+    def decorator(func: F) -> F:
+        cases = _build_cases(normalized_names, values, ids)
+        setattr(func, "__rustest_parametrization__", cases)
+        return func
+
+    return decorator
+
+
+def _normalize_arg_names(arg_names: str | Sequence[str]) -> tuple[str, ...]:
+    if isinstance(arg_names, str):
+        parts = [part.strip() for part in arg_names.split(",") if part.strip()]
+        if not parts:
+            msg = "parametrize() expected at least one argument name"
+            raise ValueError(msg)
+        return tuple(parts)
+    return tuple(arg_names)
+
+
+def _build_cases(
+    names: tuple[str, ...],
+    values: Sequence[Sequence[object] | Mapping[str, object]],
+    ids: Sequence[str] | None,
+) -> tuple[dict[str, object], ...]:
+    case_payloads: list[dict[str, object]] = []
+    if ids is not None and len(ids) != len(values):
+        msg = "ids must match the number of value sets"
+        raise ValueError(msg)
+
+    for index, case in enumerate(values):
+        # Mappings are only treated as parameter mappings when there are multiple parameters
+        # For single parameters, dicts/mappings are treated as values
+        if isinstance(case, Mapping) and len(names) > 1:
+            data = {name: case[name] for name in names}
+        elif isinstance(case, tuple) and len(case) == len(names):
+            # Tuples are unpacked to match parameter names (pytest convention)
+            # This handles both single and multiple parameters
+            data = {name: case[pos] for pos, name in enumerate(names)}
+        else:
+            # Everything else is treated as a single value
+            # This includes: primitives, lists (even if len==names), dicts (single param), objects
+            if len(names) == 1:
+                data = {names[0]: case}
+            else:
+                raise ValueError("Parametrized value does not match argument names")
+        case_id = ids[index] if ids is not None else f"case_{index}"
+        case_payloads.append({"id": case_id, "values": data})
+    return tuple(case_payloads)
+
+
+class MarkDecorator:
+    """A decorator for applying a mark to a test function."""
+
+    def __init__(self, name: str, args: tuple[Any, ...], kwargs: dict[str, Any]) -> None:
+        super().__init__()
+        self.name = name
+        self.args = args
+        self.kwargs = kwargs
+
+    def __call__(self, func: F) -> F:
+        """Apply this mark to the given function."""
+        # Get existing marks or create a new list
+        existing_marks: list[dict[str, Any]] = getattr(func, "__rustest_marks__", [])
+
+        # Add this mark to the list
+        mark_data = {
+            "name": self.name,
+            "args": self.args,
+            "kwargs": self.kwargs,
+        }
+        existing_marks.append(mark_data)
+
+        # Store the marks list on the function
+        setattr(func, "__rustest_marks__", existing_marks)
+        return func
+
+    def __repr__(self) -> str:
+        return f"Mark({self.name!r}, {self.args!r}, {self.kwargs!r})"
+
+
+class MarkGenerator:
+    """Namespace for dynamically creating marks like pytest.mark.
+
+    Usage:
+        @mark.slow
+        @mark.integration
+        @mark.timeout(seconds=30)
+
+    Standard marks:
+        @mark.skipif(condition, *, reason="...")
+        @mark.xfail(condition=None, *, reason=None, raises=None, run=True, strict=False)
+        @mark.usefixtures("fixture1", "fixture2")
+    """
+
+    def skipif(
+        self,
+        condition: bool | str,
+        *,
+        reason: str | None = None,
+    ) -> MarkDecorator:
+        """Skip test if condition is true.
+
+        Args:
+            condition: Boolean or string condition to evaluate
+            reason: Explanation for why the test is skipped
+
+        Usage:
+            @mark.skipif(sys.platform == "win32", reason="Not supported on Windows")
+            def test_unix_only():
+                pass
+        """
+        return MarkDecorator("skipif", (condition,), {"reason": reason})
+
+    def xfail(
+        self,
+        condition: bool | str | None = None,
+        *,
+        reason: str | None = None,
+        raises: type[BaseException] | tuple[type[BaseException], ...] | None = None,
+        run: bool = True,
+        strict: bool = False,
+    ) -> MarkDecorator:
+        """Mark test as expected to fail.
+
+        Args:
+            condition: Optional condition - if False, mark is ignored
+            reason: Explanation for why the test is expected to fail
+            raises: Expected exception type(s)
+            run: Whether to run the test (False means skip it)
+            strict: If True, passing test will fail the suite
+
+        Usage:
+            @mark.xfail(reason="Known bug in backend")
+            def test_known_bug():
+                assert False
+
+            @mark.xfail(sys.platform == "win32", reason="Not implemented on Windows")
+            def test_feature():
+                pass
+        """
+        kwargs = {
+            "reason": reason,
+            "raises": raises,
+            "run": run,
+            "strict": strict,
+        }
+        args = () if condition is None else (condition,)
+        return MarkDecorator("xfail", args, kwargs)
+
+    def usefixtures(self, *names: str) -> MarkDecorator:
+        """Use fixtures without explicitly requesting them as parameters.
+
+        Args:
+            *names: Names of fixtures to use
+
+        Usage:
+            @mark.usefixtures("setup_db", "cleanup")
+            def test_with_fixtures():
+                pass
+        """
+        return MarkDecorator("usefixtures", names, {})
+
+    def __getattr__(self, name: str) -> Any:
+        """Create a mark decorator for the given name."""
+        # Return a callable that can be used as @mark.name or @mark.name(args)
+        return self._create_mark(name)
+
+    def _create_mark(self, name: str) -> Any:
+        """Create a MarkDecorator that can be called with or without arguments."""
+
+        class _MarkDecoratorFactory:
+            """Factory that allows @mark.name or @mark.name(args)."""
+
+            def __init__(self, mark_name: str) -> None:
+                super().__init__()
+                self.mark_name = mark_name
+
+            def __call__(self, *args: Any, **kwargs: Any) -> Any:
+                # If called with a single argument that's a function, it's @mark.name
+                if (
+                    len(args) == 1
+                    and not kwargs
+                    and callable(args[0])
+                    and hasattr(args[0], "__name__")
+                ):
+                    decorator = MarkDecorator(self.mark_name, (), {})
+                    return decorator(args[0])
+                # Otherwise it's @mark.name(args) - return a decorator
+                return MarkDecorator(self.mark_name, args, kwargs)
+
+        return _MarkDecoratorFactory(name)
+
+
+# Create a singleton instance
+mark = MarkGenerator()
+
+
+class ExceptionInfo:
+    """Information about an exception caught by raises().
+
+    Attributes:
+        type: The exception type
+        value: The exception instance
+        traceback: The exception traceback
+    """
+
+    def __init__(
+        self, exc_type: type[BaseException], exc_value: BaseException, exc_tb: Any
+    ) -> None:
+        super().__init__()
+        self.type = exc_type
+        self.value = exc_value
+        self.traceback = exc_tb
+
+    def __repr__(self) -> str:
+        return f"<ExceptionInfo {self.type.__name__}({self.value!r})>"
+
+
+class RaisesContext:
+    """Context manager for asserting that code raises a specific exception.
+
+    This mimics pytest.raises() behavior, supporting:
+    - Single or tuple of exception types
+    - Optional regex matching of exception messages
+    - Access to caught exception information
+
+    Usage:
+        with raises(ValueError):
+            int("not a number")
+
+        with raises(ValueError, match="invalid literal"):
+            int("not a number")
+
+        with raises((ValueError, TypeError)):
+            some_function()
+
+        # Access the caught exception
+        with raises(ValueError) as exc_info:
+            raise ValueError("oops")
+        assert "oops" in str(exc_info.value)
+    """
+
+    def __init__(
+        self,
+        exc_type: type[BaseException] | tuple[type[BaseException], ...],
+        *,
+        match: str | None = None,
+    ) -> None:
+        super().__init__()
+        self.exc_type = exc_type
+        self.match_pattern = match
+        self.excinfo: ExceptionInfo | None = None
+
+    def __enter__(self) -> RaisesContext:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> bool:
+        # No exception was raised
+        if exc_type is None:
+            exc_name = self._format_exc_name()
+            msg = f"DID NOT RAISE {exc_name}"
+            raise AssertionError(msg)
+
+        # At this point, we know an exception was raised, so exc_val cannot be None
+        assert exc_val is not None, "exc_val must not be None when exc_type is not None"
+
+        # Check if the exception type matches
+        if not issubclass(exc_type, self.exc_type):
+            # Unexpected exception type - let it propagate
+            return False
+
+        # Store the exception information
+        self.excinfo = ExceptionInfo(exc_type, exc_val, exc_tb)
+
+        # Check if the message matches the pattern (if provided)
+        if self.match_pattern is not None:
+            import re
+
+            exc_message = str(exc_val)
+            if not re.search(self.match_pattern, exc_message):
+                msg = (
+                    f"Pattern {self.match_pattern!r} does not match "
+                    f"{exc_message!r}. Exception: {exc_type.__name__}: {exc_message}"
+                )
+                raise AssertionError(msg)
+
+        # Suppress the exception (it was expected)
+        return True
+
+    def _format_exc_name(self) -> str:
+        """Format the expected exception name(s) for error messages."""
+        if isinstance(self.exc_type, tuple):
+            names = " or ".join(exc.__name__ for exc in self.exc_type)
+            return names
+        return self.exc_type.__name__
+
+    @property
+    def value(self) -> BaseException:
+        """Access the caught exception value."""
+        if self.excinfo is None:
+            msg = "No exception was caught"
+            raise AttributeError(msg)
+        return self.excinfo.value
+
+    @property
+    def type(self) -> type[BaseException]:
+        """Access the caught exception type."""
+        if self.excinfo is None:
+            msg = "No exception was caught"
+            raise AttributeError(msg)
+        return self.excinfo.type
+
+
+def raises(
+    exc_type: type[BaseException] | tuple[type[BaseException], ...],
+    *,
+    match: str | None = None,
+) -> RaisesContext:
+    """Assert that code raises a specific exception.
+
+    Args:
+        exc_type: The expected exception type(s). Can be a single type or tuple of types.
+        match: Optional regex pattern to match against the exception message.
+
+    Returns:
+        A context manager that catches and validates the exception.
+
+    Raises:
+        AssertionError: If no exception is raised, or if the message doesn't match.
+
+    Usage:
+        with raises(ValueError):
+            int("not a number")
+
+        with raises(ValueError, match="invalid literal"):
+            int("not a number")
+
+        with raises((ValueError, TypeError)):
+            some_function()
+
+        # Access the caught exception
+        with raises(ValueError) as exc_info:
+            raise ValueError("oops")
+        assert "oops" in str(exc_info.value)
+    """
+    return RaisesContext(exc_type, match=match)

rustest/reporting.py

@@ -0,0 +1,63 @@
+"""Utilities for converting raw results from the Rust layer."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from . import rust
+
+
+@dataclass(slots=True)
+class TestResult:
+    """Structured view of a single test outcome."""
+
+    __test__ = False  # Tell pytest this is not a test class
+
+    name: str
+    path: str
+    status: str
+    duration: float
+    message: str | None
+    stdout: str | None
+    stderr: str | None
+
+    @classmethod
+    def from_py(cls, result: rust.PyTestResult) -> "TestResult":
+        return cls(
+            name=result.name,
+            path=result.path,
+            status=result.status,
+            duration=result.duration,
+            message=result.message,
+            stdout=result.stdout,
+            stderr=result.stderr,
+        )
+
+
+@dataclass(slots=True)
+class RunReport:
+    """Aggregate statistics for an entire test session."""
+
+    total: int
+    passed: int
+    failed: int
+    skipped: int
+    duration: float
+    results: tuple[TestResult, ...]
+
+    @classmethod
+    def from_py(cls, report: rust.PyRunReport) -> "RunReport":
+        return cls(
+            total=report.total,
+            passed=report.passed,
+            failed=report.failed,
+            skipped=report.skipped,
+            duration=report.duration,
+            results=tuple(TestResult.from_py(result) for result in report.results),
+        )
+
+    def iter_status(self, status: str) -> Iterable[TestResult]:
+        """Yield results with the requested status."""
+
+        return (result for result in self.results if result.status == status)

rustest/rust.py

@@ -0,0 +1,23 @@
+"""Fallback stub for the compiled rustest extension.
+
+This module is packaged with the Python distribution so unit tests can import the
+package without building the Rust extension. Individual tests are expected to
+monkeypatch the functions they exercise.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+
+def run(
+    _paths: Sequence[str],
+    _pattern: str | None,
+    _workers: int | None,
+    _capture_output: bool,
+) -> Any:
+    """Placeholder implementation that mirrors the extension signature."""
+
+    raise NotImplementedError(
+        "The rustest native extension is unavailable. Tests must patch rustest.rust.run."
+    )

rustest/rust.pyi

@@ -0,0 +1,37 @@
+"""Type stubs for the rustest Rust extension module."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+class PyTestResult:
+    """Individual test result from the Rust extension."""
+
+    name: str
+    path: str
+    status: str
+    duration: float
+    message: str | None
+    stdout: str | None
+    stderr: str | None
+
+class PyRunReport:
+    """Test run report from the Rust extension."""
+
+    total: int
+    passed: int
+    failed: int
+    skipped: int
+    duration: float
+    results: list[PyTestResult]
+
+def run(
+    paths: Sequence[str],
+    pattern: str | None,
+    mark_expr: str | None,
+    workers: int | None,
+    capture_output: bool,
+    enable_codeblocks: bool,
+) -> PyRunReport:
+    """Execute tests and return a report."""
+    ...

rustest-0.5.0.dist-info/METADATA

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: rustest
+Version: 0.5.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: typing-extensions>=4.15
+Requires-Dist: basedpyright>=1.19 ; extra == 'dev'
+Requires-Dist: maturin>=1.4,<2 ; extra == 'dev'
+Requires-Dist: poethepoet>=0.22 ; extra == 'dev'
+Requires-Dist: pre-commit>=3.5 ; extra == 'dev'
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.1.9 ; extra == 'dev'
+Requires-Dist: mkdocs>=1.5.0 ; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5.0 ; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.24.0 ; extra == 'docs'
+Requires-Dist: mkdocs-autorefs>=0.5.0 ; extra == 'docs'
+Provides-Extra: dev
+Provides-Extra: docs
+License-File: LICENSE
+Summary: Rust powered pytest-compatible runner
+Author: rustest contributors
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/Apex-Engineers-Inc/rustest
+Project-URL: Repository, https://github.com/Apex-Engineers-Inc/rustest
+Project-URL: Documentation, https://apex-engineers-inc.github.io/rustest
+
+# rustest
+
+Rustest (pronounced like Russ-Test) is a Rust-powered test runner that aims to provide the most common pytest ergonomics with a focus on raw performance. Get **~2x faster** test execution with familiar syntax and minimal setup.
+
+📚 **[Full Documentation](https://apex-engineers-inc.github.io/rustest)** | [Getting Started](https://apex-engineers-inc.github.io/rustest/getting-started/quickstart/) | [User Guide](https://apex-engineers-inc.github.io/rustest/guide/writing-tests/) | [API Reference](https://apex-engineers-inc.github.io/rustest/api/overview/)
+
+## Why rustest?
+
+- 🚀 **About 2x faster** than pytest on the rustest integration test suite
+- ✅ Familiar `@fixture`, `@parametrize`, `@skip`, and `@mark` decorators
+- 🔍 Automatic test discovery (`test_*.py` and `*_test.py` files)
+- 📝 **Built-in markdown code block testing** (like pytest-codeblocks, but faster)
+- 🎯 Simple, clean API—if you know pytest, you already know rustest
+- 🧮 Built-in `approx()` helper for tolerant numeric comparisons
+- 🪤 `raises()` context manager for precise exception assertions
+- 📦 Easy installation with pip or uv
+- ⚡ Low-overhead execution keeps small suites feeling instant
+
+## Performance
+
+Rustest is designed for speed. Our latest benchmarks on the rustest integration suite (~200 tests) show a consistent **2.1x wall-clock speedup** over pytest:
+
+| Test Runner | Wall Clock | Speedup | Command |
+|-------------|------------|---------|---------|
+| pytest      | 1.33–1.59s | 1.0x (baseline) | `pytest tests/ examples/tests/ -q` |
+| rustest     | 0.69–0.70s | **~2.1x faster** | `python -m rustest tests/ examples/tests/` |
+
+### Large Parametrized Stress Test
+
+With **10,000 parametrized invocations**:
+
+| Test Runner | Avg. Wall Clock | Speedup | Command |
+|-------------|-----------------|---------|---------|
+| pytest      | 9.72s           | 1.0x    | `pytest benchmarks/test_large_parametrize.py -q` |
+| rustest     | 0.41s           | **~24x faster** | `python -m rustest benchmarks/test_large_parametrize.py` |
+
+**[📊 View Detailed Performance Analysis →](https://apex-engineers-inc.github.io/rustest/advanced/performance/)**
+
+## Installation
+
+Rustest supports Python **3.10 through 3.14**.
+
+```bash
+# Using pip
+pip install rustest
+
+# Using uv
+uv add rustest
+```
+
+**[📖 Installation Guide →](https://apex-engineers-inc.github.io/rustest/getting-started/installation/)**
+
+## Quick Start
+
+### 1. Write Your Tests
+
+Create a file `test_math.py`:
+
+```python
+from rustest import fixture, parametrize, mark, approx, raises
+
+@fixture
+def numbers() -> list[int]:
+    return [1, 2, 3, 4, 5]
+
+def test_sum(numbers: list[int]) -> None:
+    assert sum(numbers) == approx(15)
+
+@parametrize("value,expected", [(2, 4), (3, 9), (4, 16)])
+def test_square(value: int, expected: int) -> None:
+    assert value ** 2 == expected
+
+@mark.slow
+def test_expensive_operation() -> None:
+    result = sum(range(1000000))
+    assert result > 0
+
+def test_division_by_zero() -> None:
+    with raises(ZeroDivisionError, match="division by zero"):
+        1 / 0
+```
+
+### 2. Run Your Tests
+
+```bash
+# Run all tests
+rustest
+
+# Run specific tests
+rustest tests/
+
+# Filter by test name pattern
+rustest -k "test_sum"
+
+# Filter by marks
+rustest -m "slow"                    # Run only slow tests
+rustest -m "not slow"                # Skip slow tests
+rustest -m "slow and integration"    # Run tests with both marks
+
+# Show output during execution
+rustest --no-capture
+```
+
+**[📖 Full Quick Start Guide →](https://apex-engineers-inc.github.io/rustest/getting-started/quickstart/)**
+
+## Documentation
+
+**[📚 Full Documentation](https://apex-engineers-inc.github.io/rustest)**
+
+### Getting Started
+- [Installation](https://apex-engineers-inc.github.io/rustest/getting-started/installation/)
+- [Quick Start](https://apex-engineers-inc.github.io/rustest/getting-started/quickstart/)
+
+### User Guide
+- [Writing Tests](https://apex-engineers-inc.github.io/rustest/guide/writing-tests/)
+- [Fixtures](https://apex-engineers-inc.github.io/rustest/guide/fixtures/)
+- [Parametrization](https://apex-engineers-inc.github.io/rustest/guide/parametrization/)
+- [Marks & Skipping](https://apex-engineers-inc.github.io/rustest/guide/marks/)
+- [Test Classes](https://apex-engineers-inc.github.io/rustest/guide/test-classes/)
+- [Assertion Helpers](https://apex-engineers-inc.github.io/rustest/guide/assertions/)
+- [Markdown Testing](https://apex-engineers-inc.github.io/rustest/guide/markdown-testing/)
+- [CLI Usage](https://apex-engineers-inc.github.io/rustest/guide/cli/)
+- [Python API](https://apex-engineers-inc.github.io/rustest/guide/python-api/)
+
+### API Reference
+- [API Overview](https://apex-engineers-inc.github.io/rustest/api/overview/)
+- [Decorators](https://apex-engineers-inc.github.io/rustest/api/decorators/)
+- [Test Execution](https://apex-engineers-inc.github.io/rustest/api/core/)
+- [Reporting](https://apex-engineers-inc.github.io/rustest/api/reporting/)
+- [Assertion Utilities](https://apex-engineers-inc.github.io/rustest/api/approx/)
+
+### Advanced Topics
+- [Performance](https://apex-engineers-inc.github.io/rustest/advanced/performance/)
+- [Comparison with pytest](https://apex-engineers-inc.github.io/rustest/advanced/comparison/)
+- [Development Guide](https://apex-engineers-inc.github.io/rustest/advanced/development/)
+
+## Feature Comparison with pytest
+
+Rustest implements the 20% of pytest features that cover 80% of use cases, with a focus on raw speed and simplicity.
+
+**[📋 View Full Feature Comparison →](https://apex-engineers-inc.github.io/rustest/advanced/comparison/)**
+
+✅ **Supported:** Fixtures, parametrization, marks, test classes, conftest.py, markdown testing
+🚧 **Planned:** Parallel execution, mark filtering, JUnit XML output
+❌ **Not Planned:** Plugins, hooks, custom collectors (keeps rustest simple)
+
+## Contributing
+
+We welcome contributions! See the [Development Guide](https://apex-engineers-inc.github.io/rustest/advanced/development/) for setup instructions.
+
+Quick reference:
+
+```bash
+# Setup
+git clone https://github.com/Apex-Engineers-Inc/rustest.git
+cd rustest
+uv sync --all-extras
+uv run maturin develop
+
+# Run tests
+uv run poe pytests  # Python tests
+cargo test          # Rust tests
+
+# Format and lint
+uv run pre-commit install  # One-time setup
+git commit -m "message"    # Pre-commit hooks run automatically
+```
+
+## License
+
+rustest is distributed under the terms of the MIT license. See [LICENSE](LICENSE).
+

rustest-0.5.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+rustest-0.5.0.dist-info/METADATA,sha256=SkRHcV4Pv7s5Hfo9ywd77-b3wuJtgbPvtrYY6LQoaYk,8225
+rustest-0.5.0.dist-info/WHEEL,sha256=n8ZdhGDUio-M1d1jdBhS3kD6MKEN1SRxo8BOjWwZdsg,96
+rustest-0.5.0.dist-info/entry_points.txt,sha256=7fUa3LO8vudQ4dKG1sTRaDnxcMdBSZsWs9EyuxFQ7Lk,48
+rustest-0.5.0.dist-info/licenses/LICENSE,sha256=Ci0bB0T1ZGkqIV237Zp_Bv8LIJJ0Vxwc-AhLhgDgAoQ,1096
+rustest/__init__.py,sha256=LL9UloOClzeNO6A-iMkEFtHDrBTAhRLko3sXy55H0QA,542
+rustest/__main__.py,sha256=yMhaWvxGAV46BYY8fB6GoRy9oh8Z8YrS9wlZI3LmoyY,188
+rustest/approx.py,sha256=sGaH15n3vSSv84dmR_QAIDV-xwaUrX-MqwpWIp5ihjk,5904
+rustest/cli.py,sha256=Y7I3sLMA7icsHFLdcGJMy0LElEcoqzrVrTkedE_vGTs,9474
+rustest/core.py,sha256=2_kav-3XPhrtXnayQBDSc_tCaaaEj07rFHq5ln4Em8Q,1227
+rustest/decorators.py,sha256=mCiqNJXYpbQMCMaVEdeiebN9KWLvgtRmqZ6nbUXpm6E,14138
+rustest/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rustest/reporting.py,sha256=g4jdlwjFoKF_fWA_sKfeDwmhDeHxPJQUqypa_E2XQlc,1686
+rustest/rust.cp312-win_amd64.pyd,sha256=RFiwEJBXWgLvajST9qNaP7RV5QbL7L6BWIMPAPgOAYQ,1341440
+rustest/rust.py,sha256=N_1C-uXRiC2qkV7ecKVcb51-XXyfhYNepd5zs-RIYOo,682
+rustest/rust.pyi,sha256=D2PL2GamLpcwdBDZxFeWC1ZgJ01CkvWycU62LnVTMD0,799
+rustest-0.5.0.dist-info/RECORD,,

rustest-0.5.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.9.6)
+Root-Is-Purelib: false
+Tag: cp312-cp312-win_amd64

rustest-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rustest=rustest.__main__:main

rustest-0.5.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Apex Engineers Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.