pytest-api-cov 0.1.0__py3-none-any.whl

pytest_api_cov/__init__.py

@@ -0,0 +1 @@
+# This file makes the pytest_api_cov directory a Python package

pytest_api_cov/cli.py

@@ -0,0 +1,192 @@
+"""CLI commands for setup and configuration."""
+
+import argparse
+import os
+import sys
+from typing import Optional
+
+
+def detect_framework_and_app() -> Optional[tuple[str, str, str]]:
+    """
+    Detect framework and app location.
+    Returns (framework, file_path, app_variable) or None.
+    """
+    common_patterns = [
+        ("app.py", ["app", "application", "main"]),
+        ("main.py", ["app", "application", "main"]),
+        ("server.py", ["app", "application", "server"]),
+        ("wsgi.py", ["app", "application"]),
+        ("asgi.py", ["app", "application"]),
+    ]
+
+    for filename, attr_names in common_patterns:
+        if os.path.exists(filename):
+            try:
+                with open(filename, "r") as f:
+                    content = f.read()
+
+                if "from fastapi import" in content or "import fastapi" in content:
+                    framework = "FastAPI"
+                elif "from flask import" in content or "import flask" in content:
+                    framework = "Flask"
+                else:
+                    continue
+
+                for attr_name in attr_names:
+                    if f"{attr_name} = " in content:
+                        return framework, filename, attr_name
+
+            except Exception:
+                continue
+
+    return None
+
+
+def generate_conftest_content(framework: str, file_path: str, app_variable: str) -> str:
+    """Generate conftest.py content based on detected framework."""
+    module_name = file_path[:-3]  # Remove .py
+
+    return f'''"""conftest.py - Auto-generated by pytest-api-cov init"""
+
+import pytest
+
+# Import your {framework} app
+from {module_name} import {app_variable}
+
+
+@pytest.fixture
+def app():
+    """Provide the {framework} app for API coverage testing."""
+    return {app_variable}
+'''
+
+
+def generate_pyproject_config(framework: str) -> str:
+    """Generate pyproject.toml configuration section."""
+    return """
+# pytest-api-cov configuration
+[tool.pytest_api_cov]
+# Fail if coverage is below this percentage (optional)
+# fail_under = 80.0
+
+# Show different endpoint types in report
+show_uncovered_endpoints = true
+show_covered_endpoints = false
+show_excluded_endpoints = false
+
+# Exclude endpoints matching these patterns (optional)
+# exclusion_patterns = [
+#     "/health",
+#     "/metrics",
+#     "/docs",
+# ]
+
+# Save JSON report to file (optional)
+# report_path = "api_coverage.json"
+
+# Force Unicode symbols in terminal output (optional)
+# force_sugar = true
+"""
+
+
+def cmd_init() -> int:
+    """Initialize pytest-api-cov setup in current directory."""
+    print("🚀 pytest-api-cov Setup Wizard")
+    print("=" * 40)
+
+    detection_result = detect_framework_and_app()
+
+    if detection_result:
+        framework, file_path, app_variable = detection_result
+        print(f"✅ Detected {framework} app in {file_path} (variable: {app_variable})")
+
+        conftest_exists = os.path.exists("conftest.py")
+        if conftest_exists:
+            print("⚠️  conftest.py already exists")
+            create_conftest = input("Do you want to overwrite it? (y/N): ").lower().startswith("y")
+        else:
+            create_conftest = True
+
+        if create_conftest:
+            conftest_content = generate_conftest_content(framework, file_path, app_variable)
+            with open("conftest.py", "w") as f:
+                f.write(conftest_content)
+            print("✅ Created conftest.py")
+
+        pyproject_exists = os.path.exists("pyproject.toml")
+        if pyproject_exists:
+            print("ℹ️  pyproject.toml already exists")
+            print("Add this configuration to your pyproject.toml:")
+            print(generate_pyproject_config(framework))
+        else:
+            create_pyproject = input("Create pyproject.toml with pytest-api-cov config? (Y/n): ").lower()
+            if not create_pyproject.startswith("n"):
+                pyproject_content = f"""[project]
+name = "your-project"
+version = "0.1.0"
+
+{generate_pyproject_config(framework)}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+"""
+                with open("pyproject.toml", "w") as f:
+                    f.write(pyproject_content)
+                print("✅ Created pyproject.toml")
+
+        print()
+        print("🎉 Setup complete!")
+        print()
+        print("Next steps:")
+        print("1. Write your tests using the 'client' fixture")
+        print("2. Run: pytest --api-cov-report")
+        print()
+        print("Example test:")
+        print("""
+def test_root_endpoint(client):
+    response = client.get("/")
+    assert response.status_code == 200
+""")
+
+    else:
+        print("❌ No FastAPI or Flask app detected in common locations")
+        print()
+        print("Please ensure you have one of these files with a Flask/FastAPI app:")
+        print("• app.py")
+        print("• main.py")
+        print("• server.py")
+        print()
+        print("Example app.py:")
+        print("""
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/")
+def read_root():
+    return {"message": "Hello World"}
+""")
+        return 1
+
+    return 0
+
+
+def main() -> int:
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(prog="pytest-api-cov", description="pytest API coverage plugin CLI tools")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    subparsers.add_parser("init", help="Initialize pytest-api-cov setup")
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        return cmd_init()
+    else:
+        parser.print_help()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pytest_api_cov/config.py

@@ -0,0 +1,77 @@
+"""Configuration handling for the API coverage report."""
+
+import sys
+from typing import Any, Dict, List, Optional
+
+import tomli
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ApiCoverageReportConfig(BaseModel):
+    """Configuration model for API coverage reporting."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    fail_under: Optional[float] = Field(None, alias="api-cov-fail-under")
+    show_uncovered_endpoints: bool = Field(True, alias="api-cov-show-uncovered-endpoints")
+    show_covered_endpoints: bool = Field(False, alias="api-cov-show-covered-endpoints")
+    show_excluded_endpoints: bool = Field(False, alias="api-cov-show-excluded-endpoints")
+    exclusion_patterns: List[str] = Field([], alias="api-cov-exclusion-patterns")
+    report_path: Optional[str] = Field(None, alias="api-cov-report-path")
+    force_sugar: bool = Field(False, alias="api-cov-force-sugar")
+    force_sugar_disabled: bool = Field(False, alias="api-cov-force-sugar-disabled")
+
+
+def read_toml_config() -> Dict[str, Any]:
+    """Read the [tool.pytest_api_cov] section from pyproject.toml."""
+    try:
+        with open("pyproject.toml", "rb") as f:
+            toml_config = tomli.load(f)
+            return toml_config.get("tool", {}).get("pytest_api_cov", {})  # type: ignore[no-any-return]
+    except (FileNotFoundError, tomli.TOMLDecodeError):
+        return {}
+
+
+def read_session_config(session_config: Any) -> Dict[str, Any]:
+    """Read configuration from pytest session config (command-line flags)."""
+    cli_options = {
+        "api-cov-fail-under": "fail_under",
+        "api-cov-show-uncovered-endpoints": "show_uncovered_endpoints",
+        "api-cov-show-covered-endpoints": "show_covered_endpoints",
+        "api-cov-show-excluded-endpoints": "show_excluded_endpoints",
+        "api-cov-exclusion-patterns": "exclusion_patterns",
+        "api-cov-report-path": "report_path",
+        "api-cov-force-sugar": "force_sugar",
+        "api-cov-force-sugar-disabled": "force_sugar_disabled",
+    }
+    config = {}
+    for opt, key in cli_options.items():
+        value = session_config.getoption(f"--{opt}")
+        if value is not None and value != [] and value is not False:
+            config[key] = value
+    return config
+
+
+def supports_unicode() -> bool:
+    """Check if the environment supports Unicode characters."""
+    if not sys.stdout.isatty():
+        return False
+    return bool(sys.stdout) and sys.stdout.encoding.lower() in ["utf-8", "utf8"]
+
+
+def get_pytest_api_cov_report_config(session_config: Any) -> ApiCoverageReportConfig:
+    """
+    Get the final API coverage configuration by merging sources.
+    Priority: CLI > pyproject.toml > Defaults
+    """
+    toml_config = read_toml_config()
+    cli_config = read_session_config(session_config)
+
+    final_config = {**toml_config, **cli_config}
+
+    if final_config.get("force_sugar_disabled"):
+        final_config["force_sugar"] = False
+    elif "force_sugar" not in final_config:
+        final_config["force_sugar"] = supports_unicode()
+
+    return ApiCoverageReportConfig.model_validate(final_config)

pytest_api_cov/frameworks.py

@@ -0,0 +1,80 @@
+"""Framework adapters for Flask and FastAPI."""
+
+from typing import TYPE_CHECKING, Any, List, Optional
+
+if TYPE_CHECKING:
+    from .models import ApiCallRecorder
+
+
+class BaseAdapter:
+    def __init__(self, app: Any):
+        self.app = app
+
+    def get_endpoints(self) -> List[str]:
+        """Return a list of all endpoint paths."""
+        raise NotImplementedError
+
+    def get_tracked_client(self, recorder: Optional["ApiCallRecorder"], test_name: str) -> Any:
+        """Return a patched test client that records calls."""
+        raise NotImplementedError
+
+
+class FlaskAdapter(BaseAdapter):
+    def get_endpoints(self) -> List[str]:
+        excluded_rules = ("/static/<path:filename>",)
+        return sorted([rule.rule for rule in self.app.url_map.iter_rules() if rule.rule not in excluded_rules])
+
+    def get_tracked_client(self, recorder: Optional["ApiCallRecorder"], test_name: str) -> Any:
+        from flask.testing import FlaskClient
+
+        if recorder is None:
+            return self.app.test_client()
+
+        class TrackingFlaskClient(FlaskClient):
+            def open(self, *args: Any, **kwargs: Any) -> Any:
+                path = kwargs.get("path") or (args[0] if args else None)
+                if path and hasattr(self.application.url_map, "bind"):
+                    try:
+                        endpoint_name, _ = self.application.url_map.bind("").match(path, method=kwargs.get("method"))
+                        endpoint_rule_string = next(self.application.url_map.iter_rules(endpoint_name)).rule
+                        recorder.record_call(endpoint_rule_string, test_name)  # type: ignore[union-attr]
+                    except Exception:
+                        pass
+                return super().open(*args, **kwargs)
+
+        return TrackingFlaskClient(self.app, self.app.response_class)
+
+
+class FastAPIAdapter(BaseAdapter):
+    def get_endpoints(self) -> List[str]:
+        from fastapi.routing import APIRoute
+
+        return sorted([route.path for route in self.app.routes if isinstance(route, APIRoute)])
+
+    def get_tracked_client(self, recorder: Optional["ApiCallRecorder"], test_name: str) -> Any:
+        from starlette.testclient import TestClient
+
+        if recorder is None:
+            return TestClient(self.app)
+
+        class TrackingFastAPIClient(TestClient):
+            def send(self, *args: Any, **kwargs: Any) -> Any:
+                request = args[0]
+                if recorder is not None:
+                    recorder.record_call(request.url.path, test_name)
+                return super().send(*args, **kwargs)
+
+        return TrackingFastAPIClient(self.app)
+
+
+def get_framework_adapter(app: Any) -> BaseAdapter:
+    """Detects the framework and returns the appropriate adapter."""
+    app_type = type(app).__name__
+    module_name = getattr(type(app), "__module__", "").split(".")[0]
+
+    if module_name == "flask" and app_type == "Flask":
+        return FlaskAdapter(app)
+    elif module_name == "fastapi" and app_type == "FastAPI":
+        return FastAPIAdapter(app)
+
+    raise TypeError(f"Unsupported application type: {app_type}. pytest-api-coverage supports Flask and FastAPI.")

pytest_api_cov/models.py

@@ -0,0 +1,122 @@
+"""Data models for pytest-api-cov."""
+
+from typing import Any, Dict, Iterable, List, Set, Tuple
+
+from pydantic import BaseModel, Field
+
+
+class ApiCallRecorder(BaseModel):
+    """Model for tracking API endpoint calls during testing."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    calls: Dict[str, Set[str]] = Field(default_factory=dict)
+
+    def record_call(self, endpoint: str, test_name: str) -> None:
+        """Record that a test called an endpoint."""
+        if endpoint not in self.calls:
+            self.calls[endpoint] = set()
+        self.calls[endpoint].add(test_name)
+
+    def get_called_endpoints(self) -> List[str]:
+        """Get list of all endpoints that have been called."""
+        return list(self.calls.keys())
+
+    def get_callers(self, endpoint: str) -> Set[str]:
+        """Get the set of test names that called a specific endpoint."""
+        return self.calls.get(endpoint, set())
+
+    def merge(self, other: "ApiCallRecorder") -> None:
+        """Merge another recorder's data into this one."""
+        for endpoint, callers in other.calls.items():
+            if endpoint not in self.calls:
+                self.calls[endpoint] = set()
+            self.calls[endpoint].update(callers)
+
+    def to_serializable(self) -> Dict[str, List[str]]:
+        """Convert to a serializable format (sets -> lists) for worker communication."""
+        return {endpoint: list(callers) for endpoint, callers in self.calls.items()}
+
+    @classmethod
+    def from_serializable(cls, data: Dict[str, List[str]]) -> "ApiCallRecorder":
+        """Create from serializable format (lists -> sets)."""
+        calls = {endpoint: set(callers) for endpoint, callers in data.items()}
+        return cls(calls=calls)
+
+    def __len__(self) -> int:
+        """Return number of endpoints recorded."""
+        return len(self.calls)
+
+    def __contains__(self, endpoint: str) -> bool:
+        """Check if an endpoint has been recorded."""
+        return endpoint in self.calls
+
+    def items(self) -> Iterable[Tuple[str, Set[str]]]:
+        """Iterate over endpoint, callers pairs."""
+        return self.calls.items()
+
+    def keys(self) -> Iterable[str]:
+        """Get all recorded endpoints."""
+        return self.calls.keys()
+
+    def values(self) -> Iterable[Set[str]]:
+        """Get all caller sets."""
+        return self.calls.values()
+
+
+class EndpointDiscovery(BaseModel):
+    """Model for discovered API endpoints."""
+
+    endpoints: List[str] = Field(default_factory=list)
+    discovery_source: str = Field(default="unknown")
+
+    def add_endpoint(self, endpoint: str) -> None:
+        """Add a discovered endpoint."""
+        if endpoint not in self.endpoints:
+            self.endpoints.append(endpoint)
+
+    def merge(self, other: "EndpointDiscovery") -> None:
+        """Merge another discovery's endpoints into this one."""
+        for endpoint in other.endpoints:
+            self.add_endpoint(endpoint)
+
+    def __len__(self) -> int:
+        """Return number of discovered endpoints."""
+        return len(self.endpoints)
+
+    def __iter__(self) -> Iterable[str]:  # type: ignore[override]
+        """Iterate over discovered endpoints."""
+        return iter(self.endpoints)
+
+
+class SessionData(BaseModel):
+    """Model for session-level API coverage data."""
+
+    recorder: ApiCallRecorder = Field(default_factory=ApiCallRecorder)
+    discovered_endpoints: EndpointDiscovery = Field(default_factory=EndpointDiscovery)
+
+    def record_call(self, endpoint: str, test_name: str) -> None:
+        """Record an API call."""
+        self.recorder.record_call(endpoint, test_name)
+
+    def add_discovered_endpoint(self, endpoint: str, source: str = "unknown") -> None:
+        """Add a discovered endpoint."""
+        if not self.discovered_endpoints.endpoints:
+            self.discovered_endpoints.discovery_source = source
+        self.discovered_endpoints.add_endpoint(endpoint)
+
+    def merge_worker_data(self, worker_recorder: Dict[str, Any], worker_endpoints: List[str]) -> None:
+        """Merge data from a worker process."""
+        if isinstance(worker_recorder, dict):
+            all_lists = worker_recorder and all(isinstance(v, list) for v in worker_recorder.values())
+            if all_lists:
+                worker_api_recorder = ApiCallRecorder.from_serializable(worker_recorder)
+            else:
+                calls = {k: set(v) if isinstance(v, (list, set)) else {v} for k, v in worker_recorder.items()}
+                worker_api_recorder = ApiCallRecorder(calls=calls)
+
+            self.recorder.merge(worker_api_recorder)
+
+        if worker_endpoints:
+            worker_discovery = EndpointDiscovery(endpoints=worker_endpoints, discovery_source="worker")
+            self.discovered_endpoints.merge(worker_discovery)