tests/test_openapi_examples.py

# -------------------------------------------------------------------
# This source file is available under the terms of the
# Pimcore Open Core License (POCL)
# Full copyright and license information is available in
# LICENSE.md which is distributed with this source code.
# -------------------------------------------------------------------
"""The documented samples must stay executable.

A sample that no longer validates is worse than no sample: someone clicks "Try it out" in `/docs`,
gets a 422, and concludes the endpoint is broken. These tests bind each documented example to the
real request model, so a schema change that invalidates a sample fails here rather than in
somebody's browser.
"""

import base64

import pytest
from src.embeddings import EmbeddingsRequest
from src.main import app
from src.openapi_examples import (
    IMAGE_EMBEDDING_EXAMPLES,
    SAMPLE_PNG_BASE64,
    TEXT_EMBEDDING_EXAMPLES,
)

ALL_EXAMPLES = [pytest.param(name, example, id=f"text-{name}") for name, example in TEXT_EMBEDDING_EXAMPLES.items()] + [
    pytest.param(name, example, id=f"image-{name}") for name, example in IMAGE_EMBEDDING_EXAMPLES.items()
]


@pytest.mark.parametrize(("name", "example"), ALL_EXAMPLES)
def test_every_documented_example_validates(name, example):
    """Catches the drift case directly: a validator added to EmbeddingsRequest that an old sample
    now violates."""
    EmbeddingsRequest(**example["value"])


@pytest.mark.parametrize(("name", "example"), ALL_EXAMPLES)
def test_every_documented_example_is_described(name, example):
    """A dropdown entry with no summary is unusable — the reader cannot tell the samples apart."""
    assert example["summary"].strip()
    assert example["description"].strip()


def test_sample_image_is_a_real_decodable_png():
    """The image sample is meant to be sent unmodified, so it has to be an actual image rather than
    a `base64_encoded_image_string` placeholder."""
    raw = base64.b64decode(SAMPLE_PNG_BASE64, validate=True)

    assert raw.startswith(b"\x89PNG\r\n\x1a\n")


def test_examples_reach_the_generated_openapi_schema():
    """Guards the wiring, not just the data: the samples are useless if FastAPI never publishes
    them."""
    schema = app.openapi()

    for path, expected in (
        ("/text-embedding", TEXT_EMBEDDING_EXAMPLES),
        ("/image-embedding", IMAGE_EMBEDDING_EXAMPLES),
    ):
        published = schema["paths"][path]["post"]["requestBody"]["content"]["application/json"]["examples"]
        assert set(published) == set(expected), f"{path} publishes {set(published)}"


def test_documented_response_codes_are_published():
    """The 400 and 404 cases are the ones a caller actually has to handle."""
    responses = app.openapi()["paths"]["/text-embedding"]["post"]["responses"]

    assert {"200", "400", "404"} <= set(responses)