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

pytest_api_core/__init__.py

@@ -0,0 +1,20 @@
+"""
+pytest-api-core: Reusable API automation framework for pytest.
+Auto-registered as a pytest plugin via entry_points["pytest11"].
+"""
+
+from pytest_api_core.client.api_client import APIClient
+from pytest_api_core.client.api_response import APIResponse
+from pytest_api_core.assertions.response_assertions import assert_that
+from pytest_api_core.auth.auth_handlers import BearerAuth, BasicAuth, APIKeyAuth, OAuth2ClientCredentials
+
+__version__ = "1.0.0"
+__all__ = [
+    "APIClient",
+    "APIResponse",
+    "assert_that",
+    "BearerAuth",
+    "BasicAuth",
+    "APIKeyAuth",
+    "OAuth2ClientCredentials",
+]

pytest_api_core/assertions/__init__.py

@@ -0,0 +1,3 @@
+from pytest_api_core.assertions.response_assertions import ResponseAssertions, assert_that
+
+__all__ = ["ResponseAssertions", "assert_that"]

pytest_api_core/assertions/response_assertions.py

@@ -0,0 +1,350 @@
+"""
+Fluent (chainable) response assertion API.
+
+Usage
+-----
+    from pytest_api_core.assertions import assert_that
+
+    assert_that(response).status_is(200)
+    assert_that(response).status_is(200).has_key("id").json_path("$.name").equals("Alice")
+    assert_that(response).content_type_contains("application/json")
+    assert_that(response).response_time_under(500)   # ms
+
+Every assertion method returns *self* so calls can be chained freely.
+A clear AssertionError with context is raised on failure.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+from typing import Any
+
+from pytest_api_core.client.api_response import APIResponse
+
+_assert_log = logging.getLogger("pytest_api_core.assertions")
+
+
+def _emit(name: str, passed: bool, **detail: Any) -> None:
+    """Emit a machine-readable sentinel line captured by HTMLReporter."""
+    _assert_log.debug(
+        "__API_ASSERT__ %s",
+        json.dumps({"name": name, "passed": passed, **detail}, separators=(",", ":")),
+    )
+
+
+class ResponseAssertions:
+    """Chainable assertion wrapper for APIResponse objects."""
+
+    def __init__(self, response: APIResponse) -> None:
+        self._response = response
+        # jsonpath-ng is optional; fall back to simple key lookup if absent
+        self._json_path_value: Any = _UNSET
+
+    # ------------------------------------------------------------------
+    # Status code
+    # ------------------------------------------------------------------
+
+    def status_is(self, expected: int) -> "ResponseAssertions":
+        """Assert the HTTP status code equals *expected*."""
+        actual = self._response.status_code
+        passed = actual == expected
+        _emit("status_is", passed, expected=expected, actual=actual)
+        if not passed:
+            raise AssertionError(
+                f"Expected status {expected}, got {actual}.\n"
+                f"  URL: {self._response.url}\n"
+                f"  Body: {self._response.response_body_text()[:500]}"
+            )
+        return self
+
+    def status_in(self, *expected: int) -> "ResponseAssertions":
+        """Assert the status code is one of *expected*."""
+        actual = self._response.status_code
+        passed = actual in expected
+        _emit("status_in", passed, expected=list(expected), actual=actual)
+        if not passed:
+            raise AssertionError(
+                f"Expected status in {expected}, got {actual}.\n"
+                f"  URL: {self._response.url}"
+            )
+        return self
+
+    def is_success(self) -> "ResponseAssertions":
+        """Assert 2xx status code."""
+        actual = self._response.status_code
+        passed = 200 <= actual < 300
+        _emit("is_success", passed, actual=actual)
+        if not passed:
+            raise AssertionError(
+                f"Expected 2xx status, got {actual}.\n"
+                f"  URL: {self._response.url}\n"
+                f"  Body: {self._response.response_body_text()[:500]}"
+            )
+        return self
+
+    def is_client_error(self) -> "ResponseAssertions":
+        """Assert 4xx status code."""
+        actual = self._response.status_code
+        if not (400 <= actual < 500):
+            raise AssertionError(f"Expected 4xx status, got {actual}.")
+        return self
+
+    def is_server_error(self) -> "ResponseAssertions":
+        """Assert 5xx status code."""
+        actual = self._response.status_code
+        if not (500 <= actual < 600):
+            raise AssertionError(f"Expected 5xx status, got {actual}.")
+        return self
+
+    # ------------------------------------------------------------------
+    # Headers
+    # ------------------------------------------------------------------
+
+    def has_header(self, name: str) -> "ResponseAssertions":
+        """Assert a response header with *name* is present (case-insensitive)."""
+        if name.lower() not in {k.lower() for k in self._response.headers}:
+            raise AssertionError(
+                f"Expected header '{name}' to be present.\n"
+                f"  Headers: {dict(self._response.headers)}"
+            )
+        return self
+
+    def header_equals(self, name: str, expected: str) -> "ResponseAssertions":
+        """Assert header *name* equals *expected* (case-insensitive name match)."""
+        actual = self._response.headers.get(name)
+        if actual != expected:
+            raise AssertionError(
+                f"Expected header '{name}' = {expected!r}, got {actual!r}."
+            )
+        return self
+
+    def content_type_contains(self, fragment: str) -> "ResponseAssertions":
+        """Assert the Content-Type header contains *fragment*."""
+        ct = self._response.headers.get("Content-Type", "")
+        if fragment.lower() not in ct.lower():
+            raise AssertionError(
+                f"Expected Content-Type to contain {fragment!r}, got {ct!r}."
+            )
+        return self
+
+    # ------------------------------------------------------------------
+    # JSON body — top-level keys
+    # ------------------------------------------------------------------
+
+    def has_key(self, key: str) -> "ResponseAssertions":
+        """Assert the JSON body contains *key* at the top level."""
+        body = self._json_body()
+        passed = isinstance(body, dict) and key in body
+        _emit("has_key", passed, key=key)
+        if not passed:
+            raise AssertionError(
+                f"Expected JSON key '{key}' to be present.\n"
+                f"  Body keys: {list(body.keys()) if isinstance(body, dict) else body}"
+            )
+        return self
+
+    def key_equals(self, key: str, expected: Any) -> "ResponseAssertions":
+        """Assert top-level JSON key *key* equals *expected*."""
+        body = self._json_body()
+        if not isinstance(body, dict):
+            raise AssertionError(f"Response body is not a JSON object: {body!r}")
+        actual = body.get(key, _UNSET)
+        if actual is _UNSET:
+            _emit("key_equals", False, key=key, expected=expected, actual="<missing>")
+            raise AssertionError(f"Key '{key}' not found in response body.")
+        passed = actual == expected
+        _emit("key_equals", passed, key=key, expected=expected, actual=actual)
+        if not passed:
+            raise AssertionError(
+                f"Expected body['{key}'] = {expected!r}, got {actual!r}."
+            )
+        return self
+
+    def body_contains(self, text: str) -> "ResponseAssertions":
+        """Assert the raw response text contains *text*."""
+        if text not in self._response.text:
+            raise AssertionError(
+                f"Expected response body to contain {text!r}.\n"
+                f"  Body (first 300 chars): {self._response.text[:300]}"
+            )
+        return self
+
+    def is_json_list(self) -> "ResponseAssertions":
+        """Assert the JSON body is an array."""
+        body = self._json_body()
+        if not isinstance(body, list):
+            raise AssertionError(f"Expected JSON array, got {type(body).__name__}.")
+        return self
+
+    def list_length(self, expected: int) -> "ResponseAssertions":
+        """Assert the JSON array body has exactly *expected* items."""
+        body = self._json_body()
+        if not isinstance(body, list):
+            raise AssertionError(f"Expected JSON array, got {type(body).__name__}.")
+        if len(body) != expected:
+            raise AssertionError(
+                f"Expected JSON list length {expected}, got {len(body)}."
+            )
+        return self
+
+    def list_length_gte(self, minimum: int) -> "ResponseAssertions":
+        """Assert the JSON array length is at least *minimum*."""
+        body = self._json_body()
+        if not isinstance(body, list) or len(body) < minimum:
+            raise AssertionError(
+                f"Expected JSON list length >= {minimum}, got {len(body) if isinstance(body, list) else 'non-list'}."
+            )
+        return self
+
+    # ------------------------------------------------------------------
+    # JSONPath navigation (simple dot-notation; no external lib required)
+    # ------------------------------------------------------------------
+
+    def json_path(self, path: str) -> "ResponseAssertions":
+        """
+        Navigate to a value in the JSON body using a simple path expression.
+
+        Supported syntax:
+          ``$.key``            — top-level key
+          ``$.key.nested``     — nested key
+          ``$.items[0].id``    — array index
+          ``$[0].id``          — root is array
+
+        The extracted value is stored for the following ``.equals()`` /
+        ``.matches()`` call.
+        """
+        body = self._json_body()
+        self._json_path_value = _resolve_path(body, path)
+        return self
+
+    def equals(self, expected: Any) -> "ResponseAssertions":
+        """Assert the value from the last ``.json_path()`` call equals *expected*."""
+        if self._json_path_value is _UNSET:
+            raise RuntimeError("Call .json_path() before .equals()")
+        actual = self._json_path_value
+        self._json_path_value = _UNSET
+        if actual != expected:
+            raise AssertionError(f"Expected {expected!r}, got {actual!r}.")
+        return self
+
+    def matches(self, pattern: str) -> "ResponseAssertions":
+        """Assert the value from the last ``.json_path()`` call matches regex *pattern*."""
+        if self._json_path_value is _UNSET:
+            raise RuntimeError("Call .json_path() before .matches()")
+        actual = str(self._json_path_value)
+        self._json_path_value = _UNSET
+        if not re.search(pattern, actual):
+            raise AssertionError(
+                f"Expected value to match /{pattern}/, got {actual!r}."
+            )
+        return self
+
+    def is_not_none(self) -> "ResponseAssertions":
+        """Assert the value from the last ``.json_path()`` call is not None."""
+        if self._json_path_value is _UNSET:
+            raise RuntimeError("Call .json_path() before .is_not_none()")
+        actual = self._json_path_value
+        self._json_path_value = _UNSET
+        if actual is None:
+            raise AssertionError("Expected value to be non-null.")
+        return self
+
+    # ------------------------------------------------------------------
+    # Performance
+    # ------------------------------------------------------------------
+
+    def response_time_under(self, max_ms: float) -> "ResponseAssertions":
+        """Assert the response time is under *max_ms* milliseconds."""
+        actual = self._response.elapsed_ms
+        passed = actual < max_ms
+        _emit("response_time_under", passed, max_ms=max_ms, actual_ms=round(actual, 1))
+        if not passed:
+            raise AssertionError(
+                f"Expected response time < {max_ms}ms, got {actual:.1f}ms.\n"
+                f"  URL: {self._response.url}"
+            )
+        return self
+
+    # ------------------------------------------------------------------
+    # Schema validation (uses jsonschema if available)
+    # ------------------------------------------------------------------
+
+    def matches_schema(self, schema: dict[str, Any]) -> "ResponseAssertions":
+        """Assert the JSON body conforms to the given JSON Schema."""
+        try:
+            import jsonschema
+
+            jsonschema.validate(instance=self._json_body(), schema=schema)
+        except ImportError:
+            raise ImportError(
+                "jsonschema is required for schema validation: pip install jsonschema"
+            )
+        except jsonschema.ValidationError as exc:
+            raise AssertionError(f"Schema validation failed: {exc.message}") from exc
+        return self
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _json_body(self) -> Any:
+        try:
+            return self._response.json()
+        except (ValueError, TypeError) as exc:
+            raise AssertionError(
+                f"Response body is not valid JSON.\n"
+                f"  Status: {self._response.status_code}\n"
+                f"  Body: {self._response.text[:200]}"
+            ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Sentinel & helpers
+# ---------------------------------------------------------------------------
+
+
+class _Unset:
+    """Sentinel for unset json_path value."""
+    def __repr__(self) -> str:
+        return "<UNSET>"
+
+
+_UNSET = _Unset()
+
+
+def _resolve_path(data: Any, path: str) -> Any:
+    """Resolve a simple ``$.key.nested[0]`` path against *data*."""
+    # Strip leading $
+    path = path.lstrip("$")
+    # Tokenise on "." and "[N]"
+    tokens: list[str | int] = []
+    for segment in re.split(r"\.|\[(\d+)\]", path):
+        if segment is None or segment == "":
+            continue
+        try:
+            tokens.append(int(segment))
+        except ValueError:
+            tokens.append(segment)
+
+    current = data
+    for token in tokens:
+        if current is None:
+            raise AssertionError(f"Path traversal failed at token {token!r}: value is null.")
+        try:
+            current = current[token]
+        except (KeyError, IndexError, TypeError) as exc:
+            raise AssertionError(
+                f"Path token {token!r} not found in {type(current).__name__}: {current!r}"
+            ) from exc
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Public factory
+# ---------------------------------------------------------------------------
+
+
+def assert_that(response: APIResponse) -> ResponseAssertions:
+    """Entry-point for the fluent assertion chain."""
+    return ResponseAssertions(response)

pytest_api_core/auth/__init__.py

@@ -0,0 +1,8 @@
+from pytest_api_core.auth.auth_handlers import (
+    BearerAuth,
+    BasicAuth,
+    APIKeyAuth,
+    OAuth2ClientCredentials,
+)
+
+__all__ = ["BearerAuth", "BasicAuth", "APIKeyAuth", "OAuth2ClientCredentials"]

pytest_api_core/auth/auth_handlers.py

@@ -0,0 +1,156 @@
+"""
+Authentication strategy classes compatible with requests.auth.AuthBase.
+
+Usage
+-----
+    client = APIClient(base_url, auth=BearerAuth("my-token"))
+    client = APIClient(base_url, auth=BasicAuth("user", "pass"))
+    client = APIClient(base_url, auth=APIKeyAuth("x-api-key", "secret"))
+"""
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import requests
+from requests.auth import AuthBase
+
+log = logging.getLogger("pytest_api_core.auth")
+
+
+class BearerAuth(AuthBase):
+    """Injects ``Authorization: Bearer <token>`` into every request."""
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest:
+        r.headers["Authorization"] = f"Bearer {self._token}"
+        return r
+
+    def __repr__(self) -> str:
+        return f"<BearerAuth token=***{self._token[-4:]}>"
+
+
+class BasicAuth(AuthBase):
+    """
+    HTTP Basic Authentication.
+    Delegates to requests' built-in HTTPBasicAuth but subclasses AuthBase
+    so it integrates cleanly with the fixture system.
+    """
+
+    def __init__(self, username: str, password: str) -> None:
+        self._inner = requests.auth.HTTPBasicAuth(username, password)
+
+    def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest:
+        return self._inner(r)
+
+    def __repr__(self) -> str:
+        return f"<BasicAuth username={self._inner.username!r}>"
+
+
+class APIKeyAuth(AuthBase):
+    """
+    Injects an API key either as a request header or a query parameter.
+
+    Parameters
+    ----------
+    name:
+        Header name (e.g. ``x-api-key``) or query-parameter name.
+    value:
+        The API key value.
+    location:
+        ``"header"`` (default) or ``"query"``.
+    """
+
+    def __init__(self, name: str, value: str, location: str = "header") -> None:
+        if location not in ("header", "query"):
+            raise ValueError("location must be 'header' or 'query'")
+        self._name = name
+        self._value = value
+        self._location = location
+
+    def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest:
+        if self._location == "header":
+            r.headers[self._name] = self._value
+        else:
+            # Append to existing query string
+            from urllib.parse import urlencode, urlparse, urlunparse, parse_qsl
+
+            parsed = urlparse(r.url or "")
+            params = parse_qsl(parsed.query)
+            params.append((self._name, self._value))
+            r.url = urlunparse(parsed._replace(query=urlencode(params)))
+        return r
+
+    def __repr__(self) -> str:
+        return f"<APIKeyAuth name={self._name!r} location={self._location!r}>"
+
+
+class OAuth2ClientCredentials(AuthBase):
+    """
+    Fetches and caches an OAuth2 access token using the *client credentials* flow.
+    Automatically refreshes when the token is within ``refresh_buffer`` seconds of expiry.
+
+    Parameters
+    ----------
+    token_url:
+        Full URL of the token endpoint.
+    client_id:
+        OAuth2 client ID.
+    client_secret:
+        OAuth2 client secret.
+    scope:
+        Space-separated list of scopes (optional).
+    refresh_buffer:
+        Seconds before expiry to proactively refresh (default 30).
+    """
+
+    def __init__(
+        self,
+        token_url: str,
+        client_id: str,
+        client_secret: str,
+        scope: str = "",
+        refresh_buffer: int = 30,
+    ) -> None:
+        self._token_url = token_url
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._scope = scope
+        self._refresh_buffer = refresh_buffer
+
+        self._access_token: str | None = None
+        self._expires_at: float = 0.0
+
+    def _fetch_token(self) -> None:
+        data: dict[str, str] = {
+            "grant_type": "client_credentials",
+            "client_id": self._client_id,
+            "client_secret": self._client_secret,
+        }
+        if self._scope:
+            data["scope"] = self._scope
+
+        log.debug("Fetching OAuth2 token from %s", self._token_url)
+        response = requests.post(self._token_url, data=data, timeout=15)
+        response.raise_for_status()
+
+        payload: dict[str, Any] = response.json()
+        self._access_token = payload["access_token"]
+        expires_in: int = payload.get("expires_in", 3600)
+        self._expires_at = time.monotonic() + expires_in
+        log.debug("OAuth2 token acquired, expires in %ds", expires_in)
+
+    def _is_expired(self) -> bool:
+        return time.monotonic() >= (self._expires_at - self._refresh_buffer)
+
+    def __call__(self, r: requests.PreparedRequest) -> requests.PreparedRequest:
+        if self._access_token is None or self._is_expired():
+            self._fetch_token()
+        r.headers["Authorization"] = f"Bearer {self._access_token}"
+        return r
+
+    def __repr__(self) -> str:
+        return f"<OAuth2ClientCredentials client_id={self._client_id!r}>"

pytest_api_core/client/__init__.py

@@ -0,0 +1,4 @@
+from pytest_api_core.client.api_client import APIClient
+from pytest_api_core.client.api_response import APIResponse
+
+__all__ = ["APIClient", "APIResponse"]