provide-testkit 0.0.0.dev0__py3-none-any.whl

provide/testkit/quality/coverage/fixture.py

@@ -0,0 +1,236 @@
+"""Pytest fixtures for coverage tracking."""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from ..base import BaseQualityFixture
+from .tracker import COVERAGE_AVAILABLE, CoverageTracker
+
+
+class CoverageFixture(BaseQualityFixture):
+    """Pytest fixture for coverage tracking integration."""
+
+    def __init__(self, config: dict[str, Any] | None = None, artifact_dir: Path | None = None):
+        """Initialize coverage fixture.
+
+        Args:
+            config: Coverage configuration
+            artifact_dir: Directory for artifacts
+        """
+        super().__init__(config, artifact_dir)
+        self.tracker: CoverageTracker | None = None
+
+    def setup(self) -> None:
+        """Setup coverage tracking."""
+        if not COVERAGE_AVAILABLE:
+            pytest.skip("Coverage.py not available")
+
+        try:
+            self.tracker = CoverageTracker(self.config)
+        except Exception as e:
+            pytest.skip(f"Failed to initialize coverage: {e}")
+
+    def teardown(self) -> None:
+        """Stop coverage and generate reports."""
+        if self.tracker and self.tracker.is_running:
+            self.tracker.stop()
+
+    def start_tracking(self) -> None:
+        """Start coverage tracking."""
+        self.ensure_setup()
+        if self.tracker:
+            self.tracker.start()
+
+    def stop_tracking(self) -> None:
+        """Stop coverage tracking."""
+        if self.tracker:
+            self.tracker.stop()
+
+    def get_coverage(self) -> float:
+        """Get current coverage percentage."""
+        if not self.tracker:
+            return 0.0
+        return self.tracker.get_coverage()
+
+    def generate_report(self, format: str = "terminal") -> str:
+        """Generate coverage report."""
+        if not self.tracker:
+            return "No coverage data"
+        return self.tracker.generate_report(format)
+
+
+@pytest.fixture
+def coverage_tracker(request, tmp_path) -> Generator[CoverageFixture, None, None]:
+    """Pytest fixture for coverage tracking.
+
+    Provides a CoverageFixture instance that automatically starts and stops
+    coverage tracking around individual tests.
+
+    Usage:
+        def test_with_coverage(coverage_tracker):
+            coverage_tracker.start_tracking()
+            # ... test code
+            coverage_tracker.stop_tracking()
+            assert coverage_tracker.get_coverage() > 80
+    """
+    # Get configuration from pytest request
+    config = getattr(request, "param", {})
+
+    # Create artifact directory for this test
+    artifact_dir = tmp_path / "coverage"
+
+    # Initialize fixture
+    fixture = CoverageFixture(config=config, artifact_dir=artifact_dir)
+
+    try:
+        fixture.setup()
+        yield fixture
+    finally:
+        fixture.teardown()
+
+
+@pytest.fixture
+def auto_coverage(coverage_tracker) -> Generator[CoverageFixture, None, None]:
+    """Automatic coverage tracking fixture.
+
+    Automatically starts coverage at the beginning of the test and stops
+    at the end. Ideal for tests that want zero-configuration coverage.
+
+    Usage:
+        def test_automatic_coverage(auto_coverage):
+            # Coverage automatically tracked
+            result = some_function()
+            assert result is not None
+            # Coverage automatically stopped and saved
+    """
+    coverage_tracker.start_tracking()
+    try:
+        yield coverage_tracker
+    finally:
+        coverage_tracker.stop_tracking()
+
+
+@pytest.fixture(scope="session")
+def session_coverage(tmp_path_factory) -> Generator[CoverageFixture, None, None]:
+    """Session-wide coverage tracking.
+
+    Tracks coverage across all tests in the session. Useful for getting
+    overall coverage metrics for the entire test suite.
+
+    Usage:
+        def test_part_one(session_coverage):
+            # Coverage tracked across all tests
+            pass
+
+        def test_part_two(session_coverage):
+            # Same coverage instance
+            pass
+    """
+    # Create session-wide artifact directory
+    artifact_dir = tmp_path_factory.mktemp("session_coverage")
+
+    # Initialize session fixture
+    fixture = CoverageFixture(artifact_dir=artifact_dir)
+
+    try:
+        fixture.setup()
+        fixture.start_tracking()
+        yield fixture
+    finally:
+        fixture.stop_tracking()
+        fixture.teardown()
+
+
+@pytest.fixture
+def coverage_config():
+    """Default coverage configuration fixture.
+
+    Returns standard coverage configuration that can be customized
+    per test or project.
+
+    Usage:
+        def test_with_custom_coverage(coverage_config):
+            coverage_config["fail_under"] = 95
+            # Use with parametrized coverage_tracker
+    """
+    return {
+        "branch": True,
+        "source": ["src"],
+        "omit": [
+            "*/tests/*",
+            "*/test_*",
+            "*/.venv/*",
+            "*/venv/*",
+        ],
+        "fail_under": 80,
+        "show_missing": True,
+        "skip_covered": False,
+    }
+
+
+# Parametrized fixtures for different coverage configurations
+@pytest.fixture(
+    params=[
+        {"fail_under": 80, "branch": True},
+        {"fail_under": 90, "branch": False},
+        {"fail_under": 95, "branch": True, "show_missing": True},
+    ]
+)
+def parametrized_coverage(request, tmp_path) -> Generator[CoverageFixture, None, None]:
+    """Parametrized coverage fixture for testing different configurations.
+
+    Automatically runs tests with different coverage configurations
+    to validate behavior under various settings.
+
+    Usage:
+        def test_coverage_configs(parametrized_coverage):
+            # Test runs multiple times with different configs
+            pass
+    """
+    config = request.param
+    artifact_dir = tmp_path / f"coverage_{id(config)}"
+
+    fixture = CoverageFixture(config=config, artifact_dir=artifact_dir)
+
+    try:
+        fixture.setup()
+        yield fixture
+    finally:
+        fixture.teardown()
+
+
+# Pytest hooks for automatic coverage integration
+def pytest_configure(config):
+    """Configure pytest with coverage markers."""
+    config.addinivalue_line("markers", "coverage: mark test to run with coverage tracking")
+    config.addinivalue_line("markers", "no_coverage: mark test to skip coverage tracking")
+
+
+@pytest.fixture(autouse=True)
+def auto_coverage_marker(request):
+    """Automatically apply coverage to marked tests.
+
+    Tests marked with @pytest.mark.coverage will automatically
+    get coverage tracking without needing to explicitly use fixtures.
+    """
+    if request.node.get_closest_marker("coverage"):
+        # Test is marked for coverage - enable automatic tracking
+        if not request.node.get_closest_marker("no_coverage"):
+            # Create temporary coverage fixture
+            coverage_fixture = CoverageFixture()
+            try:
+                coverage_fixture.setup()
+                coverage_fixture.start_tracking()
+                yield
+            finally:
+                coverage_fixture.stop_tracking()
+                coverage_fixture.teardown()
+        else:
+            yield
+    else:
+        yield

provide/testkit/quality/coverage/reporter.py

@@ -0,0 +1,150 @@
+"""Coverage reporting utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..base import QualityResult
+
+
+class CoverageReporter:
+    """Specialized reporter for coverage results."""
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        """Initialize coverage reporter.
+
+        Args:
+            config: Reporter configuration
+        """
+        self.config = config or {}
+
+    def format_terminal_report(self, result: QualityResult) -> str:
+        """Format coverage result for terminal output.
+
+        Args:
+            result: Coverage result to format
+
+        Returns:
+            Formatted terminal report
+        """
+        lines = [
+            f"Coverage Report - {result.tool}",
+            "=" * 40,
+            f"Status: {'✅ PASSED' if result.passed else '❌ FAILED'}",
+        ]
+
+        if result.score is not None:
+            lines.append(f"Coverage: {result.score}%")
+
+        details = result.details
+        if "total_statements" in details:
+            lines.extend(
+                [
+                    f"Total Statements: {details.get('total_statements', 0)}",
+                    f"Missing Statements: {details.get('missing_statements', 0)}",
+                ]
+            )
+
+        if "branch_coverage" in details and details["branch_coverage"] is not None:
+            lines.append(f"Branch Coverage: {details['branch_coverage']}%")
+
+        if "threshold" in details:
+            lines.append(f"Threshold: {details['threshold']}%")
+
+        if result.execution_time:
+            lines.append(f"Execution Time: {result.execution_time:.2f}s")
+
+        return "\n".join(lines)
+
+    def format_json_report(self, result: QualityResult) -> dict[str, Any]:
+        """Format coverage result as JSON data.
+
+        Args:
+            result: Coverage result to format
+
+        Returns:
+            JSON-serializable report data
+        """
+        return {
+            "tool": result.tool,
+            "passed": result.passed,
+            "score": result.score,
+            "details": result.details,
+            "execution_time": result.execution_time,
+            "artifacts": [str(p) for p in result.artifacts],
+        }
+
+    def format_html_summary(self, result: QualityResult) -> str:
+        """Format coverage result as HTML summary.
+
+        Args:
+            result: Coverage result to format
+
+        Returns:
+            HTML summary
+        """
+        status_color = "green" if result.passed else "red"
+        status_text = "PASSED" if result.passed else "FAILED"
+
+        html_parts = [
+            '<div class="coverage-summary">',
+            "<h3>Coverage Report</h3>",
+            f'<p><span style="color: {status_color}">Status: {status_text}</span></p>',
+        ]
+
+        if result.score is not None:
+            html_parts.append(f"<p>Coverage: <strong>{result.score}%</strong></p>")
+
+        details = result.details
+        if "total_statements" in details:
+            html_parts.extend(
+                [
+                    f"<p>Total Statements: {details.get('total_statements', 0)}</p>",
+                    f"<p>Missing Statements: {details.get('missing_statements', 0)}</p>",
+                ]
+            )
+
+        html_parts.append("</div>")
+        return "\n".join(html_parts)
+
+    def generate_dashboard_data(self, result: QualityResult) -> dict[str, Any]:
+        """Generate data for coverage dashboard.
+
+        Args:
+            result: Coverage result
+
+        Returns:
+            Dashboard data structure
+        """
+        dashboard_data: dict[str, Any] = {
+            "title": "Code Coverage",
+            "status": "passed" if result.passed else "failed",
+            "primary_metric": {
+                "label": "Coverage",
+                "value": result.score,
+                "unit": "%",
+                "threshold": result.details.get("threshold", 0),
+            },
+            "secondary_metrics": [],
+        }
+
+        details = result.details
+        secondary_metrics = dashboard_data["secondary_metrics"]
+        if "total_statements" in details and isinstance(secondary_metrics, list):
+            secondary_metrics.extend(
+                [
+                    {"label": "Total Statements", "value": details.get("total_statements", 0)},
+                    {"label": "Missing Statements", "value": details.get("missing_statements", 0)},
+                ]
+            )
+
+        if (
+            "branch_coverage" in details
+            and details["branch_coverage"] is not None
+            and isinstance(secondary_metrics, list)
+        ):
+            secondary_metrics.append(
+                {"label": "Branch Coverage", "value": details["branch_coverage"], "unit": "%"}
+            )
+
+        return dashboard_data

provide/testkit/quality/coverage/tracker.py

@@ -0,0 +1,313 @@
+"""Coverage tracking implementation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import time
+from typing import Any
+
+try:
+    from coverage import Coverage
+
+    COVERAGE_AVAILABLE = True
+except ImportError:
+    COVERAGE_AVAILABLE = False
+    Coverage = None
+
+from ..base import QualityResult, QualityToolError
+
+
+class CoverageTracker:
+    """Wrapper for coverage.py library with testkit integration.
+
+    Provides high-level interface for coverage tracking with automatic
+    artifact management and integration with the quality framework.
+    """
+
+    def __init__(self, config: dict[str, Any] | None = None):
+        """Initialize coverage tracker.
+
+        Args:
+            config: Coverage configuration options
+        """
+        if not COVERAGE_AVAILABLE:
+            raise QualityToolError(
+                "Coverage.py not available. Install with: pip install coverage", tool="coverage"
+            )
+
+        self.config = config or {}
+        self.coverage: Coverage | None = None
+        self.is_running = False
+        self.artifact_dir: Path | None = None
+
+    def analyze(self, path: Path, **kwargs: Any) -> QualityResult:
+        """Run coverage analysis on the given path.
+
+        Args:
+            path: Path to analyze
+            **kwargs: Additional options including artifact_dir
+
+        Returns:
+            QualityResult with coverage data
+        """
+        self.artifact_dir = kwargs.get("artifact_dir", Path(".coverage"))
+        start_time = time.time()
+
+        try:
+            # If coverage is already running, get current data
+            if self.is_running and self.coverage:
+                self.stop()
+
+            # Start fresh coverage analysis
+            self.start()
+
+            # For analysis mode, we need to combine existing coverage data
+            # This is typically used when coverage was collected during test runs
+            self._load_existing_data()
+
+            # Generate report
+            result = self._create_result()
+            result.execution_time = time.time() - start_time
+
+            # Generate artifacts
+            self._generate_artifacts(result)
+
+            return result
+
+        except Exception as e:
+            return QualityResult(
+                tool="coverage",
+                passed=False,
+                details={"error": str(e), "error_type": type(e).__name__},
+                execution_time=time.time() - start_time,
+            )
+
+    def start(self) -> None:
+        """Start coverage tracking."""
+        if self.is_running:
+            return
+
+        coverage_config = self._build_coverage_config()
+        self.coverage = Coverage(**coverage_config)
+        self.coverage.start()
+        self.is_running = True
+
+    def stop(self) -> None:
+        """Stop coverage tracking and save data."""
+        if not self.is_running or not self.coverage:
+            return
+
+        self.coverage.stop()
+        self.coverage.save()
+        self.is_running = False
+
+    def get_coverage(self) -> float:
+        """Get current coverage percentage.
+
+        Returns:
+            Coverage percentage (0-100)
+        """
+        if not self.coverage:
+            return 0.0
+
+        try:
+            # Get coverage data
+            total = self.coverage.report(file=None, show_missing=False)
+            return round(total, 2)
+        except Exception:
+            return 0.0
+
+    def generate_report(self, format: str = "terminal") -> str:
+        """Generate coverage report.
+
+        Args:
+            format: Report format (terminal, html, xml, json)
+
+        Returns:
+            Report content (for terminal/json) or path (for html/xml)
+        """
+        if not self.coverage:
+            return "No coverage data available"
+
+        if format == "terminal":
+            return self._generate_terminal_report()
+        elif format == "html" and self.artifact_dir:
+            html_dir = self.artifact_dir / "htmlcov"
+            self.coverage.html_report(directory=str(html_dir))
+            return str(html_dir / "index.html")
+        elif format == "xml" and self.artifact_dir:
+            xml_file = self.artifact_dir / "coverage.xml"
+            self.coverage.xml_report(outfile=str(xml_file))
+            return str(xml_file)
+        elif format == "json" and self.artifact_dir:
+            json_file = self.artifact_dir / "coverage.json"
+            self.coverage.json_report(outfile=str(json_file))
+            return json_file.read_text()
+        else:
+            return f"Unsupported format: {format}"
+
+    def report(self, result: QualityResult, format: str = "terminal") -> str:
+        """Generate report from QualityResult (implements QualityTool protocol).
+
+        Args:
+            result: Coverage result
+            format: Report format
+
+        Returns:
+            Formatted report
+        """
+        if format == "terminal":
+            lines = [
+                f"Coverage Report - {result.tool}",
+                "=" * 40,
+                f"Status: {'✅ PASSED' if result.passed else '❌ FAILED'}",
+            ]
+
+            if result.score is not None:
+                lines.append(f"Coverage: {result.score}%")
+
+            if "total_statements" in result.details:
+                details = result.details
+                lines.extend(
+                    [
+                        f"Total Statements: {details.get('total_statements', 0)}",
+                        f"Missing Statements: {details.get('missing_statements', 0)}",
+                        f"Branch Coverage: {details.get('branch_coverage', 'N/A')}%",
+                    ]
+                )
+
+            return "\n".join(lines)
+
+        return str(result.details)
+
+    def _build_coverage_config(self) -> dict[str, Any]:
+        """Build coverage.py configuration."""
+        config = {
+            "branch": self.config.get("branch", True),
+            "source": self.config.get("source", ["src"]),
+            "omit": self.config.get(
+                "omit", ["*/tests/*", "*/test_*", "*/.venv/*", "*/venv/*", "*/__pycache__/*"]
+            ),
+        }
+
+        # Add data file configuration if artifact directory is set
+        if self.artifact_dir:
+            config["data_file"] = str(self.artifact_dir / ".coverage")
+
+        return config
+
+    def _load_existing_data(self) -> None:
+        """Load existing coverage data if available."""
+        if not self.coverage or not self.artifact_dir:
+            return
+
+        data_file = self.artifact_dir / ".coverage"
+        if data_file.exists():
+            try:
+                self.coverage.load()
+            except Exception:
+                # If loading fails, continue with fresh data
+                pass
+
+    def _create_result(self) -> QualityResult:
+        """Create QualityResult from current coverage data."""
+        if not self.coverage:
+            return QualityResult(tool="coverage", passed=False, details={"error": "No coverage instance"})
+
+        try:
+            # Get coverage percentage
+            coverage_percent = self.get_coverage()
+
+            # Get detailed metrics
+            total_statements = 0
+            missing_statements = 0
+            branch_coverage = None
+
+            # Access coverage data for detailed metrics
+            data = self.coverage.get_data()
+            if data:
+                try:
+                    # Count statements across all files
+                    for filename in data.measured_files():
+                        file_data = data.lines(filename)
+                        if file_data:
+                            total_statements += len(file_data)
+
+                    # Get missing statements
+                    if hasattr(self.coverage, "_analyze"):
+                        for filename in data.measured_files():
+                            try:
+                                analysis = self.coverage._analyze(filename)
+                                missing_statements += len(analysis.missing)
+                            except Exception:
+                                continue
+                except Exception:
+                    # Handle mock objects or other issues gracefully
+                    pass
+
+            # Calculate pass/fail based on configured threshold
+            threshold = self.config.get("fail_under", 0)
+            passed = coverage_percent >= threshold
+
+            return QualityResult(
+                tool="coverage",
+                passed=passed,
+                score=coverage_percent,
+                details={
+                    "total_statements": total_statements,
+                    "missing_statements": missing_statements,
+                    "branch_coverage": branch_coverage,
+                    "threshold": threshold,
+                },
+            )
+
+        except Exception as e:
+            return QualityResult(tool="coverage", passed=False, details={"error": str(e)})
+
+    def _generate_terminal_report(self) -> str:
+        """Generate terminal coverage report."""
+        if not self.coverage:
+            return "No coverage data available"
+
+        try:
+            from io import StringIO
+
+            output = StringIO()
+            self.coverage.report(file=output, show_missing=True)
+            return output.getvalue()
+        except Exception as e:
+            return f"Error generating report: {e}"
+
+    def _generate_artifacts(self, result: QualityResult) -> None:
+        """Generate coverage artifacts.
+
+        Args:
+            result: Result to add artifacts to
+        """
+        if not self.artifact_dir:
+            return
+
+        self.artifact_dir.mkdir(parents=True, exist_ok=True)
+
+        try:
+            # Generate HTML report
+            html_dir = self.artifact_dir / "htmlcov"
+            self.coverage.html_report(directory=str(html_dir))
+            if html_dir.exists():
+                result.artifacts.append(html_dir / "index.html")
+
+            # Generate XML report
+            xml_file = self.artifact_dir / "coverage.xml"
+            self.coverage.xml_report(outfile=str(xml_file))
+            if xml_file.exists():
+                result.artifacts.append(xml_file)
+
+            # Generate terminal report
+            terminal_file = self.artifact_dir / "coverage.txt"
+            terminal_report = self._generate_terminal_report()
+            terminal_file.write_text(terminal_report)
+            result.artifacts.append(terminal_file)
+
+        except Exception as e:
+            # Add error to result details but don't fail
+            result.details["artifact_error"] = str(e)