pyforge-test 0.1.0__py3-none-any.whl

pyforge_test/__init__.py

@@ -0,0 +1,23 @@
+"""PyForge testing framework.
+
+A lightweight unit testing framework with simple decorator-based tests.
+"""
+
+from .core.collector import (
+    BUILTIN_MARKERS,
+    test,
+    test_marker,
+    test_parameterized,
+    test_skip,
+    test_skipif,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "BUILTIN_MARKERS",
+    "test",
+    "test_marker",
+    "test_parameterized",
+    "test_skip",
+    "test_skipif",
+]

pyforge_test/__main__.py

@@ -0,0 +1,8 @@
+"""Enable running pyforge_test as a module: python -m pyforge_test."""
+
+import sys
+
+from .core.main import main
+
+if __name__ == "__main__":
+    sys.exit(main())

pyforge_test/core/__init__.py

@@ -0,0 +1,8 @@
+"""PyForge core testing components."""
+
+from .collector import test, test_parameterized, test_skip, test_skipif
+from .registry import TESTS
+from .reporter import report
+from .runner import execute
+
+__all__ = ["TESTS", "execute", "report", "test", "test_parameterized", "test_skip", "test_skipif"]

pyforge_test/core/collector.py

@@ -0,0 +1,253 @@
+from collections.abc import Callable
+from typing import Any
+
+from .registry import TESTS
+
+
+# The test function is a decorator that collects test functions
+# and adds them to the TESTS list.
+def test(function: Callable[..., None]) -> Callable[..., None]:
+    """Collects the test functions and adds them to the TESTS list.
+
+    Args:
+        function (Callable[..., None]): The test function to be collected.
+
+    Returns:
+        Callable[..., None]: The original test function, unmodified.
+    """
+    try:
+        # check if the function is already in the TESTS list to avoid duplicates
+        if any(test_dict["function"] == function for test_dict in TESTS):
+            raise ValueError(f"Test function '{function.__name__}' is already collected.")
+        # check if the function name starts with "test_"
+        if not function.__name__.startswith("test_"):
+            raise ValueError(f"Test function '{function.__name__}' must start with 'test_'.")
+        # check if the function is valid or not (should be callable and should not have parameters)
+        if not callable(function):
+            raise ValueError(f"Test function '{function.__name__}' must be callable.")
+        elif function.__code__.co_argcount > 0:
+            raise ValueError(f"Test function '{function.__name__}' must not have parameters.")
+        # Add the function to TESTS list with the file name and line number for better debugging
+        TESTS.append(
+            {
+                "function": function,
+                "filename": function.__code__.co_filename,
+                "line_number": function.__code__.co_firstlineno,
+                "skip_info": None,
+                "marker": None,
+            }
+        )
+        return function
+    except Exception as e:
+        raise RuntimeError(
+            f"An error occurred while collecting test function '{function.__name__}': {e}"
+        ) from e
+
+
+# test_cases will be a list of tuples, where each tuple contains expression and expected result.
+def test_parameterized(
+    test_cases: list[tuple[Any, ...]],
+) -> Callable[[Callable[..., None]], Callable[..., None]]:
+    """A decorator to parameterize test functions with multiple test cases.
+
+    Args:
+        test_cases (list[tuple[Any, ...]]): A list of tuples, where each tuple
+            contains the parameters to be passed to the test function.
+
+    Returns:
+        Callable[[Callable[..., None]], Callable[..., None]]:
+            A decorator that can be applied to a test function.
+    """
+
+    def decorator(function: Callable[..., None]) -> Callable[..., None]:
+        """The actual decorator that wraps the test function.
+
+        Args:
+            function (Callable[..., None]): The test function to be decorated.
+
+        Returns:
+            Callable[..., None]: The wrapped test function that will run with all test cases.
+        """
+        try:
+            # Check if the function is already in the TESTS list to avoid duplicates
+            if any(test_dict["function"] == function for test_dict in TESTS):
+                raise ValueError(f"Test function '{function.__name__}' is already collected.")
+            # Check if the function name starts with "test_"
+            if not function.__name__.startswith("test_"):
+                raise ValueError(f"Test function '{function.__name__}' must start with 'test_'.")
+            # Check if the function is valid or not (should be callable)
+            if not callable(function):
+                raise ValueError(f"Test function '{function.__name__}' must be callable.")
+            # Add the parameterized test cases to TESTS list with the file name
+            # and line number for better debugging
+            for case_index, case in enumerate(test_cases):
+
+                def make_test(c: tuple[Any, ...] = case) -> None:
+                    function(*c)
+
+                make_test.__name__ = f"{function.__name__}_{case_index}"
+
+                TESTS.append(
+                    {
+                        "function": make_test,
+                        "filename": function.__code__.co_filename,
+                        "line_number": function.__code__.co_firstlineno,
+                        "skip_info": None,
+                        "marker": None,
+                    }
+                )
+            return function
+        except Exception as e:
+            raise RuntimeError(
+                f"An error occurred while collecting parameterized test function "
+                f"'{function.__name__}': {e}"
+            ) from e
+
+    return decorator
+
+
+# The test_skipif function is a decorator that allows skipping a test function based on a condition.
+def test_skipif(
+    condition: bool, reason: str
+) -> Callable[[Callable[..., None]], Callable[..., None]]:
+    """A decorator to skip a test function if a certain condition is met.
+
+    Args:
+        condition (bool): The condition that determines whether the test should be skipped.
+        reason (str): The reason for skipping the test, which will be displayed in the report.
+
+    Returns:
+        Callable[[Callable[..., None]], Callable[..., None]]:
+            A decorator that can be applied to a test function.
+    """
+
+    def decorator(function: Callable[..., None]) -> Callable[..., None]:
+        """The actual decorator that wraps the test function.
+
+        Args:
+            function (Callable[..., None]): The test function to be decorated.
+
+        Returns:
+            Callable[..., None]: The wrapped test function that will
+            be skipped if the condition is met.
+        """
+        try:
+            # Check if the function is already in the TESTS list to avoid duplicates
+            if any(test_dict["function"] == function for test_dict in TESTS):
+                raise ValueError(f"Test function '{function.__name__}' is already collected.")
+            # Check if the function name starts with "test_"
+            if not function.__name__.startswith("test_"):
+                raise ValueError(f"Test function '{function.__name__}' must start with 'test_'.")
+            # Check if the function is valid or not (should be callable)
+            if not callable(function):
+                raise ValueError(f"Test function '{function.__name__}' must be callable.")
+            # Add the skip information to TESTS list with the file name
+            # and line number for better debugging
+            TESTS.append(
+                {
+                    "function": function,
+                    "filename": function.__code__.co_filename,
+                    "line_number": function.__code__.co_firstlineno,
+                    "skip_info": {"skip": condition, "reason": reason},
+                    "marker": None,
+                }
+            )
+            return function
+        except Exception as e:
+            raise RuntimeError(
+                f"An error occurred while collecting skipif test function "
+                f"'{function.__name__}': {e}"
+            ) from e
+
+    return decorator
+
+
+# The test_skip function is a decorator that allows skipping a test function unconditionally.
+def test_skip(reason: str) -> Callable[[Callable[..., None]], Callable[..., None]]:
+    """A decorator to skip a test function unconditionally.
+
+    Args:
+        reason (str): The reason for skipping the test, which will be displayed in the report.
+
+    Returns:
+        Callable[[Callable[..., None]], Callable[..., None]]:
+            A decorator that can be applied to a test function.
+    """
+
+    def decorator(function: Callable[..., None]) -> Callable[..., None]:
+        """The actual decorator that wraps the test function.
+
+        Args:
+            function (Callable[..., None]): The test function to be decorated.
+
+        Returns:
+            Callable[..., None]: The wrapped test function that will be skipped unconditionally.
+        """
+        return test_skipif(True, reason)(function)
+
+    return decorator
+
+
+# Built-in markers
+BUILTIN_MARKERS = {
+    "slow": "Mark test as slow-running",
+    "integration": "Mark test as an integration test (requires external resources)",
+}
+
+
+# The test_marker function is a decorator that allows marking a test function with a custom marker.
+def test_marker(marker: str) -> Callable[[Callable[..., None]], Callable[..., None]]:
+    """A decorator to apply a built-in marker to a test function.
+
+    Usage:
+        @test_marker("integration")
+        @test
+        def test_database_connection() -> None:
+            pass
+
+    Args:
+        marker (str): The marker to be applied to the test function.
+
+    Returns:
+        Callable[[Callable[..., None]], Callable[..., None]]:
+            A decorator that can be applied to a test function.
+
+    Raises:
+        ValueError: If the marker is not a built-in marker.
+    """
+
+    def decorator(function: Callable[..., None]) -> Callable[..., None]:
+        """The actual decorator that applies the marker to the test function.
+
+        Args:
+            function (Callable[..., None]): The test function to be marked.
+
+        Returns:
+            Callable[..., None]: The test function with the applied marker.
+
+        Raises:
+            ValueError: If the test function is not collected before applying the marker.
+            RuntimeError: If an error occurs while applying the marker.
+        """
+        try:
+            # Check if the marker is a built-in marker
+            if marker not in BUILTIN_MARKERS:
+                raise ValueError(f"Marker '{marker}' is not a built-in marker.")
+            # Check if the marker is applied to collected test function
+            if not any(test_dict["function"] == function for test_dict in TESTS):
+                raise ValueError(
+                    f"Test function '{function.__name__}' must be collected before applying marker."
+                )
+            # Update the marker information in TESTS list
+            for test_dict in TESTS:
+                if test_dict["function"] == function:
+                    test_dict["marker"] = marker
+                    break
+            return function
+        except Exception as e:
+            raise RuntimeError(
+                f"An error occurred while applying marker '{marker}' to test function "
+                f"'{function.__name__}': {e}"
+            ) from e
+
+    return decorator

pyforge_test/core/main.py

@@ -0,0 +1,227 @@
+"""PyForge test runner entry point.
+
+Executes collected tests and displays results.
+Discovers and loads all test files from the tests directory.
+"""
+
+import argparse
+import contextlib
+import importlib.util
+import sys
+import traceback
+from pathlib import Path
+
+from .reporter import VERBOSITY_NORMAL, VERBOSITY_QUIET, VERBOSITY_VERBOSE, report
+from .runner import execute
+
+# Set up path for tests package import
+_pyforge_root: Path = Path(__file__).parent.parent.parent.parent  # project root
+sys.path.insert(0, str(_pyforge_root))
+with contextlib.suppress(ImportError):
+    import tests  # pyright: ignore[reportUnusedImport] # noqa: F401
+
+
+def _find_project_root() -> Path:
+    """Find the project root directory.
+
+    First checks current working directory, then the directory where
+    pyforge is installed.
+
+    Returns:
+        Path: The project root directory containing tests/ subdirectory.
+
+    Raises:
+        FileNotFoundError: If no project structure is found.
+    """
+    # Check current working directory first (for user projects)
+    cwd: Path = Path.cwd()
+    if (cwd / "tests").exists() and (cwd / "tests").is_dir():
+        return cwd
+
+    # Check one level up from CWD
+    parent: Path = cwd.parent
+    if (parent / "tests").exists() and (parent / "tests").is_dir():
+        return parent
+
+    # Fall back to pyforge installation directory
+    pyforge_root: Path = Path(__file__).parent.parent.parent.parent
+    if (pyforge_root / "tests").exists() and (pyforge_root / "tests").is_dir():
+        return pyforge_root
+
+    raise FileNotFoundError(
+        "No project structure found. Expected 'tests/' directory in "
+        f"current directory ({cwd}), parent directory ({parent}), "
+        f"or pyforge installation ({pyforge_root})"
+    )
+
+
+def _setup_src_path(project_root: Path) -> None:
+    """Add src directory to sys.path if it exists.
+
+    Args:
+        project_root: The root directory of the project.
+    """
+    src_dir: Path = project_root / "src"
+    if src_dir.exists() and src_dir.is_dir():
+        src_path: str = str(src_dir)
+        if src_path not in sys.path:
+            sys.path.insert(0, src_path)
+
+
+def discover_and_load_tests(project_root: Path) -> int:
+    """Discover and load all test modules from the tests directory.
+
+    Args:
+        project_root: The root directory containing the tests/ folder.
+
+    Returns:
+        int: Number of test modules successfully loaded.
+
+    Raises:
+        FileNotFoundError: If the tests directory does not exist.
+    """
+    tests_dir: Path = project_root / "tests"
+
+    if not tests_dir.exists() or not tests_dir.is_dir():
+        raise FileNotFoundError(f"Tests directory '{tests_dir}' does not exist.")
+
+    # Find all test files (anything matching test*.py pattern)
+    test_files: list[Path] = sorted(tests_dir.glob("test*.py"))
+
+    if not test_files:
+        print(f"No test modules found in '{tests_dir}'")
+        return 0
+
+    loaded_count: int = 0
+    print(f"Discovering test modules in '{tests_dir}'...")
+
+    for test_file in test_files:
+        try:
+            # Load the module using importlib
+            spec = importlib.util.spec_from_file_location(test_file.stem, test_file)
+            if spec is None or spec.loader is None:
+                raise ImportError(f"Could not create module spec for {test_file.name}")
+
+            module = importlib.util.module_from_spec(spec)
+            sys.modules[test_file.stem] = module
+            spec.loader.exec_module(module)
+
+            # Verify that the module has a __name__ attribute (it should)
+            if not hasattr(module, "__name__"):
+                raise ImportError(f"Module {test_file.name} does not have a __name__ attribute")
+
+            print(f"Loaded: {test_file.name}")
+            loaded_count += 1
+
+        except Exception as e:
+            print(f"✗ Error loading {test_file.name}: {type(e).__name__}: {e}")
+
+    return loaded_count
+
+
+def main() -> int:
+    """Main entry point for PyForge test runner.
+
+    Supports verbosity levels, fail-fast option, and selective running:
+    - Default: Normal output
+    - -q/--quiet: Only show summary and failures
+    - -v/--verbose: Show detailed info with tracebacks
+    - --fail-fast: Stop on first failure
+    - -k: Substring filtering on test names
+    - FILES: File paths to run tests from (positional arguments)
+
+    Returns:
+        int: Exit code (0 for success, 1 for failure).
+    """
+    # Parse CLI arguments
+    parser = argparse.ArgumentParser(
+        description="PyForge - Lightweight Python testing framework",
+        epilog="Examples:\n"
+        "  pyforge                    # Run all tests\n"
+        "  pyforge -k test_basic      # Run tests with 'test_basic' in name\n"
+        "  pyforge test_name.py       # Run tests from specific file(s)\n"
+        "  pyforge -k basic -v        # Verbose output for matching tests",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="Quiet mode: only show summary and failures",
+    )
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="store_true",
+        help="Verbose mode: show detailed info with tracebacks",
+    )
+    parser.add_argument(
+        "--fail-fast",
+        action="store_true",
+        help="Stop execution at first failure",
+    )
+    parser.add_argument(
+        "-k",
+        dest="name_pattern",
+        default=None,
+        help="Substring filter: run tests with this string in their name",
+    )
+    parser.add_argument(
+        "files",
+        nargs="*",
+        help="File paths to run tests from (supports partial paths and filenames)",
+    )
+    args = parser.parse_args()
+
+    # Determine verbosity level
+    if args.quiet:
+        verbosity = VERBOSITY_QUIET
+    elif args.verbose:
+        verbosity = VERBOSITY_VERBOSE
+    else:
+        verbosity = VERBOSITY_NORMAL
+
+    try:
+        # Find project root (where tests/ directory is located)
+        project_root: Path = _find_project_root()
+
+        # Setup src/ directory in sys.path if it exists
+        _setup_src_path(project_root)
+
+        # Add src directory to path for core module imports
+        sys.path.insert(0, str(Path(__file__).parent))
+
+        # Discover and load test modules
+        modules_loaded: int = discover_and_load_tests(project_root)
+        if modules_loaded == 0:
+            return 0
+
+        if verbosity >= VERBOSITY_NORMAL:
+            print(f"\nLoaded {modules_loaded} test module(s).\n")
+
+        # Execute collected tests with filters
+        results, summary = execute(
+            fail_fast=args.fail_fast,
+            name_pattern=args.name_pattern,
+            file_patterns=args.files if args.files else None,
+        )
+
+        # Generate and display report
+        output: str = report(results, summary, verbosity=verbosity)
+        print(output)
+
+        # Return 1 if any tests failed or errors occurred
+        has_failures: bool = int(summary.get("failed", 0)) > 0 or int(summary.get("errors", 0)) > 0
+        return 1 if has_failures else 0
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+        return 1
+    except Exception as e:
+        print(f"Unexpected error: {type(e).__name__}: {e}")
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyforge_test/core/registry.py

@@ -0,0 +1,45 @@
+from collections.abc import Callable
+from typing import Any, TypedDict
+
+
+class TestCase(TypedDict):
+    """TypedDict for test case structure.
+
+    Attributes:
+        function: The test function to execute.
+        filename: The source file where the test is defined.
+        line_number: The line number where the test is defined.
+        skip_info: Dictionary containing skip information and reason.
+        marker: The test marker (e.g., 'slow', 'integration', 'wip').
+    """
+
+    function: Callable[..., None]
+    filename: str
+    line_number: int
+    skip_info: dict[str, Any] | None
+    marker: str | None
+
+
+class ResultDict(TypedDict):
+    """TypedDict for test result structure.
+
+    Attributes:
+        name: The test function name.
+        result: The test result status (Passed, Failed, Error, or Skipped).
+        filename: The source file where the test is defined.
+        line_number: The line number where the test is defined.
+        skip_info: Dictionary containing skip information and reason.
+        marker: The test marker (e.g., 'slow', 'integration', 'wip').
+        traceback: The traceback string for failed/error tests, None otherwise.
+    """
+
+    name: str
+    result: str
+    filename: str
+    line_number: int
+    skip_info: dict[str, Any] | None
+    marker: str | None
+    traceback: str | None
+
+
+TESTS: list[TestCase] = []