pytest-api-cov 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

pytest_api_cov/__init__.py

@@ -2,6 +2,7 @@
 
 try:
     from importlib.metadata import version
+
     __version__ = version("pytest-api-cov")
 except ImportError:
     __version__ = "unknown"

pytest_api_cov/cli.py

@@ -56,22 +56,36 @@ def generate_conftest_content(framework: str, file_path: str, app_variable: str)
 
 import pytest
 
-# Import your {framework} app
+# Import your {framework} app from anywhere in your project
 from {module_path} import {app_variable}
 
 
 @pytest.fixture
-def client():
-    """Provide the {framework} client for API coverage testing.
-    
-    In your test:
-    ```
-    def test_root_endpoint(client):
-        response = client.get("/")
-        assert response.status_code == 200
-    ```
+def app():
+    """Provide the {framework} app for API coverage testing.
+
+    You can import from any location - just change the import path above
+    to match your project structure.
     """
     return {app_variable}
+
+
+# The plugin will automatically create a 'coverage_client' fixture that uses your 'app' fixture
+# You can use either:
+# - def test_endpoint(app): ...  # Direct app access
+# - def test_endpoint(coverage_client): ...  # Test client with API coverage tracking
+#
+# To wrap an existing custom fixture instead, specify the fixture name in pyproject.toml:
+# [tool.pytest_api_cov]
+# client_fixture_name = "my_custom_client"
+#
+# Example custom fixture:
+# @pytest.fixture
+# def my_custom_client(app):
+#     client = app.test_client()  # Flask
+#     # or client = TestClient(app)  # FastAPI
+#     # Add custom setup here (auth headers, etc.)
+#     return client
 '''
 
 
@@ -100,6 +114,9 @@ show_excluded_endpoints = false
 
 # Force Unicode symbols in terminal output (optional)
 # force_sugar = true
+
+# Wrap an existing custom test client fixture with coverage tracking (optional)
+# client_fixture_name = "my_custom_client"
 """
 
 
@@ -152,13 +169,13 @@ testpaths = ["tests"]
         print("🎉 Setup complete!")
         print()
         print("Next steps:")
-        print("1. Write your tests using the 'client' fixture")
+        print("1. Write your tests using the 'coverage_client' fixture")
         print("2. Run: pytest --api-cov-report")
         print()
         print("Example test:")
         print("""
-def test_root_endpoint(client):
-    response = client.get("/")
+def test_root_endpoint(coverage_client):
+    response = coverage_client.get("/")
     assert response.status_code == 200
 """)
 

pytest_api_cov/config.py

@@ -20,6 +20,7 @@ class ApiCoverageReportConfig(BaseModel):
     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")
+    client_fixture_name: str = Field("coverage_client", alias="api-cov-client-fixture-name")
 
 
 def read_toml_config() -> Dict[str, Any]:
@@ -43,6 +44,7 @@ def read_session_config(session_config: Any) -> Dict[str, Any]:
         "api-cov-report-path": "report_path",
         "api-cov-force-sugar": "force_sugar",
         "api-cov-force-sugar-disabled": "force_sugar_disabled",
+        "api-cov-client-fixture-name": "client_fixture_name",
     }
     config = {}
     for opt, key in cli_options.items():

pytest_api_cov/plugin.py

@@ -1,270 +1,374 @@
-"""pytest plugin for API coverage tracking."""
-
-import importlib
-import importlib.util
-import logging
-import os
-from typing import Any, Optional
-
-import pytest
-
-from .config import get_pytest_api_cov_report_config
-from .frameworks import get_framework_adapter
-from .models import SessionData
-from .pytest_flags import add_pytest_api_cov_flags
-from .report import generate_pytest_api_cov_report
-
-logger = logging.getLogger(__name__)
-
-
-def is_supported_framework(app: Any) -> bool:
-    """Check if the app is a supported framework (Flask or FastAPI)."""
-    if app is None:
-        return False
-
-    app_type = type(app).__name__
-    module_name = getattr(type(app), "__module__", "").split(".")[0]
-
-    return (module_name == "flask" and app_type == "Flask") or (module_name == "fastapi" and app_type == "FastAPI")
-
-
-def auto_discover_app() -> Optional[Any]:
-    """Automatically discover Flask/FastAPI apps in common locations."""
-    logger.debug("> Auto-discovering app in common locations...")
-
-    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):
-            logger.debug(f"> Found {filename}, checking for app variables...")
-            try:
-                module_name = filename[:-3]  # .py extension
-                spec = importlib.util.spec_from_file_location(module_name, filename)
-                if spec and spec.loader:
-                    module = importlib.util.module_from_spec(spec)
-                    spec.loader.exec_module(module)
-
-                    for attr_name in attr_names:
-                        if hasattr(module, attr_name):
-                            app = getattr(module, attr_name)
-                            if is_supported_framework(app):
-                                logger.info(
-                                    f"✅ Auto-discovered {type(app).__name__} app in {filename} as '{attr_name}'"
-                                )
-                                return app
-                            else:
-                                logger.debug(f"> Found '{attr_name}' in {filename} but it's not a supported framework")
-
-            except Exception as e:
-                logger.debug(f"> Could not import {filename}: {e}")
-                continue
-
-    logger.debug("> No app auto-discovered")
-    return None
-
-
-def get_helpful_error_message() -> str:
-    """Generate a helpful error message for setup guidance."""
-    return """
-🚫 No API app found!
-
-Quick Setup Options:
-
-Option 1 - Auto-discovery (Recommended):
-  Place your FastAPI/Flask app in one of these files:
-  • app.py (with variable named 'app', 'application', or 'main')
-  • main.py (with variable named 'app', 'application', or 'main')
-  • server.py (with variable named 'app', 'application', or 'server')
-
-  Example app.py:
-    from fastapi import FastAPI
-    app = FastAPI()  # <- Plugin will auto-discover this
-
-Option 2 - Manual fixture:
-  Create conftest.py with:
-
-    import pytest
-    from your_module import your_app
-
-    @pytest.fixture
-    def app():
-        return your_app
-
-Then run: pytest --api-cov-report
-
-Need help? Run: pytest-api-cov init (for setup wizard)
-"""
-
-
-def pytest_addoption(parser: pytest.Parser) -> None:
-    """Add API coverage flags to the pytest parser."""
-    add_pytest_api_cov_flags(parser)
-
-
-def pytest_configure(config: pytest.Config) -> None:
-    """Configure the pytest session and logging."""
-    if config.getoption("--api-cov-report"):
-        verbosity = config.option.verbose
-
-        if verbosity >= 2:  # -vv or more
-            log_level = logging.DEBUG
-        elif verbosity >= 1:  # -v
-            log_level = logging.INFO
-        else:
-            log_level = logging.WARNING
-
-        logger.setLevel(log_level)
-
-        if not logger.handlers:
-            handler = logging.StreamHandler()
-            handler.setLevel(log_level)
-            formatter = logging.Formatter("%(message)s")
-            handler.setFormatter(formatter)
-            logger.addHandler(handler)
-
-        logger.info("Initializing API coverage plugin...")
-
-    if config.pluginmanager.hasplugin("xdist"):
-        config.pluginmanager.register(DeferXdistPlugin(), "defer_xdist_plugin")
-
-
-def pytest_sessionstart(session: pytest.Session) -> None:
-    """Initialize the call recorder at the start of the session."""
-    if session.config.getoption("--api-cov-report"):
-        session.api_coverage_data = SessionData()  # type: ignore[attr-defined]
-
-
-@pytest.fixture
-def client(request: pytest.FixtureRequest) -> Any:
-    """
-    Smart auto-discovering test client that records API calls for coverage.
-
-    Tries to find an 'app' fixture first, then auto-discovers apps in common locations.
-    """
-    session = request.node.session
-
-    if not session.config.getoption("--api-cov-report"):
-        pytest.skip("API coverage not enabled. Use --api-cov-report flag.")
-
-    app = None
-    try:
-        app = request.getfixturevalue("app")
-        logger.debug("> Found 'app' fixture")
-    except pytest.FixtureLookupError:
-        logger.debug("> No 'app' fixture found, trying auto-discovery...")
-        app = auto_discover_app()
-
-    if app is None:
-        helpful_msg = get_helpful_error_message()
-        print(helpful_msg)
-        pytest.skip("No API app found. See error message above for setup guidance.")
-
-    if not is_supported_framework(app):
-        pytest.skip(f"Unsupported framework: {type(app).__name__}. pytest-api-coverage supports Flask and FastAPI.")
-
-    try:
-        adapter = get_framework_adapter(app)
-    except TypeError as e:
-        pytest.skip(f"Framework detection failed: {e}")
-
-    coverage_data = getattr(session, "api_coverage_data", None)
-    if coverage_data is None:
-        pytest.skip("API coverage data not initialized. This should not happen.")
-
-    if not coverage_data.discovered_endpoints.endpoints:
-        try:
-            endpoints = adapter.get_endpoints()
-            framework_name = type(app).__name__
-            for endpoint in endpoints:
-                coverage_data.add_discovered_endpoint(endpoint, f"{framework_name.lower()}_adapter")
-            logger.info(f"> pytest-api-coverage: Discovered {len(endpoints)} endpoints.")
-            logger.debug(f"> Discovered endpoints: {endpoints}")
-        except Exception as e:
-            logger.warning(f"> pytest-api-coverage: Could not discover endpoints. Error: {e}")
-
-    client = adapter.get_tracked_client(coverage_data.recorder, request.node.name)
-    yield client
-
-
-def pytest_sessionfinish(session: pytest.Session) -> None:
-    """Generate the API coverage report at the end of the session."""
-    if session.config.getoption("--api-cov-report"):
-        coverage_data = getattr(session, "api_coverage_data", None)
-        if coverage_data is None:
-            logger.warning("> No API coverage data found. Plugin may not have been properly initialized.")
-            return
-
-        logger.debug(f"> pytest-api-coverage: Generating report for {len(coverage_data.recorder)} recorded endpoints.")
-        if hasattr(session.config, "workeroutput"):
-            serializable_recorder = coverage_data.recorder.to_serializable()
-            session.config.workeroutput["api_call_recorder"] = serializable_recorder
-            session.config.workeroutput["discovered_endpoints"] = coverage_data.discovered_endpoints.endpoints
-            logger.debug("> Sent API call data and discovered endpoints to master process")
-        else:
-            logger.debug("> No workeroutput found, generating report for master data.")
-
-            worker_recorder_data = getattr(session.config, "worker_api_call_recorder", {})
-            worker_endpoints = getattr(session.config, "worker_discovered_endpoints", [])
-
-            # Merge worker data into session data
-            if worker_recorder_data or worker_endpoints:
-                coverage_data.merge_worker_data(worker_recorder_data, worker_endpoints)
-                logger.debug(f"> Merged worker data: {len(worker_recorder_data)} endpoints")
-
-            logger.debug(f"> Final merged data: {len(coverage_data.recorder)} recorded endpoints")
-            logger.debug(f"> Using discovered endpoints: {coverage_data.discovered_endpoints.endpoints}")
-
-            api_cov_config = get_pytest_api_cov_report_config(session.config)
-            status = generate_pytest_api_cov_report(
-                api_cov_config=api_cov_config,
-                called_data=coverage_data.recorder.calls,
-                discovered_endpoints=coverage_data.discovered_endpoints.endpoints,
-            )
-            if session.exitstatus == 0:
-                session.exitstatus = status
-
-        if hasattr(session, "api_coverage_data"):
-            delattr(session, "api_coverage_data")
-
-        if hasattr(session.config, "worker_api_call_recorder"):
-            delattr(session.config, "worker_api_call_recorder")
-
-
-class DeferXdistPlugin:
-    """Simple class to defer pytest-xdist hook until we know it is installed."""
-
-    def pytest_testnodedown(self, node: Any) -> None:
-        """Collect API call data from each worker as they finish."""
-        logger.debug("> pytest-api-coverage: Worker node down.")
-        worker_data = node.workeroutput.get("api_call_recorder", {})
-        discovered_endpoints = node.workeroutput.get("discovered_endpoints", [])
-        logger.debug(f"> Worker data: {worker_data}")
-        logger.debug(f"> Worker discovered endpoints: {discovered_endpoints}")
-
-        # Merge API call data
-        if worker_data:
-            logger.debug("> Worker data found, merging with current data.")
-            current = getattr(node.config, "worker_api_call_recorder", {})
-            logger.debug(f"> Current data before merge: {current}")
-
-            # Merge the worker data into current
-            for endpoint, calls in worker_data.items():
-                if endpoint not in current:
-                    current[endpoint] = set()
-                elif not isinstance(current[endpoint], set):
-                    current[endpoint] = set(current[endpoint])
-                current[endpoint].update(calls)
-                logger.debug(f"> Updated endpoint {endpoint} with calls: {calls}")
-
-            node.config.worker_api_call_recorder = current
-            logger.debug(f"> Updated current data: {current}")
-
-        if discovered_endpoints and not getattr(node.config, "worker_discovered_endpoints", []):
-            node.config.worker_discovered_endpoints = discovered_endpoints
-            logger.debug(f"> Set discovered endpoints from worker: {discovered_endpoints}")
+"""pytest plugin for API coverage tracking."""
+
+import importlib
+import importlib.util
+import logging
+import os
+from typing import Any, Optional
+
+import pytest
+
+from .config import get_pytest_api_cov_report_config
+from .frameworks import get_framework_adapter
+from .models import SessionData
+from .pytest_flags import add_pytest_api_cov_flags
+from .report import generate_pytest_api_cov_report
+
+logger = logging.getLogger(__name__)
+
+
+def is_supported_framework(app: Any) -> bool:
+    """Check if the app is a supported framework (Flask or FastAPI)."""
+    if app is None:
+        return False
+
+    app_type = type(app).__name__
+    module_name = getattr(type(app), "__module__", "").split(".")[0]
+
+    return (module_name == "flask" and app_type == "Flask") or (module_name == "fastapi" and app_type == "FastAPI")
+
+
+def auto_discover_app() -> Optional[Any]:
+    """Automatically discover Flask/FastAPI apps in common locations."""
+    logger.debug("> Auto-discovering app in common locations...")
+
+    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"]),
+    ]
+
+    found_apps = []  # Track all discovered apps
+    found_files = []  # Track all files that exist
+
+    for filename, attr_names in common_patterns:
+        if os.path.exists(filename):
+            found_files.append(filename)
+            logger.debug(f"> Found {filename}, checking for app variables...")
+            try:
+                module_name = filename[:-3]  # .py extension
+                spec = importlib.util.spec_from_file_location(module_name, filename)
+                if spec and spec.loader:
+                    module = importlib.util.module_from_spec(spec)
+                    spec.loader.exec_module(module)
+
+                    for attr_name in attr_names:
+                        if hasattr(module, attr_name):
+                            app = getattr(module, attr_name)
+                            if is_supported_framework(app):
+                                found_apps.append((filename, attr_name, type(app).__name__))
+                                # Return the first valid app found, but log what we're doing
+                                if len(found_apps) == 1:
+                                    logger.info(
+                                        f"✅ Auto-discovered {type(app).__name__} app in {filename} as '{attr_name}'"
+                                    )
+                                    # Check if there are more files to scan
+                                    remaining_files = [
+                                        f
+                                        for f in [
+                                            p[0]
+                                            for p in common_patterns[common_patterns.index((filename, attr_names)) :]
+                                        ]
+                                        if os.path.exists(f) and f != filename
+                                    ]
+                                    if remaining_files:
+                                        logger.debug(
+                                            f"> Note: Also found files {remaining_files} but using first discovered app"
+                                        )
+                                        logger.debug(
+                                            "> To use a different app, create a conftest.py with an 'app' fixture"
+                                        )
+                                    return app
+                            else:
+                                logger.debug(f"> Found '{attr_name}' in {filename} but it's not a supported framework")
+
+            except Exception as e:
+                logger.debug(f"> Could not import {filename}: {e}")
+                continue
+
+    # If we get here, no apps were found
+    if found_files:
+        logger.debug(f"> Found files {found_files} but no supported Flask/FastAPI apps in them")
+        logger.debug("> If your app is in one of these files with a different variable name,")
+        logger.debug("> create a conftest.py with an 'app' fixture to specify it")
+
+    logger.debug("> No app auto-discovered")
+    return None
+
+
+def get_helpful_error_message() -> str:
+    """Generate a helpful error message for setup guidance."""
+    return """
+🚫 No API app found!
+
+Quick Setup Options:
+
+Option 1 - Auto-discovery (Zero Config):
+  Place your FastAPI/Flask app in one of these files:
+  • app.py (with variable named 'app', 'application', or 'main')
+  • main.py (with variable named 'app', 'application', or 'main')
+  • server.py (with variable named 'app', 'application', or 'server')
+
+  Example app.py:
+    from fastapi import FastAPI
+    app = FastAPI()  # <- Plugin will auto-discover this
+
+Option 2 - Custom Location or Override Auto-discovery:
+  Create conftest.py to specify exactly which app to use:
+
+    import pytest
+    from my_project.api.server import my_app  # Any import path!
+    # or from app import my_real_app  # Override auto-discovery
+
+    @pytest.fixture
+    def app():
+        return my_app
+
+  This works for:
+  • Apps in custom locations
+  • Multiple app files (specify which one to use)
+  • Different variable names in standard files
+
+Option 3 - Setup Wizard:
+  Run: pytest-api-cov init
+
+Then run: pytest --api-cov-report
+"""
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """Add API coverage flags to the pytest parser."""
+    add_pytest_api_cov_flags(parser)
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """Configure the pytest session and logging."""
+    if config.getoption("--api-cov-report"):
+        verbosity = config.option.verbose
+
+        if verbosity >= 2:  # -vv or more
+            log_level = logging.DEBUG
+        elif verbosity >= 1:  # -v
+            log_level = logging.INFO
+        else:
+            log_level = logging.WARNING
+
+        logger.setLevel(log_level)
+
+        if not logger.handlers:
+            handler = logging.StreamHandler()
+            handler.setLevel(log_level)
+            formatter = logging.Formatter("%(message)s")
+            handler.setFormatter(formatter)
+            logger.addHandler(handler)
+
+        logger.info("Initializing API coverage plugin...")
+
+    if config.pluginmanager.hasplugin("xdist"):
+        config.pluginmanager.register(DeferXdistPlugin(), "defer_xdist_plugin")
+
+
+def pytest_sessionstart(session: pytest.Session) -> None:
+    """Initialize the call recorder at the start of the session."""
+    if session.config.getoption("--api-cov-report"):
+        session.api_coverage_data = SessionData()  # type: ignore[attr-defined]
+
+
+def wrap_client_with_coverage(client: Any, recorder: Any, test_name: str) -> Any:
+    """Wrap an existing test client with coverage tracking."""
+
+    class CoverageWrapper:
+        def __init__(self, wrapped_client: Any):
+            self._wrapped = wrapped_client
+
+        def __getattr__(self, name: str) -> Any:
+            attr = getattr(self._wrapped, name)
+            if name in ["get", "post", "put", "delete", "patch", "head", "options"]:
+
+                def tracked_method(*args: Any, **kwargs: Any) -> Any:
+                    response = attr(*args, **kwargs)
+                    # Extract path from args[0]
+                    if args and recorder is not None:
+                        path = args[0]
+                        # Clean up the path to match endpoint format
+                        if isinstance(path, str):
+                            # Remove query parameters
+                            path = path.partition("?")[0]
+                            recorder.record_call(path, test_name)
+                    return response
+
+                return tracked_method
+            return attr
+
+    return CoverageWrapper(client)
+
+
+def get_app_from_fixture_or_auto_discover(request: pytest.FixtureRequest) -> Any:
+    """Get app from fixture or auto-discovery."""
+    app = None
+    try:
+        app = request.getfixturevalue("app")
+        logger.debug("> Found 'app' fixture")
+    except pytest.FixtureLookupError:
+        logger.debug("> No 'app' fixture found, trying auto-discovery...")
+        app = auto_discover_app()
+    return app
+
+
+@pytest.fixture
+def coverage_client(request: pytest.FixtureRequest) -> Any:
+    """
+    Smart auto-discovering test coverage_client that records API calls for coverage.
+
+    Tries to find an 'app' fixture first, then auto-discovers apps in common locations.
+    Can also wrap existing custom fixtures if configured.
+    """
+    session = request.node.session
+
+    if not session.config.getoption("--api-cov-report"):
+        pytest.skip("API coverage not enabled. Use --api-cov-report flag.")
+
+    config = get_pytest_api_cov_report_config(request.config)
+    coverage_data = getattr(session, "api_coverage_data", None)
+    if coverage_data is None:
+        pytest.skip("API coverage data not initialized. This should not happen.")
+
+    # Check if we should wrap an existing fixture
+    if config.client_fixture_name != "coverage_client":
+        try:
+            # Get the existing custom fixture
+            existing_client = request.getfixturevalue(config.client_fixture_name)
+            logger.info(f"> Found custom fixture '{config.client_fixture_name}', wrapping with coverage tracking")
+
+            # We still need to discover endpoints, so try to get the app
+            app = get_app_from_fixture_or_auto_discover(request)
+            if app and is_supported_framework(app):
+                try:
+                    adapter = get_framework_adapter(app)
+                    if not coverage_data.discovered_endpoints.endpoints:
+                        endpoints = adapter.get_endpoints()
+                        framework_name = type(app).__name__
+                        for endpoint in endpoints:
+                            coverage_data.add_discovered_endpoint(endpoint, f"{framework_name.lower()}_adapter")
+                        logger.info(f"> pytest-api-coverage: Discovered {len(endpoints)} endpoints.")
+                        logger.debug(f"> Discovered endpoints: {endpoints}")
+                except Exception as e:
+                    logger.warning(f"> pytest-api-coverage: Could not discover endpoints from app. Error: {e}")
+
+            # Wrap the existing client with coverage tracking
+            wrapped_client = wrap_client_with_coverage(existing_client, coverage_data.recorder, request.node.name)
+            yield wrapped_client
+            return
+
+        except pytest.FixtureLookupError:
+            logger.warning(f"> Custom fixture '{config.client_fixture_name}' not found, falling back to auto-discovery")
+
+    # Original auto-discovery logic
+    app = get_app_from_fixture_or_auto_discover(request)
+
+    if app is None:
+        helpful_msg = get_helpful_error_message()
+        print(helpful_msg)
+        pytest.skip("No API app found. See error message above for setup guidance.")
+
+    if not is_supported_framework(app):
+        pytest.skip(f"Unsupported framework: {type(app).__name__}. pytest-api-coverage supports Flask and FastAPI.")
+
+    try:
+        adapter = get_framework_adapter(app)
+    except TypeError as e:
+        pytest.skip(f"Framework detection failed: {e}")
+
+    if not coverage_data.discovered_endpoints.endpoints:
+        try:
+            endpoints = adapter.get_endpoints()
+            framework_name = type(app).__name__
+            for endpoint in endpoints:
+                coverage_data.add_discovered_endpoint(endpoint, f"{framework_name.lower()}_adapter")
+            logger.info(f"> pytest-api-coverage: Discovered {len(endpoints)} endpoints.")
+            logger.debug(f"> Discovered endpoints: {endpoints}")
+        except Exception as e:
+            logger.warning(f"> pytest-api-coverage: Could not discover endpoints. Error: {e}")
+
+    client = adapter.get_tracked_client(coverage_data.recorder, request.node.name)
+    yield client
+
+
+def pytest_sessionfinish(session: pytest.Session) -> None:
+    """Generate the API coverage report at the end of the session."""
+    if session.config.getoption("--api-cov-report"):
+        coverage_data = getattr(session, "api_coverage_data", None)
+        if coverage_data is None:
+            logger.warning("> No API coverage data found. Plugin may not have been properly initialized.")
+            return
+
+        logger.debug(f"> pytest-api-coverage: Generating report for {len(coverage_data.recorder)} recorded endpoints.")
+        if hasattr(session.config, "workeroutput"):
+            serializable_recorder = coverage_data.recorder.to_serializable()
+            session.config.workeroutput["api_call_recorder"] = serializable_recorder
+            session.config.workeroutput["discovered_endpoints"] = coverage_data.discovered_endpoints.endpoints
+            logger.debug("> Sent API call data and discovered endpoints to master process")
+        else:
+            logger.debug("> No workeroutput found, generating report for master data.")
+
+            worker_recorder_data = getattr(session.config, "worker_api_call_recorder", {})
+            worker_endpoints = getattr(session.config, "worker_discovered_endpoints", [])
+
+            # Merge worker data into session data
+            if worker_recorder_data or worker_endpoints:
+                coverage_data.merge_worker_data(worker_recorder_data, worker_endpoints)
+                logger.debug(f"> Merged worker data: {len(worker_recorder_data)} endpoints")
+
+            logger.debug(f"> Final merged data: {len(coverage_data.recorder)} recorded endpoints")
+            logger.debug(f"> Using discovered endpoints: {coverage_data.discovered_endpoints.endpoints}")
+
+            api_cov_config = get_pytest_api_cov_report_config(session.config)
+            status = generate_pytest_api_cov_report(
+                api_cov_config=api_cov_config,
+                called_data=coverage_data.recorder.calls,
+                discovered_endpoints=coverage_data.discovered_endpoints.endpoints,
+            )
+            if session.exitstatus == 0:
+                session.exitstatus = status
+
+        if hasattr(session, "api_coverage_data"):
+            delattr(session, "api_coverage_data")
+
+        if hasattr(session.config, "worker_api_call_recorder"):
+            delattr(session.config, "worker_api_call_recorder")
+
+
+class DeferXdistPlugin:
+    """Simple class to defer pytest-xdist hook until we know it is installed."""
+
+    def pytest_testnodedown(self, node: Any) -> None:
+        """Collect API call data from each worker as they finish."""
+        logger.debug("> pytest-api-coverage: Worker node down.")
+        worker_data = node.workeroutput.get("api_call_recorder", {})
+        discovered_endpoints = node.workeroutput.get("discovered_endpoints", [])
+        logger.debug(f"> Worker data: {worker_data}")
+        logger.debug(f"> Worker discovered endpoints: {discovered_endpoints}")
+
+        # Merge API call data
+        if worker_data:
+            logger.debug("> Worker data found, merging with current data.")
+            current = getattr(node.config, "worker_api_call_recorder", {})
+            logger.debug(f"> Current data before merge: {current}")
+
+            # Merge the worker data into current
+            for endpoint, calls in worker_data.items():
+                if endpoint not in current:
+                    current[endpoint] = set()
+                elif not isinstance(current[endpoint], set):
+                    current[endpoint] = set(current[endpoint])
+                current[endpoint].update(calls)
+                logger.debug(f"> Updated endpoint {endpoint} with calls: {calls}")
+
+            node.config.worker_api_call_recorder = current
+            logger.debug(f"> Updated current data: {current}")
+
+        if discovered_endpoints and not getattr(node.config, "worker_discovered_endpoints", []):
+            node.config.worker_discovered_endpoints = discovered_endpoints
+            logger.debug(f"> Set discovered endpoints from worker: {discovered_endpoints}")

pytest_api_cov/pytest_flags.py

@@ -66,3 +66,11 @@ def add_pytest_api_cov_flags(parser: pytest.Parser) -> None:
         default=False,
         help="Disable use of API coverage sugar in console report.",
     )
+
+    parser.addoption(
+        "--api-cov-client-fixture-name",
+        action="store",
+        type=str,
+        default=None,
+        help="Name of existing test client fixture to wrap with coverage tracking",
+    )

{pytest_api_cov-1.0.0.dist-info → pytest_api_cov-1.0.2.dist-info}/METADATA

@@ -1,19 +1,19 @@
 Metadata-Version: 2.4
 Name: pytest-api-cov
-Version: 1.0.0
-Summary: Api Coverage Report Pytest Plugin
+Version: 1.0.2
+Summary: Pytest Plugin to provide API Coverage statistics for Python Web Frameworks
 Author-email: Barnaby Gill <barnabasgill@gmail.com>
 License: Apache-2.0
 License-File: LICENSE
 Requires-Python: >=3.10
-Requires-Dist: fastapi>=0.116.1
-Requires-Dist: flask>=3.1.1
-Requires-Dist: httpx>=0.28.1
-Requires-Dist: pydantic>=2.11.7
-Requires-Dist: pytest>=8.4.1
-Requires-Dist: rich>=14.0.0
-Requires-Dist: starlette>=0.47.1
-Requires-Dist: tomli>=2.2.1
+Requires-Dist: fastapi>=0.68.0
+Requires-Dist: flask>=2.0.0
+Requires-Dist: httpx>=0.20.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pytest>=6.0.0
+Requires-Dist: rich>=10.0.0
+Requires-Dist: starlette>=0.14.0
+Requires-Dist: tomli>=1.2.0
 Description-Content-Type: text/markdown
 
 # pytest-api-cov
@@ -44,11 +44,28 @@ For most projects, no configuration is needed:
 pytest --api-cov-report
 ```
 
+### App Location Flexibility
+
+**Zero Config**: Works automatically if your app is in `app.py`, `main.py`, or `server.py`
+
+**Any Location**: Place your app anywhere in your project - just create a `conftest.py`:
+
+```python
+import pytest
+from my_project.backend.api import my_app  # Any import path!
+
+@pytest.fixture
+def app():
+    return my_app
+```
+
 The plugin will automatically discover your Flask/FastAPI app if it's in common locations:
 - `app.py` (with variable `app`, `application`, or `main`)
 - `main.py` (with variable `app`, `application`, or `main`) 
 - `server.py` (with variable `app`, `application`, or `server`)
 
+**Your app can be located anywhere!** If it's not in a standard location, just create a `conftest.py` file to tell the plugin where to find it.
+
 ### Example
 
 Given this FastAPI app in `app.py`:
@@ -74,12 +91,12 @@ def health_check():
 And this test file:
 
 ```python
-def test_root_endpoint(client):
-    response = client.get("/")
+def test_root_endpoint(coverage_client):
+    response = coverage_client.get("/")
     assert response.status_code == 200
 
-def test_get_user(client):
-    response = client.get("/users/123")
+def test_get_user(coverage_client):
+    response = coverage_client.get("/users/123")
     assert response.status_code == 200
 ```
 
@@ -93,6 +110,22 @@ Uncovered Endpoints:
 Total API Coverage: 66.67%
 ```
 
+Or running with advanced options `pytest --api-cov-report --api-cov-show-covered-endpoints --api-cov-exclusion-patterns="/users/*" --api-cov-show-excluded-endpoints --api-cov-report-path=api_coverage.json --api-cov-fail-under=49` produces:
+
+```
+API Coverage Report
+Uncovered Endpoints:
+  [X] /health
+Covered Endpoints:
+  [.] /
+Excluded Endpoints:
+  [-] /users/{user_id}
+
+SUCCESS: Coverage of 50.0% meets requirement of 49.0%
+
+JSON report saved to api_coverage.json
+```
+
 ## Advanced Configuration
 
 ### Setup Wizard
@@ -110,15 +143,56 @@ This will:
 
 ### Manual Configuration
 
-Create a `conftest.py` file:
+Create a `conftest.py` file to specify your app location (works with **any** file path or structure):
 
 ```python
 import pytest
-from your_app import app
+
+# Import from anywhere in your project
+from my_project.backend.api import flask_app
+# or from src.services.web_server import fastapi_instance  
+# or from deeply.nested.modules import my_app
 
 @pytest.fixture
 def app():
-    return app
+    return flask_app  # Return your app instance
+```
+
+This approach works with any project structure - the plugin doesn't care where your app is located as long as you can import it.
+
+### Custom Test Client Fixtures
+
+If you have an existing test client fixture with custom setup (authentication, headers, etc.), you can wrap it with coverage tracking:
+
+```python
+import pytest
+from fastapi.testclient import TestClient
+from your_app import app
+
+@pytest.fixture
+def my_custom_client():
+    """Custom test client with authentication."""
+    client = TestClient(app)
+    client.headers.update({"Authorization": "Bearer test-token"})
+    return client
+
+def test_endpoint(coverage_client):
+    # coverage_client will be your custom client with coverage tracking
+    response = coverage_client.get("/protected-endpoint")
+    assert response.status_code == 200
+```
+
+Configure it in `pyproject.toml`:
+
+```toml
+[tool.pytest_api_cov]
+client_fixture_name = "my_custom_client"
+```
+
+Or via command line:
+
+```bash
+pytest --api-cov-report --api-cov-client-fixture-name=my_custom_client
 ```
 
 ### Configuration Options
@@ -153,6 +227,9 @@ force_sugar = true
 
 # Force no Unicode symbols in output
 force_sugar_disabled = true
+
+# Wrap an existing custom test client fixture with coverage tracking
+client_fixture_name = "my_custom_client"
 ```
 
 ### Command Line Options
@@ -194,7 +271,6 @@ Works automatically with FastAPI and Flask applications.
 
 ```python
 from fastapi import FastAPI
-from fastapi.testclient import TestClient
 
 app = FastAPI()
 
@@ -202,9 +278,9 @@ app = FastAPI()
 def read_item(item_id: int):
     return {"item_id": item_id}
 
-# Tests automatically get a 'client' fixture
-def test_read_item(client):
-    response = client.get("/items/42")
+# Tests automatically get a 'coverage_client' fixture
+def test_read_item(coverage_client):
+    response = coverage_client.get("/items/42")
     assert response.status_code == 200
 ```
 
@@ -219,9 +295,9 @@ app = Flask(__name__)
 def get_user(user_id):
     return {"user_id": user_id}
 
-# Tests automatically get a 'client' fixture  
-def test_get_user(client):
-    response = client.get("/users/123")
+# Tests automatically get a 'coverage_client' fixture  
+def test_get_user(coverage_client):
+    response = coverage_client.get("/users/123")
     assert response.status_code == 200
 ```
 
@@ -301,13 +377,56 @@ jobs:
 
 ### No App Found
 
-If you see "No API app found", ensure:
+If you see "No API app found", you have several options:
+
+**Option 1 - Auto-discovery (Zero Config)**
+Place your app in a standard location with a standard name:
+- Files: `app.py`, `main.py`, `server.py`, `wsgi.py`, `asgi.py`
+- Variable names: `app`, `application`, `main`, `server`
+
+**Option 2 - Custom Location (Any File/Path)**
+Create a `conftest.py` file to specify your app location:
+
+```python
+import pytest
+from my_project.api.server import my_flask_app  # Any import path
+# or from src.backend.main import fastapi_instance
+# or from anywhere import your_app
+
+@pytest.fixture
+def app():
+    return my_flask_app  # Return your app instance
+```
+
+**Option 3 - Override Auto-discovery**
+If you have multiple auto-discoverable files or want to use a different app:
+
+```python
+# Even if you have app.py, you can override it
+import pytest
+from main import my_real_app  # Use this instead of app.py
+
+@pytest.fixture
+def app():
+    return my_real_app
+```
+
+**Option 4 - Setup Wizard**
+Run the interactive setup: `pytest-api-cov init`
+
+The plugin will automatically find your app using the `app` fixture first, then fall back to auto-discovery in common locations. This means you can place your app **anywhere** as long as you create the fixture.
+
+### Multiple App Files
+
+If you have multiple files that could be auto-discovered (e.g., both `app.py` and `main.py`), the plugin will use the **first valid app it finds** in this priority order:
 
-1. Your app is in a standard location (`app.py`, `main.py`, etc.)
-2. Your app variable has a standard name (`app`, `application`, `main`)
-3. Your app imports are correct (`from fastapi import FastAPI` or `from flask import Flask`)
+1. `app.py` 
+2. `main.py`
+3. `server.py`
+4. `wsgi.py`
+5. `asgi.py`
 
-Or use the setup wizard: `pytest-api-cov init`
+To use a specific app when multiple exist, create a `conftest.py` with an `app` fixture pointing to your preferred app.
 
 ### No Endpoints Discovered
 
@@ -315,7 +434,7 @@ If you see "No endpoints discovered":
 
 1. Check that your app is properly instantiated
 2. Verify your routes/endpoints are defined
-3. Ensure the `client` fixture is working in your tests
+3. Ensure the `coverage_client` fixture is working in your tests
 4. Use `-v` or `-vv` for debug information
 
 ### Framework Not Detected

pytest_api_cov-1.0.2.dist-info/RECORD

@@ -0,0 +1,13 @@
+pytest_api_cov/__init__.py,sha256=7ZX-XIlYwdB0AkSSaXG2O6mah3CBCjZGTiBSEf5dTqk,177
+pytest_api_cov/cli.py,sha256=TCnldhRBi9BMLaPrnp7sfoWNc0Ktu8XnoRQKUuXFGWo,7186
+pytest_api_cov/config.py,sha256=51GaJgAtctAcNb2F-7Q65qZuNusf3_s1-4bE-AWv5QE,3323
+pytest_api_cov/frameworks.py,sha256=5d6wnEsb2BykPtpnpkv98GMPuyoG4elXRJ7vtGHF06A,3228
+pytest_api_cov/models.py,sha256=YiXLiEEyNREiodzn1pGqSNIHrm3zV6kFn0XgyN8_8Rs,4893
+pytest_api_cov/plugin.py,sha256=rZVTvhqKv5GCIbwgFRH3KcrwNXdecFDRrtbMepZfjs8,16118
+pytest_api_cov/pytest_flags.py,sha256=OX1NMcQHfI9uyPrZXj0Q_VG1daU8uKKB4sY-4JLm220,2175
+pytest_api_cov/report.py,sha256=VxfWag20V8o9ArbxOkR_gWQ2TE-sthrS0PCJvn4YCSU,6642
+pytest_api_cov-1.0.2.dist-info/METADATA,sha256=jR8gMyw5frvKQzWeyPrjHmACqa1S6xPZuYXgoshK9Vc,11303
+pytest_api_cov-1.0.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pytest_api_cov-1.0.2.dist-info/entry_points.txt,sha256=hWqEhsBKzbwSwcxCzKgSA8NElQxk0K4PKERrYsi3csk,110
+pytest_api_cov-1.0.2.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
+pytest_api_cov-1.0.2.dist-info/RECORD,,

pytest_api_cov-1.0.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-pytest_api_cov/__init__.py,sha256=o5esC2mfxHTQ7_KBZPGipOQ1OrTTeb-WeE8zPdVzQj8,175
-pytest_api_cov/cli.py,sha256=vEkVCFKxxOUo_-vUCMuo5u49aAT9aHZ5EU5JcCBuqfc,6383
-pytest_api_cov/config.py,sha256=cB8N9bpkGmYhXLW3QL08atJy3ukC1vJcSD2qc8tRol0,3166
-pytest_api_cov/frameworks.py,sha256=5d6wnEsb2BykPtpnpkv98GMPuyoG4elXRJ7vtGHF06A,3228
-pytest_api_cov/models.py,sha256=YiXLiEEyNREiodzn1pGqSNIHrm3zV6kFn0XgyN8_8Rs,4893
-pytest_api_cov/plugin.py,sha256=Sa4tWSXmwcXDmxRSAwlM6n4RjU-HqY3S9G8Esicy2nw,11078
-pytest_api_cov/pytest_flags.py,sha256=aH-MpUQCX7JdPA7f_Qulf0HzOtFpyTqDbHFDy48epOg,1949
-pytest_api_cov/report.py,sha256=VxfWag20V8o9ArbxOkR_gWQ2TE-sthrS0PCJvn4YCSU,6642
-pytest_api_cov-1.0.0.dist-info/METADATA,sha256=yevOYWGatlPnDmoZjWkOn17KGVq8FIZoszzB3yHr2uM,7528
-pytest_api_cov-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-pytest_api_cov-1.0.0.dist-info/entry_points.txt,sha256=hWqEhsBKzbwSwcxCzKgSA8NElQxk0K4PKERrYsi3csk,110
-pytest_api_cov-1.0.0.dist-info/licenses/LICENSE,sha256=HrhfyXIkWY2tGFK11kg7vPCqhgh5DcxleloqdhrpyMY,11558
-pytest_api_cov-1.0.0.dist-info/RECORD,,