test_runner_modular.py

"""
Modular test runner sub-module.

Provides ModularTestRunner class for category-based test execution
with resource monitoring, timeout handling, and comprehensive reporting.

Also provides create_test_runner() factory and monitor_memory() utility.

Extracted from runner.py for maintainability.
"""

import gc
import json
import logging
import os
import re
import signal
import subprocess  # nosec B404 -- subprocess calls with controlled/trusted input
import sys
import threading
import time
from pathlib import Path
from typing import Any, Dict, List

from .categories import MODULAR_TEST_CATEGORIES


class ModularTestRunner:
    """Test runner with comprehensive error handling and reporting."""

    def __init__(self, args, logger: logging.Logger):
        self.args = args
        self.logger = logger
        self.project_root = Path(__file__).parent.parent.parent
        self.test_dir = self.project_root / "src" / "tests"
        self.results = {}
        self.start_time = time.time()

        # Error tracking
        self.total_tests_run = 0
        self.total_tests_passed = 0
        self.total_tests_failed = 0
        self.total_tests_skipped = 0
        self.categories_run = 0
        self.categories_successful = 0
        self.categories_failed = 0

        # Performance tracking
        self.category_times = {}
        self.slowest_tests = []

        # Resource monitoring
        self.resource_usage = {}

        # Error categorization
        self.import_errors = []
        self.runtime_errors = []
        self.pathlib_errors = []
        self.sapf_errors = []

        self.logger.info(f"Initialized ModularTestRunner with {len(MODULAR_TEST_CATEGORIES)} categories")

    def _monitor_resources_during_test(self):
        """Monitor system resources during test execution."""
        try:
            import psutil
            process = psutil.Process()
            return {
                "memory_mb": process.memory_info().rss / 1024 / 1024,
                "cpu_percent": process.cpu_percent(),
                "threads": process.num_threads()
            }
        except ImportError:
            return {"memory_mb": 0, "cpu_percent": 0, "threads": 0}

    def should_run_category(self, category: str) -> bool:
        """Determine if a test category should be run based on arguments."""
        if hasattr(self.args, 'comprehensive') and self.args.comprehensive:
            return True

        if hasattr(self.args, 'fast_only') and self.args.fast_only:
            return category in ["core", "pipeline", "validation", "utilities", "fast_suite"]

        if category == "performance" and hasattr(self.args, 'include_performance') and not self.args.include_performance:
            return False

        if category in ["specialized", "integration"] and hasattr(self.args, 'include_slow') and not self.args.include_slow:
            return False

        return category not in ["performance", "specialized", "integration"]

    def _run_fallback_tests(self, category: str, test_files: List[str], python_executable: str, start_time: float) -> Dict[str, Any]:
        """Recovery test execution when pytest fails with internal errors."""
        self.logger.info(f"Running recovery test execution for category '{category}'")

        total_tests = 0
        passed_tests = 0
        failed_tests = 0

        for test_file in test_files:
            try:
                syntax_result = subprocess.run(  # nosec B603 -- subprocess calls with controlled/trusted input
                    [python_executable, "-m", "py_compile", test_file],
                    capture_output=True,
                    text=True,
                    timeout=30
                )

                if syntax_result.returncode == 0:
                    total_tests += 1
                    passed_tests += 1
                    self.logger.info(f"  {Path(test_file).name}: Syntax valid")
                else:
                    total_tests += 1
                    failed_tests += 1
                    self.logger.warning(f"  {Path(test_file).name}: Syntax error")

            except Exception as e:
                total_tests += 1
                failed_tests += 1
                self.logger.warning(f"  {Path(test_file).name}: Error {e}")

        duration = time.time() - start_time
        self.category_times[category] = duration

        self.total_tests_run += total_tests
        self.total_tests_passed += passed_tests
        self.total_tests_failed += failed_tests

        return {
            "success": failed_tests == 0,
            "tests_run": total_tests,
            "tests_passed": passed_tests,
            "tests_failed": failed_tests,
            "tests_skipped": 0,
            "duration": duration,
            "stdout": f"Recovery execution: {passed_tests}/{total_tests} files passed syntax check",
            "stderr": "",
            "returncode": 1 if failed_tests > 0 else 0,
            "resource_usage": {"memory_mb": 0, "cpu_percent": 0, "threads": 0}
        }

    def discover_test_files(self, category: str, config: Dict[str, Any]) -> List[str]:
        """Discover test files for a category with enhanced error handling."""
        test_files = []

        for file_pattern in config.get("files", []):
            exact_file = self.test_dir / file_pattern
            if exact_file.exists():
                test_files.append(str(exact_file))
                continue

            pattern_files = list(self.test_dir.glob(file_pattern))
            test_files.extend([str(f) for f in pattern_files])

        test_files = sorted(set(test_files))

        self.logger.info(f"Discovered {len(test_files)} test files for category '{category}': {test_files}")
        return test_files

    def _parse_pytest_output(self, stdout: str, stderr: str) -> Dict[str, int]:
        """Parse pytest output to extract test counts."""
        tests_run = 0
        tests_passed = 0
        tests_failed = 0
        tests_skipped = 0

        lines = stdout.split('\n')

        for line in reversed(lines):
            line = line.strip()
            if "passed" in line and ("failed" in line or "skipped" in line or "error" in line):
                match = re.search(r'(\d+)\s+passed.*?(\d+)\s+(failed|skipped|error)', line)
                if match:
                    tests_passed = int(match.group(1))
                    count = int(match.group(2))
                    status = match.group(3)

                    if status == "failed" or status == "error":
                        tests_failed = count
                    elif status == "skipped":
                        tests_skipped = count

                    tests_run = tests_passed + tests_failed + tests_skipped
                    break

        if tests_run == 0:
            passed_count = stdout.count(" PASSED")
            failed_count = stdout.count(" FAILED") + stdout.count(" ERROR")
            skipped_count = stdout.count(" SKIPPED")

            if passed_count > 0 or failed_count > 0 or skipped_count > 0:
                tests_passed = passed_count
                tests_failed = failed_count
                tests_skipped = skipped_count
                tests_run = passed_count + failed_count + skipped_count

        if tests_run == 0:
            for line in lines:
                if "collected" in line and "items" in line:
                    parts = line.split()
                    for i, part in enumerate(parts):
                        if part == "collected" and i+1 < len(parts):
                            try:
                                tests_run = int(parts[i+1])
                                tests_passed = tests_run
                                break
                            except (ValueError, IndexError):
                                pass

        return {
            "tests_run": tests_run,
            "tests_passed": tests_passed,
            "tests_failed": tests_failed,
            "tests_skipped": tests_skipped,
            "total": tests_run,
            "passed": tests_passed,
            "failed": tests_failed,
            "skipped": tests_skipped
        }

    def run_test_category(self, category: str, config: Dict[str, Any]) -> Dict[str, Any]:
        """Run tests for a specific category with comprehensive error handling."""
        category_start_time = time.time()

        self.logger.info(f"\n{'='*60}")
        self.logger.info(f"Running category: {config['name']}")
        self.logger.info(f"Description: {config['description']}")
        effective_timeout_seconds = int(config.get('timeout_seconds', 120))
        self.logger.info(f"Category timeout budget: {effective_timeout_seconds} seconds")
        self.logger.info(f"Parallel: {config.get('parallel', True)}")
        self.logger.info(f"{'='*60}")

        test_files = self.discover_test_files(category, config)

        if not test_files:
            self.logger.info(f"No test files found for category '{category}', marking as skipped/success")
            return {
                "success": True,
                "tests_run": 0,
                "tests_passed": 0,
                "tests_failed": 0,
                "tests_skipped": 0,
                "duration": 0,
                "stdout": "",
                "stderr": "",
                "return_code": 0
            }

        self.logger.info(f"Found {len(test_files)} test files:")
        for test_file in test_files:
            self.logger.info(f"  {test_file}")

        # Use the same interpreter as the runner so plugin detection (below) matches the
        # subprocess (e.g. uv run --extra dev provides pytest_cov, xdist, etc. in both).
        python_executable = sys.executable
        self.logger.info(f"Using Python: {python_executable}")

        # Detect optional pytest plugins. Only enable a plugin if it can be imported in this
        # process, so the subprocess (same executable) can load it without ModuleNotFoundError.
        import importlib.util

        def _has_plugin(name: str) -> bool:
            if importlib.util.find_spec(name) is None:
                return False
            try:
                __import__(name)
                return True
            except Exception:
                return False

        _has_plugin("xdist")
        _has_plugin("pytest_cov")
        _has_plugin("pytest_jsonreport")
        _has_plugin("pytest_timeout")
        _has_plugin("pytest_asyncio")

        category_output_dir = Path(self.args.output_dir) / "test_reports" / f"category_{category}"
        category_output_dir.mkdir(parents=True, exist_ok=True)

        cmd = [
            python_executable, "-m", "pytest",
            "--tb=short",
            "--maxfail=10",
            "--durations=10",
            "--no-header",
            "-p", "no:randomly",
            "-p", "no:sugar",
            "-p", "no:cacheprovider",
        ]
        # Optional plugins: omit so subprocess runs without requiring dev plugins.
        # Adding -p/--timeout/--cov causes ModuleNotFoundError or unrecognized args when
        # the subprocess env differs from the runner. Run plain pytest for reliability.
        self.logger.info("Optional plugins (timeout, cov, json-report) omitted for runner stability")

        if config.get("markers"):
            for marker in config["markers"]:
                cmd.extend(["-m", marker])
            self.logger.info(f"Using markers: {config['markers']}")

        cmd.extend(test_files)

        # Parallel: omit -n auto to avoid xdist plugin load issues in subprocess
        if config.get("parallel", True) and getattr(self.args, 'parallel', True):
            self.logger.info("Sequential execution (xdist omitted for stability)")
        else:
            self.logger.info("Sequential execution")

        self.logger.info(f"Executing command: {' '.join(cmd[:5])}...")

        try:
            initial_resources = self._monitor_resources_during_test()
            self.logger.info(f"Initial resource usage: {initial_resources}")

            old_handler = None

            try:
                env = os.environ.copy()
                # Prepend project src/ to PYTHONPATH; never clobber existing paths so
                # wrapper/CI paths are preserved. Plugin loading is deterministic via
                # optional plugin options; pytest loads them via entry points.
                existing_pythonpath = env.get("PYTHONPATH", "")
                src_path = str(self.project_root / "src")
                env["PYTHONPATH"] = (
                    f"{src_path}{os.pathsep}{existing_pythonpath}"
                    if existing_pythonpath
                    else src_path
                )
                # Let pytest auto-load plugins via entry points so the subprocess finds
                # timeout, cov, xdist, etc. without -p module name import issues.
                # Allow pytest to load installed plugins (e.g. pytest-timeout, pytest-cov).
                # Keep the subprocess environment deterministic: do not inherit
                # `PYTEST_ADDOPTS` from the outer shell/editor.
                env["PYTEST_ADDOPTS"] = " ".join(
                    [
                        "-v",
                        "-rA",
                        "-s",
                        "--durations=15",
                        "-o",
                        "console_output_style=classic",
                        "--color=no",
                        "--log-cli-level=WARNING",
                    ]
                ).strip()
                env.setdefault("PYTHONUNBUFFERED", "1")
                env.setdefault("TERM", "dumb")
                env.setdefault("NO_COLOR", "1")
                env.setdefault("PY_COLORS", "0")
                env.setdefault("COLUMNS", "120")
                env.setdefault("LINES", "40")
                env.setdefault("OLLAMA_DISABLED", "1")

                self.logger.info(f"Starting test execution at {time.strftime('%H:%M:%S')}")

                stdout_path = category_output_dir / "pytest_stdout.txt"
                stderr_path = category_output_dir / "pytest_stderr.txt"

                process = subprocess.Popen(  # nosec B603 -- subprocess calls with controlled/trusted input
                    cmd,
                    stdout=subprocess.PIPE,
                    stderr=subprocess.PIPE,
                    text=True,
                    bufsize=1,
                    cwd=self.project_root,
                    env=env
                )

                collected_stdout: List[str] = []
                collected_stderr: List[str] = []
                progress_counts = {"passed": 0, "failed": 0, "skipped": 0}
                last_output_time = time.time()

                def _log_progress_line(line: str):
                    nonlocal progress_counts
                    # Only count pytest outcome lines (avoid counting arbitrary log messages
                    # that contain words like "error" or "failed").
                    #
                    # Examples:
                    # - path::test_name PASSED
                    # - path::test_name FAILED
                    # - path::test_name SKIPPED
                    if re.search(r"::.*\sPASSED(\s|$)", line):
                        progress_counts["passed"] += 1
                        return
                    if re.search(r"::.*\sFAILED(\s|$)", line) or line.startswith("FAILED "):
                        progress_counts["failed"] += 1
                        return
                    if re.search(r"::.*\sSKIPPED(\s|$)", line):
                        progress_counts["skipped"] += 1
                        return

                    # If we see a final summary, prefer its numeric counts.
                    m = re.search(r"(\d+)\s+passed", line)
                    if m:
                        progress_counts["passed"] = int(m.group(1))
                    m = re.search(r"(\d+)\s+failed", line)
                    if m:
                        progress_counts["failed"] = int(m.group(1))
                    m = re.search(r"(\d+)\s+skipped", line)
                    if m:
                        progress_counts["skipped"] = int(m.group(1))

                f_out = open(stdout_path, "w")
                f_err = open(stderr_path, "w")
                try:
                    def _stream(pipe, sink, is_err: bool):
                        nonlocal last_output_time
                        try:
                            for raw in iter(pipe.readline, ""):
                                line = raw.rstrip("\n")
                                try:
                                    sink.write(raw)
                                    sink.flush()
                                except Exception:
                                    break
                                if is_err:
                                    lower_line = line.lower()
                                    if (
                                        "traceback" in lower_line
                                        or lower_line.startswith("e   ")
                                        or "= fail" in lower_line
                                        or "failed" in lower_line
                                        or re.search(r"\b(error|exception)\b", lower_line)
                                    ):
                                        self.logger.error(line)
                                    elif "warn" in lower_line:
                                        self.logger.warning(line)
                                    else:
                                        self.logger.info(line)
                                    collected_stderr.append(line)
                                else:
                                    self.logger.info(line)
                                    collected_stdout.append(line)
                                    _log_progress_line(line)
                                last_output_time = time.time()
                        finally:
                            try:
                                pipe.close()
                            except Exception:
                                pass

                    t_out = threading.Thread(target=_stream, args=(process.stdout, f_out, False))
                    t_err = threading.Thread(target=_stream, args=(process.stderr, f_err, True))
                    t_out.start(); t_err.start()

                    collection_stall_limit = 25
                    while process.poll() is None:
                        if time.time() - last_output_time > 10:
                            elapsed = time.time() - category_start_time
                            self.logger.info(
                                f"... pytest running [{category}] -- elapsed {int(elapsed)}s; "
                                f"progress: {progress_counts['passed']} passed, {progress_counts['failed']} failed, {progress_counts['skipped']} skipped"
                            )
                            last_output_time = time.time()
                        if time.time() - last_output_time > collection_stall_limit:
                            self.logger.warning(f"Aborting category '{category}' due to inactivity > {collection_stall_limit}s")
                            try:
                                process.kill()
                            except Exception as e:
                                self.logger.debug(f"Could not kill stalled process: {e}")
                            break
                        time.sleep(2)

                    t_out.join()
                    t_err.join()
                finally:
                    try:
                        f_out.close()
                    except Exception as e:
                        self.logger.debug(f"Could not close stdout file: {e}")
                    try:
                        f_err.close()
                    except Exception as e:
                        self.logger.debug(f"Could not close stderr file: {e}")

                if old_handler is not None:
                    try:
                        signal.signal(signal.SIGALRM, old_handler)
                    except Exception as e:
                        self.logger.debug(f"Could not restore signal handler: {e}")

                execution_time = time.time() - category_start_time
                self.logger.info(f"Test execution completed in {execution_time:.2f} seconds")

                final_resources = self._monitor_resources_during_test()
                self.logger.info(f"Final resource usage: {final_resources}")

                resource_usage = {
                    "memory_mb": final_resources.get("memory_mb", 0),
                    "cpu_percent": final_resources.get("cpu_percent", 0),
                    "threads": final_resources.get("threads", 0)
                }
                self.resource_usage[category] = resource_usage

                stdout_text = "\n".join(collected_stdout)
                stderr_text = "\n".join(collected_stderr)

                if process.returncode == 3 and ("INTERNALERROR" in stdout_text or "INTERNALERROR" in stderr_text):
                    self.logger.warning(f"Pytest internal error detected for category '{category}', attempting recovery...")
                    return self._run_fallback_tests(category, test_files, python_executable, category_start_time)

                test_stats = self._parse_pytest_output(stdout_text, stderr_text)

                self.logger.info(f"Test Results for {category}:")
                self.logger.info(f"  Passed: {test_stats.get('passed', 0)}")
                self.logger.info(f"  Failed: {test_stats.get('failed', 0)}")
                self.logger.info(f"  Skipped: {test_stats.get('skipped', 0)}")
                self.logger.info(f"  Total: {test_stats.get('total', 0)}")

                total_tests = test_stats.get('total', 0)
                failed_tests = test_stats.get('failed', 0)
                passed_tests = test_stats.get('passed', 0)

                success = (total_tests > 0 and failed_tests == 0)

                if success:
                    self.logger.info(f"Category '{category}' completed successfully")
                else:
                    self.logger.warning(f"Category '{category}' completed with failures")

                return {
                    "success": success,
                    "tests_run": total_tests,
                    "tests_passed": passed_tests,
                    "tests_failed": failed_tests,
                    "tests_skipped": test_stats.get('skipped', 0),
                    "duration": execution_time,
                    "resource_usage": resource_usage,
                    "stdout": stdout_text,
                    "stderr": stderr_text,
                    "return_code": process.returncode
                }

            except subprocess.TimeoutExpired:
                if old_handler is not None:
                    try:
                        signal.signal(signal.SIGALRM, old_handler)
                    except Exception:
                        pass
                self.logger.error(f"Test category '{category}' reached subprocess timeout")
                return {
                    "success": False,
                    "error": "Subprocess timeout",
                    "tests_run": 0,
                    "tests_passed": 0,
                    "tests_failed": 0,
                    "tests_skipped": 0,
                    "duration": time.time() - category_start_time
                }

        except Exception as e:
            self.logger.error(f"Unexpected error in category '{category}': {e}")
            return {
                "success": False,
                "error": str(e),
                "tests_run": 0,
                "tests_passed": 0,
                "tests_failed": 0,
                "tests_skipped": 0,
                "duration": time.time() - category_start_time
            }

    def run_all_categories(self) -> Dict[str, Any]:
        """Run all test categories and generate comprehensive report."""
        self.logger.info(f"\n{'='*80}")
        self.logger.info("STARTING COMPREHENSIVE TEST SUITE EXECUTION")
        self.logger.info(f"{'='*80}")

        total_categories = len([cat for cat in MODULAR_TEST_CATEGORIES.keys() if self.should_run_category(cat)])
        self.logger.info(f"Total categories to run: {total_categories}")

        overall_success = True
        start_time = time.time()

        for i, (category, config) in enumerate(MODULAR_TEST_CATEGORIES.items(), 1):
            if not self.should_run_category(category):
                self.logger.info(f"Skipping category '{category}' based on arguments")
                continue

            self.logger.info(f"\n{'='*60}")
            self.logger.info(f"Category {i}/{total_categories}: {category}")
            self.logger.info(f"{config['name']}")
            self.logger.info(f"{'='*60}")

            self.categories_run += 1

            try:
                result = self.run_test_category(category, config)
                self.results[category] = result

                self.total_tests_run += result.get("tests_run", 0)
                self.total_tests_passed += result.get("tests_passed", 0)
                self.total_tests_failed += result.get("tests_failed", 0)
                self.total_tests_skipped += result.get("tests_skipped", 0)

                if result.get("success", False):
                    self.categories_successful += 1
                    self.logger.info(f"Category '{category}' completed successfully")
                else:
                    self.categories_failed += 1
                    overall_success = False
                    self.logger.warning(f"Category '{category}' completed with issues")

                duration = result.get("duration", 0)
                tests_run = result.get("tests_run", 0)
                tests_passed = result.get("tests_passed", 0)
                tests_failed = result.get("tests_failed", 0)

                self.logger.info(f"Category '{category}' Summary:")
                self.logger.info(f"  Duration: {duration:.2f}s")
                self.logger.info(f"  Tests: {tests_run} total, {tests_passed} passed, {tests_failed} failed")

                if tests_run > 0:
                    success_rate = (tests_passed / tests_run) * 100
                    self.logger.info(f"  Success Rate: {success_rate:.1f}%")

                resource_usage = result.get("resource_usage", {})
                if resource_usage:
                    memory_mb = resource_usage.get("memory_mb", 0)
                    cpu_percent = resource_usage.get("cpu_percent", 0)
                    self.logger.info(f"  Memory: {memory_mb:.1f}MB, CPU: {cpu_percent:.1f}%")

            except Exception as e:
                self.logger.error(f"Unexpected error in category '{category}': {e}")
                self.results[category] = {
                    "success": False,
                    "error": str(e),
                    "tests_run": 0,
                    "tests_passed": 0,
                    "tests_failed": 0,
                    "tests_skipped": 0,
                    "duration": 0
                }
                self.categories_failed += 1
                overall_success = False

        total_duration = time.time() - start_time

        self.logger.info(f"\n{'='*80}")
        self.logger.info("COMPREHENSIVE TEST SUITE SUMMARY")
        self.logger.info(f"{'='*80}")
        self.logger.info(f"Total Duration: {total_duration:.2f}s")
        self.logger.info(f"Categories: {self.categories_run} run, {self.categories_successful} successful, {self.categories_failed} failed")
        self.logger.info(f"Tests: {self.total_tests_run} total, {self.total_tests_passed} passed, {self.total_tests_failed} failed, {self.total_tests_skipped} skipped")

        if self.total_tests_run > 0:
            overall_success_rate = (self.total_tests_passed / self.total_tests_run) * 100
            self.logger.info(f"Overall Success Rate: {overall_success_rate:.1f}%")

        self.logger.info("\nGenerating comprehensive test reports...")
        self._save_intermediate_results()
        self._generate_final_report()
        self._log_final_summary(overall_success)

        return {
            "overall_success": overall_success,
            "total_tests_run": self.total_tests_run,
            "total_tests_passed": self.total_tests_passed,
            "total_tests_failed": self.total_tests_failed,
            "total_tests_skipped": self.total_tests_skipped,
            "categories_run": self.categories_run,
            "categories_successful": self.categories_successful,
            "categories_failed": self.categories_failed,
            "total_duration": total_duration,
            "success_rate": (self.total_tests_passed / self.total_tests_run * 100) if self.total_tests_run > 0 else 0
        }

    def _save_intermediate_results(self):
        """Save intermediate results to JSON files."""
        output_dir = Path(self.args.output_dir) / "test_reports"
        output_dir.mkdir(parents=True, exist_ok=True)

        for category, result in self.results.items():
            category_dir = output_dir / f"category_{category}"
            category_dir.mkdir(exist_ok=True)

            if "stdout" in result:
                with open(category_dir / "pytest_stdout.txt", "w") as f:
                    f.write(result["stdout"])

            if "stderr" in result:
                with open(category_dir / "pytest_stderr.txt", "w") as f:
                    f.write(result["stderr"])

            with open(category_dir / "pytest_command.txt", "w") as f:
                f.write(f"Category: {category}\n")
                f.write(f"Success: {result.get('success', False)}\n")
                f.write(f"Duration: {result.get('duration', 0):.2f}s\n")
                if "error" in result:
                    f.write(f"Error: {result['error']}\n")

                if "resource_usage" in result:
                    resource_data = result["resource_usage"]
                    f.write(f"Peak Memory: {resource_data.get('memory_mb', 0):.2f} MB\n")
                    f.write(f"CPU Usage: {resource_data.get('cpu_percent', 0):.1f}%\n")

    def _generate_final_report(self):
        """Generate comprehensive final test report."""
        output_dir = Path(self.args.output_dir) / "test_reports"

        success_rate = (self.total_tests_passed / max(self.total_tests_run, 1)) * 100

        summary = {
            "total_categories": self.categories_run,
            "successful_categories": self.categories_successful,
            "failed_categories": self.categories_failed,
            "total_tests_run": self.total_tests_run,
            "total_tests_passed": self.total_tests_passed,
            "total_tests_failed": self.total_tests_failed,
            "total_tests_skipped": self.total_tests_skipped,
            "success_rate": success_rate,
            "total_duration": time.time() - self.start_time,
            "category_times": self.category_times,
            "resource_usage": self.resource_usage,
            "error_categories": {
                "pathlib_errors": self.pathlib_errors,
                "sapf_errors": self.sapf_errors,
                "import_errors": self.import_errors,
                "runtime_errors": self.runtime_errors
            }
        }

        with open(output_dir / "modular_test_summary.json", "w") as f:
            json.dump(summary, f, indent=2)

        with open(output_dir / "modular_test_results.json", "w") as f:
            json.dump(self.results, f, indent=2)

    def _log_final_summary(self, success: bool):
        """Log comprehensive final summary."""
        self.logger.info(f"\n{'='*80}")
        self.logger.info("COMPREHENSIVE TEST SUITE EXECUTION COMPLETE")
        self.logger.info(f"{'='*80}")

        self.logger.info(f"Overall Result: {'SUCCESS' if success else 'FAILURE'}")
        self.logger.info(f"Total Duration: {time.time() - self.start_time:.2f}s")
        self.logger.info(f"Categories Run: {self.categories_run}")
        self.logger.info(f"Categories Successful: {self.categories_successful}")
        self.logger.info(f"Categories Failed: {self.categories_failed}")

        self.logger.info(f"Total Tests Run: {self.total_tests_run}")
        self.logger.info(f"Total Tests Passed: {self.total_tests_passed}")
        self.logger.info(f"Total Tests Failed: {self.total_tests_failed}")
        self.logger.info(f"Total Tests Skipped: {self.total_tests_skipped}")

        if self.total_tests_run > 0:
            success_rate = (self.total_tests_passed / self.total_tests_run) * 100
            self.logger.info(f"Success Rate: {success_rate:.1f}%")

        if self.pathlib_errors:
            self.logger.warning(f"Pathlib errors detected in categories: {self.pathlib_errors}")

        if self.sapf_errors:
            self.logger.warning(f"SAPF errors detected in categories: {self.sapf_errors}")

        if self.import_errors:
            self.logger.warning(f"Import errors detected in categories: {self.import_errors}")

        if self.category_times:
            slowest_category = max(self.category_times.items(), key=lambda x: x[1])
            self.logger.info(f"Slowest category: {slowest_category[0]} ({slowest_category[1]:.2f}s)")

        if self.resource_usage:
            peak_memory = max([usage.get("memory_mb", 0) for usage in self.resource_usage.values()])
            self.logger.info(f"Peak Memory Usage: {peak_memory:.2f} MB")

        self.logger.info(f"{'='*80}")


def create_test_runner(args, logger: logging.Logger) -> ModularTestRunner:
    """Factory function to create a ModularTestRunner instance."""
    return ModularTestRunner(args, logger)


def monitor_memory(logger: logging.Logger, threshold_mb: int = 2000):
    """Monitor memory usage and log warnings if threshold exceeded."""
    try:
        import psutil as _ps
        process = _ps.Process()
        memory_info = process.memory_info()
        memory_mb = memory_info.rss / 1024 / 1024

        if memory_mb > threshold_mb:
            logger.warning(f"High memory usage: {memory_mb:.1f}MB (threshold: {threshold_mb}MB)")

            gc.collect()

            memory_info = process.memory_info()
            memory_mb_after = memory_info.rss / 1024 / 1024

            if memory_mb_after < memory_mb:
                logger.info(f"Memory usage reduced to {memory_mb_after:.1f}MB after garbage collection")
            else:
                logger.warning(f"Memory usage still high: {memory_mb_after:.1f}MB")

        return memory_mb

    except Exception as e:
        logger.warning(f"Failed to monitor memory: {e}")
        return 0.0