7806425ba6
Adds tests/contracts/test_openapi_baseline.py which loads the live FastAPI app and diffs its OpenAPI schema against a checked-in baseline. Fails on: - Any removed path or operation - Any removed response status code on an existing operation - Any new required request body field (would break existing clients) Passes silently on additive changes. The baseline is regenerated by running tests/contracts/regenerate_baseline.py — only when a contract change has been reviewed and every consumer (admin-compliance, developer-portal, SDKs) has been updated in the same change set. This is the safety harness for the Phase 1 backend-compliance refactor: every subsequent refactor commit must keep this test green. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
103 lines
3.7 KiB
Python
103 lines
3.7 KiB
Python
"""OpenAPI contract test.
|
|
|
|
This test pins the public HTTP contract of backend-compliance. It loads the
|
|
FastAPI app, extracts the live OpenAPI schema, and compares it against a
|
|
checked-in baseline at ``tests/contracts/openapi.baseline.json``.
|
|
|
|
Rules:
|
|
- Adding new paths/operations/fields → OK (additive change).
|
|
- Removing a path, changing a method, changing a status code, removing or
|
|
renaming a response/request field → FAIL. Such changes require updating
|
|
every consumer (admin-compliance, developer-portal, SDKs) in the same
|
|
change, then regenerating the baseline with:
|
|
|
|
python tests/contracts/regenerate_baseline.py
|
|
|
|
and explaining the contract change in the PR description.
|
|
|
|
The baseline is missing on first run — the test prints the command to create
|
|
it and skips. This is intentional: Phase 1 step 1 generates it fresh from the
|
|
current app state before any refactoring begins.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
from pathlib import Path
|
|
from typing import Any
|
|
|
|
import pytest
|
|
|
|
BASELINE_PATH = Path(__file__).parent / "openapi.baseline.json"
|
|
|
|
|
|
def _load_live_schema() -> dict[str, Any]:
|
|
"""Import the FastAPI app and extract its OpenAPI schema.
|
|
|
|
Kept inside the function so that test collection does not fail if the app
|
|
has import-time side effects that aren't satisfied in the test env.
|
|
"""
|
|
from main import app # type: ignore[import-not-found]
|
|
|
|
return app.openapi()
|
|
|
|
|
|
def _collect_operations(schema: dict[str, Any]) -> dict[str, dict[str, Any]]:
|
|
"""Return a flat {f'{METHOD} {path}': operation} map for diffing."""
|
|
out: dict[str, dict[str, Any]] = {}
|
|
for path, methods in schema.get("paths", {}).items():
|
|
for method, op in methods.items():
|
|
if method.lower() in {"get", "post", "put", "patch", "delete", "options", "head"}:
|
|
out[f"{method.upper()} {path}"] = op
|
|
return out
|
|
|
|
|
|
@pytest.mark.contract
|
|
def test_openapi_no_breaking_changes() -> None:
|
|
if not BASELINE_PATH.exists():
|
|
pytest.skip(
|
|
f"Baseline missing. Run: python {Path(__file__).parent}/regenerate_baseline.py"
|
|
)
|
|
|
|
baseline = json.loads(BASELINE_PATH.read_text())
|
|
live = _load_live_schema()
|
|
|
|
baseline_ops = _collect_operations(baseline)
|
|
live_ops = _collect_operations(live)
|
|
|
|
# 1. No operation may disappear.
|
|
removed = sorted(set(baseline_ops) - set(live_ops))
|
|
assert not removed, (
|
|
f"Breaking change: {len(removed)} operation(s) removed from public API:\n "
|
|
+ "\n ".join(removed)
|
|
)
|
|
|
|
# 2. For operations that exist in both, response status codes must be a superset.
|
|
for key, baseline_op in baseline_ops.items():
|
|
live_op = live_ops[key]
|
|
baseline_codes = set((baseline_op.get("responses") or {}).keys())
|
|
live_codes = set((live_op.get("responses") or {}).keys())
|
|
missing = baseline_codes - live_codes
|
|
assert not missing, (
|
|
f"Breaking change: {key} no longer returns status code(s) {sorted(missing)}"
|
|
)
|
|
|
|
# 3. Required request-body fields may not be added (would break existing clients).
|
|
for key, baseline_op in baseline_ops.items():
|
|
live_op = live_ops[key]
|
|
base_req = _required_body_fields(baseline_op)
|
|
live_req = _required_body_fields(live_op)
|
|
new_required = live_req - base_req
|
|
assert not new_required, (
|
|
f"Breaking change: {key} added required request field(s) {sorted(new_required)}"
|
|
)
|
|
|
|
|
|
def _required_body_fields(op: dict[str, Any]) -> set[str]:
|
|
rb = op.get("requestBody") or {}
|
|
content = rb.get("content") or {}
|
|
for media in content.values():
|
|
schema = media.get("schema") or {}
|
|
return set(schema.get("required") or [])
|
|
return set()
|