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

pytest_api_core/fixtures/api_fixtures.py

@@ -0,0 +1,133 @@
+"""
+Auto-registered pytest fixtures provided by pytest-api-core.
+
+These fixtures are available in every test suite that has the package
+installed — no ``conftest.py`` import required.
+
+Fixtures
+--------
+api_config      (session)  — resolved config dict for the target environment
+api_client      (session)  — configured APIClient instance
+api_bearer_auth (function) — BearerAuth instance (token from cfg or API_TOKEN)
+api_basic_auth  (function) — BasicAuth instance (from API_USERNAME / API_PASSWORD)
+api_key_auth    (function) — APIKeyAuth instance
+"""
+from __future__ import annotations
+
+import os
+from typing import Any, Generator
+
+import pytest
+
+from pytest_api_core.auth.auth_handlers import APIKeyAuth, BasicAuth, BearerAuth
+from pytest_api_core.client.api_client import APIClient
+from pytest_api_core.config.config_manager import ConfigManager
+
+
+# ---------------------------------------------------------------------------
+# Config fixture
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def api_config(request: pytest.FixtureRequest) -> dict[str, Any]:
+    """
+    Returns the fully-resolved configuration dict for the active environment.
+
+    Override via CLI: ``--api-env=staging --api-config-dir=config/env``
+    Override via ini: ``api_env = staging``
+    Override via env-var: ``API_ENV=staging``
+    """
+    env: str | None = (
+        request.config.getoption("--api-env", default=None)
+        or request.config.getini("api_env")
+        or None
+    )
+    base_url_override: str | None = request.config.getoption("--api-base-url", default=None)
+    settings_module: str | None = request.config.getini("api_settings_module") or None
+
+    manager = ConfigManager(
+        env=env,
+        cli_overrides={"base_url": base_url_override} if base_url_override else None,
+        settings_module=settings_module,
+    )
+    return manager.load()
+
+
+# ---------------------------------------------------------------------------
+# Client fixture
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def api_client(api_config: dict[str, Any]) -> Generator[APIClient, None, None]:
+    """
+    Session-scoped APIClient built from *api_config*.
+
+    Automatically applies a BearerAuth if ``API_TOKEN`` env-var is set
+    or ``api_config["_token"]`` is present.
+    """
+    auth = None
+    token = api_config.pop("_token", None) or os.environ.get("API_TOKEN")
+    if token:
+        auth = BearerAuth(token)
+
+    client = APIClient(
+        base_url=api_config["base_url"],
+        auth=auth,
+        timeout=api_config.get("timeout", 30),
+        verify_ssl=api_config.get("verify_ssl", True),
+        default_headers=api_config.get("headers"),
+    )
+    yield client
+    client.close()
+
+
+# ---------------------------------------------------------------------------
+# Auth fixtures (function-scoped so tests can customise per-test)
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture()
+def api_bearer_auth(api_config: dict[str, Any]) -> BearerAuth:
+    """
+    BearerAuth built from ``API_TOKEN`` env-var or ``api_config["token"]``.
+    Raises if no token is available.
+    """
+    token = os.environ.get("API_TOKEN") or api_config.get("token")
+    if not token:
+        raise ValueError(
+            "api_bearer_auth requires an API token. "
+            "Set the API_TOKEN environment variable or add 'token' to your env config."
+        )
+    return BearerAuth(token)
+
+
+@pytest.fixture()
+def api_basic_auth() -> BasicAuth:
+    """
+    BasicAuth built from ``API_USERNAME`` / ``API_PASSWORD`` env-vars.
+    Raises if either is missing.
+    """
+    username = os.environ.get("API_USERNAME", "")
+    password = os.environ.get("API_PASSWORD", "")
+    if not username or not password:
+        raise ValueError(
+            "api_basic_auth requires API_USERNAME and API_PASSWORD environment variables."
+        )
+    return BasicAuth(username, password)
+
+
+@pytest.fixture()
+def api_key_auth() -> APIKeyAuth:
+    """
+    APIKeyAuth built from ``API_KEY_NAME`` / ``API_KEY_VALUE`` / ``API_KEY_LOCATION`` env-vars.
+    """
+    name = os.environ.get("API_KEY_NAME", "x-api-key")
+    value = os.environ.get("API_KEY_VALUE", "")
+    location = os.environ.get("API_KEY_LOCATION", "header")
+    if not value:
+        raise ValueError(
+            "api_key_auth requires API_KEY_VALUE environment variable."
+        )
+    return APIKeyAuth(name, value, location)

pytest_api_core/plugin.py

@@ -0,0 +1,125 @@
+"""
+pytest plugin entry-point.
+Registered via [project.entry-points."pytest11"] in pyproject.toml so pytest
+auto-discovers and loads it without any conftest.py changes in consuming projects.
+"""
+from __future__ import annotations
+
+import datetime
+import logging
+
+import pytest
+
+from pytest_api_core.config.env_loader import load_env_file
+from pytest_api_core.fixtures.api_fixtures import (
+    api_config,
+    api_client,
+    api_bearer_auth,
+    api_basic_auth,
+    api_key_auth,
+)
+from pytest_api_core.reporters.html_reporter import HTMLReporter
+
+
+# ---------------------------------------------------------------------------
+# CLI options
+# ---------------------------------------------------------------------------
+
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    group = parser.getgroup("pytest-api-core", "API framework options")
+    group.addoption(
+        "--api-env",
+        action="store",
+        default=None,
+        help="Target environment name (maps to config/env/<name>.yaml)",
+    )
+    group.addoption(
+        "--api-config-dir",
+        action="store",
+        default="config/env",
+        help="Directory containing environment YAML files (default: config/env)",
+    )
+    group.addoption(
+        "--api-html-report",
+        action="store",
+        default=None,
+        metavar="PATH",
+        help="Path for the custom HTML report (e.g. reports/report.html)",
+    )
+    group.addoption(
+        "--api-base-url",
+        action="store",
+        default=None,
+        help="Override base_url from config",
+    )
+    group.addoption(
+        "--api-log-level",
+        action="store",
+        default=None,
+        choices=["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
+        help="Log level for pytest-api-core internals (default: WARNING)",
+    )
+    # Register ini options to suppress "Unknown config option" warnings
+    parser.addini("api_env", help="Default environment (e.g. dev, staging, prod)", default="dev")
+    parser.addini("api_html_report", help="Output path for the custom HTML report", default=None)
+    parser.addini("api_html_theme", help="Report theme: light or dark (default: dark)", default="dark")
+    parser.addini("api_html_title", help="Report browser tab title (default: API Test Report)", default="API Test Report")
+    parser.addini("api_html_header", help="Report page header text (default: API Test Report)", default="API Test Report")
+    parser.addini("api_log_level", help="Log level for pytest-api-core (DEBUG/INFO/WARNING/ERROR/CRITICAL)", default="WARNING")
+    parser.addini("api_settings_module", help="Dotted module path to settings (e.g. config.settings)", default=None)
+    parser.addini("api_dotenv_file", help="Path to .env file loaded at session start (default: .env)", default=".env")
+
+
+# ---------------------------------------------------------------------------
+# ini options (allow pytest.ini / pyproject.toml [tool.pytest.ini_options])
+# ---------------------------------------------------------------------------
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    config.addinivalue_line("markers", "api: mark test as an API test")
+
+    # Load .env file before anything else so os.environ is fully populated
+    # for settings.py class attributes and fixtures
+    dotenv_path = config.getini("api_dotenv_file") or ".env"
+    load_env_file(dotenv_path)
+
+    # Configure the framework logger level from CLI option or ini
+    log_level = (
+        config.getoption("--api-log-level", default=None)
+        or config.getini("api_log_level")
+        or "WARNING"
+    )
+    logging.getLogger("pytest_api_core").setLevel(log_level.upper())
+
+    report_path = config.getoption("--api-html-report", default=None)
+    if not report_path:
+        report_path = config.getini("api_html_report")
+    if report_path:
+        env = (
+            config.getoption("--api-env", default=None)
+            or config.getini("api_env")
+            or "default"
+        )
+        report_path = _resolve_report_path(report_path, env)
+        plugin = HTMLReporter(report_path, config)
+        config.pluginmanager.register(plugin, "api-html-reporter")
+
+
+def _resolve_report_path(path: str, env: str) -> str:
+    """Expand {timestamp} and {env} placeholders in the report path."""
+    timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+    return path.format(timestamp=timestamp, env=env)
+
+
+# ---------------------------------------------------------------------------
+# Re-export fixtures so pytest can discover them from this module
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "api_config",
+    "api_client",
+    "api_bearer_auth",
+    "api_basic_auth",
+    "api_key_auth",
+]

pytest_api_core/reporters/__init__.py

@@ -0,0 +1,3 @@
+from pytest_api_core.reporters.html_reporter import HTMLReporter
+
+__all__ = ["HTMLReporter"]

pytest_api_core/reporters/html_reporter.py

@@ -0,0 +1,245 @@
+"""
+Custom HTML reporter for pytest-api-core.
+
+Generates a single self-contained HTML file from a Jinja2 template with:
+  - Summary card: total / passed / failed / error / skipped counts + duration
+  - SVG donut chart
+  - Filterable, sortable results table
+  - Per-test expandable panels:
+      • HTTP call banners (method badge, URL, status, elapsed) with
+        tabbed Request Headers / Req Body / Res Headers / Res Body
+      • Assertion result rows (✅/❌ with expected vs actual)
+      • Captured logs, stdout, failure traceback
+  - Dark/light mode toggle
+"""
+from __future__ import annotations
+
+import datetime
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+import pytest
+from jinja2 import Environment, PackageLoader
+
+
+_jinja_env = Environment(
+    loader=PackageLoader("pytest_api_core", "reporters/templates"),
+    autoescape=True,
+)
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+class _TestRecord:
+    __slots__ = (
+        "node_id",
+        "name",
+        "outcome",         # "passed" | "failed" | "error" | "skipped"
+        "duration",        # seconds
+        "stdout",
+        "stderr",
+        "logs",            # captured log output (displayed in template)
+        "longrepr",        # failure text
+        "api_calls",       # list[dict] — parsed from __API_CALL__ sentinels
+        "assertions",      # list[dict] — parsed from __API_ASSERT__ sentinels
+        "markers",
+    )
+
+    def __init__(self, node_id: str) -> None:
+        self.node_id = node_id
+        self.name = node_id.split("::")[-1]
+        self.outcome = "unknown"
+        self.duration = 0.0
+        self.stdout = ""
+        self.stderr = ""
+        self.logs = ""
+        self.longrepr = ""
+        self.api_calls: list[dict[str, Any]] = []
+        self.assertions: list[dict[str, Any]] = []
+        self.markers: list[str] = []
+
+
+# ---------------------------------------------------------------------------
+# Plugin hooks
+# ---------------------------------------------------------------------------
+
+
+class HTMLReporter:
+    """pytest plugin that captures results and writes an HTML report on finish."""
+
+    def __init__(self, report_path: str, config: pytest.Config) -> None:
+        self._path = Path(report_path)
+        self._records: dict[str, _TestRecord] = {}
+        self._start_time: datetime.datetime = datetime.datetime.now()
+        self._total_duration = 0.0
+        self._theme = config.getini("api_html_theme") or "dark"
+        self._title = config.getini("api_html_title") or "API Test Report"
+        self._header = config.getini("api_html_header") or "API Test Report"
+
+    # -- collection ----------------------------------------------------------
+
+    def pytest_collection_finish(self, session: pytest.Session) -> None:
+        # Pre-register every collected item so the table order is stable
+        for item in session.items:
+            rec = _TestRecord(item.nodeid)
+            rec.markers = [m.name for m in item.iter_markers()]
+            self._records[item.nodeid] = rec
+
+    # -- per-test result capture ---------------------------------------------
+
+    def pytest_runtest_logreport(self, report: pytest.TestReport) -> None:
+        node_id = report.nodeid
+        if node_id not in self._records:
+            self._records[node_id] = _TestRecord(node_id)
+
+        rec = self._records[node_id]
+
+        if report.when == "call" or (report.when == "setup" and report.failed):
+            rec.duration = report.duration
+            self._total_duration += report.duration
+
+            if report.passed:
+                rec.outcome = "passed"
+            elif report.failed:
+                rec.outcome = "failed" if report.when == "call" else "error"
+            elif report.skipped:
+                rec.outcome = "skipped"
+
+            # Capture printed output
+            if report.capstdout:
+                rec.stdout = report.capstdout
+            if report.capstderr:
+                rec.stderr = report.capstderr
+
+            # Parse captured log sections:
+            # - extract __API_CALL__ and __API_ASSERT__ sentinels into structured fields
+            # - keep human-readable log lines for the LOGS panel
+            log_text = ""
+            for header, content in report.sections:
+                if "log" not in header.lower() or not content.strip():
+                    continue
+                clean_lines = []
+                for raw_line in _strip_ansi(content).splitlines():
+                    if "__API_CALL__" in raw_line:
+                        try:
+                            payload = raw_line.split("__API_CALL__", 1)[1].strip()
+                            rec.api_calls.append(json.loads(payload))
+                        except (ValueError, IndexError):
+                            pass
+                        continue   # don't add to human log
+                    if "__API_ASSERT__" in raw_line:
+                        try:
+                            payload = raw_line.split("__API_ASSERT__", 1)[1].strip()
+                            rec.assertions.append(json.loads(payload))
+                        except (ValueError, IndexError):
+                            pass
+                        continue   # don't add to human log
+                    clean_lines.append(raw_line)
+                section_text = "\n".join(clean_lines).strip()
+                if section_text:
+                    log_text += f"--- {header} ---\n{section_text}\n"
+            rec.logs = log_text
+
+            # Capture failure text
+            if report.longrepr:
+                rec.longrepr = str(report.longrepr)
+
+        elif report.when == "setup" and report.skipped:
+            rec.outcome = "skipped"
+            if report.longrepr:
+                rec.longrepr = str(report.longrepr)
+
+    # -- session finish — write report ----------------------------------------
+
+    def pytest_sessionfinish(self, session: pytest.Session, exitstatus: int) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        html_content = _render_report(
+            records=list(self._records.values()),
+            start_time=self._start_time,
+            total_duration=self._total_duration,
+            theme=self._theme,
+            title=self._title,
+            header=self._header,
+        )
+        self._path.write_text(html_content, encoding="utf-8")
+        # Print path relative to cwd for readability
+        try:
+            rel = self._path.relative_to(Path.cwd())
+        except ValueError:
+            rel = self._path
+        print(f"\n  📄  API HTML report: {rel}\n")
+
+
+# ---------------------------------------------------------------------------
+# Rendering
+# ---------------------------------------------------------------------------
+
+
+def _render_report(
+    records: list[_TestRecord],
+    start_time: datetime.datetime,
+    total_duration: float,
+    theme: str,
+    title: str,
+    header: str,
+) -> str:
+    counts: dict[str, int] = {"passed": 0, "failed": 0, "error": 0, "skipped": 0, "unknown": 0}
+    for rec in records:
+        counts[rec.outcome] = counts.get(rec.outcome, 0) + 1
+
+    total = len(records)
+    template = _jinja_env.get_template("report.html")
+    return template.render(
+        records=records,
+        generated_at=start_time.strftime("%Y-%m-%d %H:%M:%S"),
+        duration=f"{total_duration:.2f}s",
+        total=total,
+        passed=counts["passed"],
+        failed=counts["failed"],
+        error=counts["error"],
+        skipped=counts["skipped"],
+        pass_rate=f"{(counts['passed'] / total * 100):.1f}" if total else "0.0",
+        donut_svg=_donut_svg(counts, total),
+        theme=theme,
+        report_title=title,
+        report_header=header,
+    )
+
+
+def _strip_ansi(text: str) -> str:
+    """Strip ANSI escape codes from a string."""
+    return re.sub(r"\x1b\[[0-9;]*m", "", text)
+
+
+def _donut_svg(counts: dict[str, int], total: int) -> str:
+    if total == 0:
+        return '<svg width="140" height="140"><circle cx="70" cy="70" r="55" fill="none" stroke="#ccc" stroke-width="20"/></svg>'
+
+    colors = {"passed": "#22c55e", "failed": "#ef4444", "error": "#f97316", "skipped": "#94a3b8"}
+    r = 55
+    cx = cy = 70
+    circumference = 2 * 3.14159 * r
+    segments: list[str] = []
+    offset = 0.0
+
+    for outcome, color in colors.items():
+        count = counts.get(outcome, 0)
+        if count == 0:
+            continue
+        fraction = count / total
+        dash = fraction * circumference
+        segments.append(
+            f'<circle cx="{cx}" cy="{cy}" r="{r}" fill="none" stroke="{color}" '
+            f'stroke-width="20" stroke-dasharray="{dash:.2f} {circumference:.2f}" '
+            f'stroke-dashoffset="-{offset:.2f}" transform="rotate(-90 {cx} {cy})"/>' 
+        )
+        offset += dash
+
+    inner_text = f'<text x="{cx}" y="{cy+5}" text-anchor="middle" font-size="18" font-weight="bold" fill="currentColor">{total}</text>'
+    joined = "".join(segments)
+    return f'<svg width="140" height="140">{joined}{inner_text}</svg>'