elspais 0.9.1__py3-none-any.whl

elspais/testing/mapper.py

@@ -0,0 +1,163 @@
+"""
+elspais.testing.mapper - Test-to-requirement mapping orchestration.
+
+Coordinates test file scanning and result parsing to produce
+per-requirement test coverage data.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+from elspais.testing.config import TestingConfig
+from elspais.testing.result_parser import ResultParser, TestResult, TestStatus
+from elspais.testing.scanner import TestScanner
+
+
+@dataclass
+class RequirementTestData:
+    """
+    Test coverage data for a single requirement.
+
+    Attributes:
+        test_count: Total number of tests referencing this requirement
+        test_passed: Number of passed tests
+        test_failed: Number of failed tests
+        test_skipped: Number of skipped tests
+        test_result_files: Unique result file paths for this requirement
+    """
+
+    test_count: int = 0
+    test_passed: int = 0
+    test_failed: int = 0
+    test_skipped: int = 0
+    test_result_files: List[str] = field(default_factory=list)
+
+
+@dataclass
+class TestMappingResult:
+    """
+    Complete test mapping for all requirements.
+
+    Attributes:
+        requirement_data: Mapping of requirement IDs to test data
+        scan_summary: Summary of scanning operation
+        errors: List of errors encountered
+    """
+
+    requirement_data: Dict[str, RequirementTestData] = field(default_factory=dict)
+    scan_summary: Dict[str, Any] = field(default_factory=dict)
+    errors: List[str] = field(default_factory=list)
+
+
+class TestMapper:
+    """
+    Orchestrates test scanning and result mapping.
+
+    Coordinates the TestScanner and ResultParser to produce
+    per-requirement test coverage data for JSON output.
+    """
+
+    def __init__(self, config: TestingConfig) -> None:
+        """
+        Initialize the mapper.
+
+        Args:
+            config: Testing configuration
+        """
+        self.config = config
+        self._scanner = TestScanner(config.reference_patterns or None)
+        self._parser = ResultParser(config.reference_patterns or None)
+
+    def map_tests(
+        self,
+        requirement_ids: Set[str],
+        base_path: Path,
+        ignore: Optional[List[str]] = None,
+    ) -> TestMappingResult:
+        """
+        Map tests to requirements and gather coverage data.
+
+        Args:
+            requirement_ids: Set of known requirement IDs
+            base_path: Project root path
+            ignore: Directory names to ignore
+
+        Returns:
+            TestMappingResult with per-requirement test data
+        """
+        result = TestMappingResult()
+        ignore_dirs = ignore or []
+
+        # Step 1: Scan test files for requirement references
+        scan_result = self._scanner.scan_directories(
+            base_path=base_path,
+            test_dirs=self.config.test_dirs,
+            file_patterns=self.config.patterns,
+            ignore=ignore_dirs,
+        )
+
+        result.scan_summary["files_scanned"] = scan_result.files_scanned
+        result.scan_summary["test_dirs"] = self.config.test_dirs
+        result.scan_summary["patterns"] = self.config.patterns
+        result.errors.extend(scan_result.errors)
+
+        # Step 2: Parse test result files
+        parse_result = self._parser.parse_result_files(
+            base_path=base_path,
+            result_file_patterns=self.config.result_files,
+        )
+
+        result.scan_summary["result_files_parsed"] = len(parse_result.files_parsed)
+        result.errors.extend(parse_result.errors)
+
+        # Step 3: Build requirement ID to test results mapping
+        req_to_results: Dict[str, List[TestResult]] = {}
+        for test_result in parse_result.results:
+            for req_id in test_result.requirement_ids:
+                if req_id not in req_to_results:
+                    req_to_results[req_id] = []
+                req_to_results[req_id].append(test_result)
+
+        # Step 4: Calculate per-requirement test data
+        # Combine scan references with result data
+        all_req_ids = set(scan_result.references.keys()) | set(req_to_results.keys())
+
+        for req_id in all_req_ids:
+            test_data = RequirementTestData()
+
+            # Count from scan references (test files found)
+            if req_id in scan_result.references:
+                test_data.test_count = len(scan_result.references[req_id])
+
+            # Count from results (if available)
+            if req_id in req_to_results:
+                results = req_to_results[req_id]
+                # If we have results, use result count (more accurate)
+                if not scan_result.references.get(req_id):
+                    test_data.test_count = len(results)
+
+                result_files: Set[str] = set()
+                for tr in results:
+                    if tr.status == TestStatus.PASSED:
+                        test_data.test_passed += 1
+                    elif tr.status == TestStatus.FAILED:
+                        test_data.test_failed += 1
+                    elif tr.status == TestStatus.ERROR:
+                        test_data.test_failed += 1
+                    elif tr.status == TestStatus.SKIPPED:
+                        test_data.test_skipped += 1
+
+                    if tr.result_file:
+                        result_files.add(str(tr.result_file))
+
+                test_data.test_result_files = sorted(result_files)
+
+            result.requirement_data[req_id] = test_data
+
+        # Ensure all known requirements have entries (even if zero)
+        for req_id in requirement_ids:
+            if req_id not in result.requirement_data:
+                result.requirement_data[req_id] = RequirementTestData()
+
+        return result

elspais/testing/result_parser.py

@@ -0,0 +1,289 @@
+"""
+elspais.testing.result_parser - Test result file parser.
+
+Parses JUnit XML and pytest JSON result files to extract test outcomes.
+"""
+
+import json
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set
+
+
+class TestStatus(Enum):
+    """Test execution status."""
+
+    PASSED = "passed"
+    FAILED = "failed"
+    ERROR = "error"
+    SKIPPED = "skipped"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class TestResult:
+    """
+    Result of a single test case.
+
+    Attributes:
+        test_name: Name of the test function/method
+        classname: Test class or module name
+        status: Test execution status
+        requirement_ids: Requirement IDs this test covers
+        result_file: Path to the result file
+        duration: Test duration in seconds (if available)
+        message: Failure/error message (if applicable)
+    """
+
+    test_name: str
+    classname: str
+    status: TestStatus
+    requirement_ids: List[str] = field(default_factory=list)
+    result_file: Optional[Path] = None
+    duration: Optional[float] = None
+    message: Optional[str] = None
+
+
+@dataclass
+class ResultParseResult:
+    """
+    Result of parsing test result files.
+
+    Attributes:
+        results: List of all parsed test results
+        files_parsed: List of successfully parsed files
+        errors: List of parse errors
+    """
+
+    results: List[TestResult] = field(default_factory=list)
+    files_parsed: List[Path] = field(default_factory=list)
+    errors: List[str] = field(default_factory=list)
+
+
+class ResultParser:
+    """
+    Parses test result files (JUnit XML, pytest JSON).
+
+    Extracts test names, outcomes, and requirement references from
+    test result files to correlate with test file scanning.
+    """
+
+    # Patterns for extracting requirement IDs from test names
+    DEFAULT_REF_PATTERNS = [
+        r"(?:REQ[-_])?([pod]\d{5})(?:[-_]([A-Z]))?",
+    ]
+
+    def __init__(self, reference_patterns: Optional[List[str]] = None) -> None:
+        """
+        Initialize the parser.
+
+        Args:
+            reference_patterns: Regex patterns to extract requirement IDs from test names
+        """
+        patterns = reference_patterns or self.DEFAULT_REF_PATTERNS
+        self._patterns = [re.compile(p) for p in patterns]
+
+    def parse_result_files(
+        self,
+        base_path: Path,
+        result_file_patterns: List[str],
+    ) -> ResultParseResult:
+        """
+        Parse all matching result files.
+
+        Args:
+            base_path: Project root path
+            result_file_patterns: Glob patterns for result files
+
+        Returns:
+            ResultParseResult with all parsed test results
+        """
+        result = ResultParseResult()
+        seen_files: Set[Path] = set()
+
+        for pattern in result_file_patterns:
+            for result_file in base_path.glob(pattern):
+                if result_file in seen_files:
+                    continue
+                if not result_file.is_file():
+                    continue
+                seen_files.add(result_file)
+
+                try:
+                    if result_file.suffix == ".xml":
+                        file_results = self._parse_junit_xml(result_file)
+                    elif result_file.suffix == ".json":
+                        file_results = self._parse_pytest_json(result_file)
+                    else:
+                        continue
+
+                    result.results.extend(file_results)
+                    result.files_parsed.append(result_file)
+                except Exception as e:
+                    result.errors.append(f"{result_file}: {e}")
+
+        return result
+
+    def _parse_junit_xml(self, file_path: Path) -> List[TestResult]:
+        """
+        Parse a JUnit XML result file.
+
+        Args:
+            file_path: Path to JUnit XML file
+
+        Returns:
+            List of TestResult objects
+        """
+        results: List[TestResult] = []
+
+        try:
+            tree = ET.parse(file_path)
+            root = tree.getroot()
+        except ET.ParseError as e:
+            raise ValueError(f"Invalid XML: {e}")
+
+        # Handle both <testsuites> and <testsuite> as root
+        if root.tag == "testsuites":
+            testsuites = root.findall("testsuite")
+        elif root.tag == "testsuite":
+            testsuites = [root]
+        else:
+            return results
+
+        for testsuite in testsuites:
+            for testcase in testsuite.findall("testcase"):
+                test_name = testcase.get("name", "")
+                classname = testcase.get("classname", "")
+                time_str = testcase.get("time")
+                duration = float(time_str) if time_str else None
+
+                # Determine status
+                failure = testcase.find("failure")
+                error = testcase.find("error")
+                skipped = testcase.find("skipped")
+
+                if failure is not None:
+                    status = TestStatus.FAILED
+                    message = failure.get("message") or failure.text
+                elif error is not None:
+                    status = TestStatus.ERROR
+                    message = error.get("message") or error.text
+                elif skipped is not None:
+                    status = TestStatus.SKIPPED
+                    message = skipped.get("message") or skipped.text
+                else:
+                    status = TestStatus.PASSED
+                    message = None
+
+                # Extract requirement IDs from test name
+                req_ids = self._extract_requirement_ids(test_name, classname)
+
+                results.append(TestResult(
+                    test_name=test_name,
+                    classname=classname,
+                    status=status,
+                    requirement_ids=req_ids,
+                    result_file=file_path,
+                    duration=duration,
+                    message=message,
+                ))
+
+        return results
+
+    def _parse_pytest_json(self, file_path: Path) -> List[TestResult]:
+        """
+        Parse a pytest JSON result file.
+
+        Args:
+            file_path: Path to pytest JSON file
+
+        Returns:
+            List of TestResult objects
+        """
+        results: List[TestResult] = []
+
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON: {e}")
+
+        # Handle pytest-json-report format
+        tests = data.get("tests", [])
+        for test in tests:
+            nodeid = test.get("nodeid", "")
+            outcome = test.get("outcome", "unknown")
+
+            # Parse nodeid: "tests/test_foo.py::TestClass::test_method"
+            parts = nodeid.split("::")
+            test_name = parts[-1] if parts else nodeid
+            classname = parts[-2] if len(parts) > 1 else ""
+
+            # Map outcome to status
+            status_map = {
+                "passed": TestStatus.PASSED,
+                "failed": TestStatus.FAILED,
+                "error": TestStatus.ERROR,
+                "skipped": TestStatus.SKIPPED,
+            }
+            status = status_map.get(outcome, TestStatus.UNKNOWN)
+
+            # Get duration and message
+            duration = test.get("duration")
+            message = None
+            call_data = test.get("call", {})
+            if call_data and status in (TestStatus.FAILED, TestStatus.ERROR):
+                message = call_data.get("longrepr")
+
+            # Extract requirement IDs
+            req_ids = self._extract_requirement_ids(test_name, classname)
+
+            results.append(TestResult(
+                test_name=test_name,
+                classname=classname,
+                status=status,
+                requirement_ids=req_ids,
+                result_file=file_path,
+                duration=duration,
+                message=message,
+            ))
+
+        return results
+
+    def _extract_requirement_ids(self, test_name: str, classname: str) -> List[str]:
+        """
+        Extract requirement IDs from test name and classname.
+
+        Args:
+            test_name: Test function/method name
+            classname: Test class or module name
+
+        Returns:
+            List of normalized requirement IDs (e.g., ["REQ-p00001"])
+        """
+        req_ids: List[str] = []
+        search_text = f"{classname}::{test_name}"
+
+        for pattern in self._patterns:
+            for match in pattern.finditer(search_text):
+                groups = match.groups()
+                if not groups or not groups[0]:
+                    continue
+                type_id = groups[0]
+                # Normalize to full requirement ID (ignore assertion label for ID)
+                req_id = f"REQ-{type_id}"
+                if req_id not in req_ids:
+                    req_ids.append(req_id)
+
+        return req_ids
+
+    def parse_junit_xml(self, file_path: Path) -> List[TestResult]:
+        """Public method to parse a JUnit XML file."""
+        return self._parse_junit_xml(file_path)
+
+    def parse_pytest_json(self, file_path: Path) -> List[TestResult]:
+        """Public method to parse a pytest JSON file."""
+        return self._parse_pytest_json(file_path)

elspais/testing/scanner.py

@@ -0,0 +1,206 @@
+"""
+elspais.testing.scanner - Test file scanner for requirement references.
+
+Scans test files for requirement ID references (e.g., REQ-d00001, REQ-p00001-A)
+in function names, docstrings, and comments.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+
+@dataclass
+class TestReference:
+    """
+    A reference from a test to a requirement.
+
+    Attributes:
+        requirement_id: Normalized requirement ID (e.g., "REQ-p00001")
+        assertion_label: Assertion label if present (e.g., "A" for REQ-p00001-A)
+        test_file: Path to the test file
+        test_name: Name of the test function/method if extractable
+        line_number: Line number where reference was found
+    """
+
+    requirement_id: str
+    assertion_label: Optional[str]
+    test_file: Path
+    test_name: Optional[str] = None
+    line_number: int = 0
+
+
+@dataclass
+class TestScanResult:
+    """
+    Result of scanning test files for requirement references.
+
+    Attributes:
+        references: Mapping of requirement IDs to their test references
+        files_scanned: Number of test files scanned
+        errors: List of errors encountered during scanning
+    """
+
+    references: Dict[str, List[TestReference]] = field(default_factory=dict)
+    files_scanned: int = 0
+    errors: List[str] = field(default_factory=list)
+
+    def add_reference(self, ref: TestReference) -> None:
+        """Add a test reference, rolling up assertion-level refs to parent."""
+        # Roll up assertion-level references to the parent requirement
+        req_id = ref.requirement_id
+        if req_id not in self.references:
+            self.references[req_id] = []
+        self.references[req_id].append(ref)
+
+
+class TestScanner:
+    """
+    Scans test files for requirement ID references.
+
+    Uses configurable patterns to find requirement references in:
+    - Test function/method names
+    - Docstrings
+    - Comments (IMPLEMENTS: patterns)
+    """
+
+    # Default patterns if none configured
+    DEFAULT_PATTERNS = [
+        # Test function names: test_REQ_p00001_something or test_p00001_something
+        r"test_.*(?:REQ[-_])?([pod]\d{5})(?:[-_]([A-Z]))?",
+        # IMPLEMENTS comments: IMPLEMENTS: REQ-p00001 or IMPLEMENTS: REQ-p00001-A
+        r"(?:IMPLEMENTS|Implements|implements)[:\s]+(?:REQ[-_])?([pod]\d{5})(?:-([A-Z]))?",
+        # Direct references: REQ-p00001 or REQ-p00001-A
+        r"\bREQ[-_]([pod]\d{5})(?:-([A-Z]))?\b",
+    ]
+
+    def __init__(self, reference_patterns: Optional[List[str]] = None) -> None:
+        """
+        Initialize the scanner with reference patterns.
+
+        Args:
+            reference_patterns: Regex patterns for extracting requirement IDs.
+                               Each pattern should have groups for (type+id) and
+                               optionally (assertion_label).
+        """
+        patterns = reference_patterns or self.DEFAULT_PATTERNS
+        self._patterns = [re.compile(p) for p in patterns]
+
+    def scan_directories(
+        self,
+        base_path: Path,
+        test_dirs: List[str],
+        file_patterns: List[str],
+        ignore: Optional[List[str]] = None,
+    ) -> TestScanResult:
+        """
+        Scan test directories for requirement references.
+
+        Args:
+            base_path: Project root path
+            test_dirs: Glob patterns for test directories (e.g., ["apps/**/test"])
+            file_patterns: File patterns to match (e.g., ["*_test.py"])
+            ignore: Directory names to ignore (e.g., ["node_modules"])
+
+        Returns:
+            TestScanResult with all found references
+        """
+        result = TestScanResult()
+        ignore_set = set(ignore or [])
+        seen_files: Set[Path] = set()
+
+        for dir_pattern in test_dirs:
+            # Handle special cases for directory patterns
+            if dir_pattern in (".", ""):
+                # Current directory
+                dirs_to_scan = [base_path]
+            else:
+                # Resolve the directory pattern
+                dirs_to_scan = list(base_path.glob(dir_pattern))
+
+            for test_dir in dirs_to_scan:
+                if not test_dir.is_dir():
+                    continue
+                if any(ig in test_dir.parts for ig in ignore_set):
+                    continue
+
+                # Find test files in this directory
+                for file_pattern in file_patterns:
+                    for test_file in test_dir.glob(file_pattern):
+                        if test_file in seen_files:
+                            continue
+                        if not test_file.is_file():
+                            continue
+                        seen_files.add(test_file)
+
+                        # Scan the file
+                        file_refs = self._scan_file(test_file)
+                        for ref in file_refs:
+                            result.add_reference(ref)
+                        result.files_scanned += 1
+
+        return result
+
+    def _scan_file(self, file_path: Path) -> List[TestReference]:
+        """
+        Scan a single test file for requirement references.
+
+        Args:
+            file_path: Path to the test file
+
+        Returns:
+            List of TestReference objects found in the file
+        """
+        references: List[TestReference] = []
+
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="replace")
+        except Exception:
+            return references
+
+        lines = content.split("\n")
+        current_test_name: Optional[str] = None
+
+        for line_num, line in enumerate(lines, start=1):
+            # Track current test function name
+            test_match = re.match(r"\s*def\s+(test_\w+)", line)
+            if test_match:
+                current_test_name = test_match.group(1)
+
+            # Look for requirement references
+            for pattern in self._patterns:
+                for match in pattern.finditer(line):
+                    groups = match.groups()
+                    if not groups or not groups[0]:
+                        continue
+
+                    # Extract requirement ID parts
+                    type_id = groups[0]  # e.g., "p00001"
+                    assertion_label = groups[1] if len(groups) > 1 else None
+
+                    # Normalize to full requirement ID
+                    req_id = f"REQ-{type_id}"
+
+                    ref = TestReference(
+                        requirement_id=req_id,
+                        assertion_label=assertion_label,
+                        test_file=file_path,
+                        test_name=current_test_name,
+                        line_number=line_num,
+                    )
+                    references.append(ref)
+
+        return references
+
+    def scan_file(self, file_path: Path) -> List[TestReference]:
+        """
+        Public method to scan a single file.
+
+        Args:
+            file_path: Path to the test file
+
+        Returns:
+            List of TestReference objects
+        """
+        return self._scan_file(file_path)