pytest-api-core 1.0.1__py3-none-any.whl

pytest_api_core/client/api_client.py

@@ -0,0 +1,183 @@
+"""
+HTTP client built on top of requests.Session.
+
+Features
+--------
+- Automatic base-URL resolution
+- Configurable retry with back-off (via urllib3.Retry)
+- Request / response logging
+- Pluggable auth strategies
+- Returns APIResponse objects for use with the fluent assertion API
+"""
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from pytest_api_core.client.api_response import APIResponse
+
+log = logging.getLogger("pytest_api_core.client")
+
+
+_DEFAULT_RETRY = Retry(
+    total=3,
+    backoff_factor=0.3,
+    status_forcelist=(500, 502, 503, 504),
+    allowed_methods={"GET", "OPTIONS", "HEAD"},
+    raise_on_status=False,
+)
+
+
+class APIClient:
+    """
+    Session-backed HTTP client used by API tests.
+
+    Parameters
+    ----------
+    base_url:
+        Root URL prepended to every relative path (e.g. ``https://api.example.com/v1``).
+    auth:
+        An auth handler instance (BearerAuth, BasicAuth, APIKeyAuth, …) or any
+        callable accepted by requests.
+    timeout:
+        Default timeout in seconds for every request.
+    verify_ssl:
+        Whether to verify TLS certificates.
+    default_headers:
+        Headers merged into every request.
+    retry:
+        urllib3 Retry config.  Pass ``None`` to disable retries.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        auth: Any = None,
+        timeout: int | float = 30,
+        verify_ssl: bool = True,
+        default_headers: dict[str, str] | None = None,
+        retry: Retry | None = _DEFAULT_RETRY,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.verify_ssl = verify_ssl
+
+        self._session = requests.Session()
+
+        if auth is not None:
+            self._session.auth = auth
+
+        if default_headers:
+            self._session.headers.update(default_headers)
+
+        if retry:
+            adapter = HTTPAdapter(max_retries=retry)
+            self._session.mount("https://", adapter)
+            self._session.mount("http://", adapter)
+
+    # ------------------------------------------------------------------
+    # HTTP verbs
+    # ------------------------------------------------------------------
+
+    def get(self, path: str, **kwargs: Any) -> APIResponse:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> APIResponse:
+        return self._request("POST", path, **kwargs)
+
+    def put(self, path: str, **kwargs: Any) -> APIResponse:
+        return self._request("PUT", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> APIResponse:
+        return self._request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> APIResponse:
+        return self._request("DELETE", path, **kwargs)
+
+    def head(self, path: str, **kwargs: Any) -> APIResponse:
+        return self._request("HEAD", path, **kwargs)
+
+    def options(self, path: str, **kwargs: Any) -> APIResponse:
+        return self._request("OPTIONS", path, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _resolve_url(self, path: str) -> str:
+        if path.startswith(("http://", "https://")):
+            return path
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> APIResponse:
+        url = self._resolve_url(path)
+        kwargs.setdefault("timeout", self.timeout)
+        kwargs.setdefault("verify", self.verify_ssl)
+
+        # DEBUG: full request detail before sending
+        if log.isEnabledFor(logging.DEBUG):
+            log.debug(
+                "→ %s %s  headers=%s  body=%s",
+                method,
+                url,
+                dict(self._session.headers),
+                kwargs.get("json") or kwargs.get("data"),
+            )
+
+        start = time.monotonic()
+        response = self._session.request(method, url, **kwargs)
+        elapsed_ms = (time.monotonic() - start) * 1000
+
+        api_resp = APIResponse(response, elapsed_ms)
+
+        # INFO: one-liner always shown at INFO level
+        log.info("← %s %s  %s  (%.1f ms)", method, url, response.status_code, elapsed_ms)
+
+        # DEBUG: response body
+        if log.isEnabledFor(logging.DEBUG):
+            log.debug("   response body: %s", api_resp.response_body_text())
+
+        # Structured sentinel — parsed by HTMLReporter to build request/response banners
+        log.debug(
+            "__API_CALL__ %s",
+            json.dumps(
+                {
+                    "method": method,
+                    "url": url,
+                    "req_headers": {
+                        k: v for k, v in dict(self._session.headers).items()
+                        if k.lower() not in ("authorization",)  # never log auth tokens
+                    },
+                    "req_body": api_resp.request_body_text()[:2000],
+                    "status": response.status_code,
+                    "elapsed_ms": round(elapsed_ms, 1),
+                    "res_headers": dict(response.headers),
+                    "res_body": api_resp.response_body_text()[:2000],
+                },
+                separators=(",", ":"),
+            ),
+        )
+
+        return api_resp
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "APIClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._session.close()
+
+    def __repr__(self) -> str:
+        return f"<APIClient base_url={self.base_url!r}>"

pytest_api_core/client/api_response.py

@@ -0,0 +1,101 @@
+"""
+Thin wrapper around requests.Response that adds helper properties
+and is consumed by the fluent assertion API.
+"""
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+import requests
+
+
+class APIResponse:
+    """Wraps requests.Response with additional convenience methods."""
+
+    def __init__(self, response: requests.Response, elapsed_ms: float | None = None) -> None:
+        self._response = response
+        self.elapsed_ms: float = elapsed_ms if elapsed_ms is not None else (
+            response.elapsed.total_seconds() * 1000 if response.elapsed else 0.0
+        )
+
+    # ------------------------------------------------------------------
+    # Delegated properties
+    # ------------------------------------------------------------------
+
+    @property
+    def status_code(self) -> int:
+        return self._response.status_code
+
+    @property
+    def headers(self) -> requests.structures.CaseInsensitiveDict:  # type: ignore[type-arg]
+        return self._response.headers
+
+    @property
+    def text(self) -> str:
+        return self._response.text
+
+    @property
+    def content(self) -> bytes:
+        return self._response.content
+
+    @property
+    def url(self) -> str:
+        return self._response.url
+
+    @property
+    def ok(self) -> bool:
+        return self._response.ok
+
+    @property
+    def request(self) -> requests.PreparedRequest:
+        return self._response.request
+
+    # ------------------------------------------------------------------
+    # JSON helpers
+    # ------------------------------------------------------------------
+
+    def json(self, **kwargs: Any) -> Any:
+        return self._response.json(**kwargs)
+
+    def json_value(self, key: str, default: Any = None) -> Any:
+        """Return a top-level key from the JSON body, or *default* if missing."""
+        try:
+            return self.json().get(key, default)
+        except (ValueError, AttributeError):
+            return default
+
+    # ------------------------------------------------------------------
+    # Request echo (for logging / reporting)
+    # ------------------------------------------------------------------
+
+    def request_body_text(self) -> str:
+        """Return the raw request body as a string (best-effort)."""
+        body = self._response.request.body
+        if body is None:
+            return ""
+        if isinstance(body, bytes):
+            try:
+                parsed = json.loads(body)
+                return json.dumps(parsed, indent=2)
+            except (ValueError, TypeError):
+                return body.decode("utf-8", errors="replace")
+        return str(body)
+
+    def response_body_text(self) -> str:
+        """Return the response body pretty-printed if JSON, else raw text."""
+        try:
+            return json.dumps(self.json(), indent=2)
+        except (ValueError, TypeError):
+            return self.text
+
+    # ------------------------------------------------------------------
+    # Dunder
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return f"<APIResponse [{self.status_code}] {self.url} ({self.elapsed_ms:.1f} ms)>"
+
+    def raise_for_status(self) -> None:
+        self._response.raise_for_status()

pytest_api_core/config/__init__.py

@@ -0,0 +1,3 @@
+from pytest_api_core.config.config_manager import ConfigManager
+
+__all__ = ["ConfigManager"]

pytest_api_core/config/base_settings.py

@@ -0,0 +1,54 @@
+"""
+Base class for environment settings.
+
+Consumer projects subclass this, define class-level attributes,
+and register them in an ENVIRONMENTS dict.
+
+Example
+-------
+    from pytest_api_core.config.base_settings import BaseSettings
+    import os
+
+    class DevSettings(BaseSettings):
+        base_url = "https://api.dev.mycompany.com"
+        timeout = 30
+        verify_ssl = True
+        headers = {"Accept": "application/json"}
+
+    class StagingSettings(DevSettings):      # inherit defaults, override what changes
+        base_url = "https://api.staging.mycompany.com"
+        timeout = 60
+
+    class ProdSettings(BaseSettings):
+        base_url = os.environ.get("API_BASE_URL", "https://api.mycompany.com")
+        timeout = 60
+        verify_ssl = True
+
+    ENVIRONMENTS = {
+        "dev":     DevSettings,
+        "staging": StagingSettings,
+        "prod":    ProdSettings,
+    }
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class BaseSettings:
+    """Base class for environment-specific API settings."""
+
+    base_url: str = "http://localhost"
+    timeout: int = 30
+    verify_ssl: bool = True
+    headers: dict[str, str] = {}
+
+    @classmethod
+    def as_dict(cls) -> dict[str, Any]:
+        """Return settings as a plain dict, respecting MRO for inheritance."""
+        result: dict[str, Any] = {}
+        for klass in reversed(cls.__mro__):
+            for k, v in vars(klass).items():
+                if not k.startswith("_") and not callable(v) and not isinstance(v, (classmethod, staticmethod)):
+                    result[k] = v
+        return result

pytest_api_core/config/config_manager.py

@@ -0,0 +1,156 @@
+"""
+Environment-aware configuration manager.
+
+Resolution order (highest → lowest priority):
+  1. Environment variables  (API_BASE_URL, API_TOKEN, …)
+  2. ``--api-base-url`` CLI flag
+  3. settings.py  ENVIRONMENTS[env].as_dict()
+  4. Built-in defaults
+
+Usage
+-----
+    manager = ConfigManager(env="staging", settings_module="config.settings")
+    cfg = manager.load()
+"""
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+from typing import Any
+
+log = logging.getLogger("pytest_api_core.config")
+
+_DEFAULTS: dict[str, Any] = {
+    "base_url": "http://localhost",
+    "timeout": 30,
+    "verify_ssl": True,
+    "headers": {},
+    "retry": {
+        "total": 3,
+        "backoff_factor": 0.3,
+        "status_forcelist": [500, 502, 503, 504],
+    },
+}
+
+# Maps env-var names → config keys
+_ENV_VAR_MAP: dict[str, str] = {
+    "API_BASE_URL": "base_url",
+    "API_TIMEOUT": "timeout",
+    "API_VERIFY_SSL": "verify_ssl",
+    "API_TOKEN": "_token",          # consumed by fixtures, not stored in cfg directly
+}
+
+
+class ConfigManager:
+    """
+    Loads and merges configuration for a given environment name.
+
+    Parameters
+    ----------
+    env:
+        Environment label (e.g. ``"dev"``, ``"staging"``).
+    cli_overrides:
+        Extra key/value pairs from CLI options (e.g. ``--api-base-url``).
+    settings_module:
+        Dotted import path to a Python module that contains an
+        ``ENVIRONMENTS`` dict mapping env names to ``BaseSettings``
+        subclasses (e.g. ``"config.settings"``).
+    """
+
+    def __init__(
+        self,
+        env: str | None = None,
+        cli_overrides: dict[str, Any] | None = None,
+        settings_module: str | None = None,
+    ) -> None:
+        self._env = env or os.environ.get("API_ENV", "dev")
+        self._cli_overrides: dict[str, Any] = cli_overrides or {}
+        self._settings_module = settings_module
+        self._cache: dict[str, Any] | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def env(self) -> str:
+        return self._env
+
+    def load(self) -> dict[str, Any]:
+        """Return the fully-resolved config dict (cached after first call)."""
+        if self._cache is not None:
+            return self._cache
+
+        cfg: dict[str, Any] = dict(_DEFAULTS)
+
+        # Layer 1: settings.py
+        _deep_merge(cfg, self._load_settings())
+
+        # Layer 2: CLI overrides
+        _deep_merge(cfg, {k: v for k, v in self._cli_overrides.items() if v is not None})
+
+        # Layer 3: Environment variables
+        for env_var, cfg_key in _ENV_VAR_MAP.items():
+            value = os.environ.get(env_var)
+            if value is not None:
+                cfg[cfg_key] = self._coerce(cfg_key, value)
+
+        log.debug("Loaded config for env=%r: %s", self._env, cfg)
+        self._cache = cfg
+        return cfg
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _load_settings(self) -> dict[str, Any]:
+        if not self._settings_module:
+            log.warning("No api_settings_module configured — using defaults only")
+            return {}
+        try:
+            module = importlib.import_module(self._settings_module)
+        except ModuleNotFoundError:
+            log.warning("Settings module not found: %s — using defaults only", self._settings_module)
+            return {}
+
+        environments = getattr(module, "ENVIRONMENTS", None)
+        if not environments:
+            log.warning("No ENVIRONMENTS dict found in %s", self._settings_module)
+            return {}
+
+        settings_class = environments.get(self._env)
+        if not settings_class:
+            log.warning(
+                "Environment %r not in ENVIRONMENTS %s — using defaults only",
+                self._env, list(environments.keys()),
+            )
+            return {}
+
+        return settings_class.as_dict()
+
+    @staticmethod
+    def _coerce(key: str, raw: str) -> Any:
+        """Coerce env-var strings to appropriate Python types."""
+        if key in ("timeout",):
+            try:
+                return int(raw)
+            except ValueError:
+                return float(raw)
+        if key == "verify_ssl":
+            return raw.lower() not in ("0", "false", "no")
+        return raw
+
+
+# ------------------------------------------------------------------
+# Utility
+# ------------------------------------------------------------------
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> None:
+    """Recursively merge *override* into *base* in-place."""
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(base.get(key), dict):
+            _deep_merge(base[key], value)
+        else:
+            base[key] = value

pytest_api_core/config/env_loader.py

@@ -0,0 +1,110 @@
+"""
+.env file loader and typed environment-variable accessor.
+
+The framework calls :func:`load_env_file` once at session start
+(``pytest_configure``), so any values defined in the .env file are
+available to ``settings.py``, fixtures, and test code via
+:func:`get_env` — or directly through ``os.environ``.
+
+Resolution order (highest → lowest priority)
+---------------------------------------------
+1. Real environment variables already set in the shell / CI secrets
+2. Values loaded from the ``.env`` file  (``override=False`` keeps 1 winning)
+
+Usage in tests
+--------------
+    from pytest_api_core.config.env_loader import get_env
+
+    def test_protected(api_client):
+        token = get_env("BEARER_TOKEN", required=True)
+        api_client.get("/me", headers={"Authorization": f"Bearer {token}"})
+
+Usage in settings.py
+--------------------
+    import os  # .env already loaded by framework before settings are read
+    from pytest_api_core.config.base_settings import BaseSettings
+
+    class StagingSettings(BaseSettings):
+        base_url = os.environ.get("API_BASE_URL", "https://api.staging.example.com")
+        headers  = {"Authorization": f"Bearer {os.environ.get('BEARER_TOKEN', '')}"}
+"""
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+log = logging.getLogger("pytest_api_core.config")
+
+try:
+    from dotenv import load_dotenv as _load_dotenv
+
+    _HAS_DOTENV = True
+except ImportError:  # python-dotenv is an optional dependency
+    _HAS_DOTENV = False
+
+
+def load_env_file(path: str | Path = ".env") -> None:
+    """
+    Load a ``.env`` file into ``os.environ``.
+
+    - Silently skips if the file does not exist.
+    - ``override=False`` ensures real shell / CI environment variables always
+      take precedence over values defined in the file.
+    - Requires ``python-dotenv``; logs a debug message and returns without
+      error if the package is not installed.
+
+    Parameters
+    ----------
+    path:
+        Path to the ``.env`` file.  Relative paths are resolved from the
+        current working directory (the project root when pytest runs).
+    """
+    if not _HAS_DOTENV:
+        log.debug(
+            "python-dotenv is not installed — .env file loading skipped. "
+            "Install it with: pip install python-dotenv"
+        )
+        return
+
+    dotenv_path = Path(path)
+    if not dotenv_path.is_file():
+        log.debug("No .env file found at '%s' — skipping", dotenv_path.resolve())
+        return
+
+    _load_dotenv(dotenv_path=dotenv_path, override=False)
+    log.debug("Loaded .env file from '%s'", dotenv_path.resolve())
+
+
+def get_env(key: str, default: str | None = None, required: bool = False) -> str | None:
+    """
+    Read a value from ``os.environ`` (which includes any values loaded by
+    :func:`load_env_file`).
+
+    Parameters
+    ----------
+    key:
+        Environment variable name (e.g. ``"BEARER_TOKEN"``).
+    default:
+        Value to return when the variable is not set.
+    required:
+        When ``True`` and the variable is not set (and no ``default`` is
+        given), raise :class:`ValueError` with a descriptive message.
+
+    Returns
+    -------
+    str or None
+        The variable value, or ``default`` if not set.
+
+    Raises
+    ------
+    ValueError
+        If ``required=True`` and the variable is absent with no default.
+    """
+    value = os.environ.get(key, default)
+    if required and value is None:
+        raise ValueError(
+            f"Required environment variable '{key}' is not set. "
+            f"Add it to your .env file or export it in your shell / CI secrets."
+        )
+    return value

pytest_api_core/fixtures/__init__.py

@@ -0,0 +1,9 @@
+from pytest_api_core.fixtures.api_fixtures import (
+    api_config,
+    api_client,
+    api_bearer_auth,
+    api_basic_auth,
+    api_key_auth,
+)
+
+__all__ = ["api_config", "api_client", "api_bearer_auth", "api_basic_auth", "api_key_auth"]