ycdemo / fastapi / tests/ test_query_optional_models.py

from typing import Annotated, Optional

import pytest
from fastapi import Depends, FastAPI, Query, WebSocket
from fastapi.testclient import TestClient
from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator


def test_optional_query_model():
    app = FastAPI()

    class Filters(BaseModel):
        start: int
        end: int
        tags: list[str] = Field(default_factory=list)
        enabled: bool = True
        label: str = "default"

        @model_validator(mode="after")
        def check_range(self):
            if self.start > self.end:
                raise ValueError("start must not exceed end")
            return self

    @app.get("/")
    def read(filters: Annotated[Filters | None, Query()] = None):
        return filters

    client = TestClient(app)
    response = client.get("/")
    assert response.status_code == 200, response.text
    assert response.json() is None
    response = client.get(
        "/", params={"start": "0", "end": "10", "tags": ["a", "b"], "label": ""}
    )
    assert response.status_code == 200, response.text
    assert response.json() == {
        "start": 0,
        "end": 10,
        "tags": ["a", "b"],
        "enabled": True,
        "label": "",
    }
    response = client.get("/", params={"start": "", "end": "10"})
    assert response.status_code == 422
    assert response.json()["detail"][0]["loc"] == ["query", "start"]
    assert response.json()["detail"][0]["type"] == "int_parsing"
    for fields in ({"label": ""}, {"tags": "a"}, {"enabled": "false"}):
        response = client.get("/", params=fields)
        assert response.status_code == 422
        assert [error["loc"] for error in response.json()["detail"]] == [
            ["query", "start"],
            ["query", "end"],
        ]
    response = client.get("/", params={"start": "20", "end": "10"})
    assert response.status_code == 422
    assert response.json()["detail"][0]["loc"] == ["query"]
    assert response.json()["detail"][0]["type"] == "value_error"


def test_optional_models_with_dependencies_and_individual_parameters():
    app = FastAPI()

    class Range(BaseModel):
        start: int
        end: int

    class Filters(BaseModel):
        tags: list[str]

    def get_filters(filters: Annotated[Filters | None, Query()] = None):
        return filters

    @app.get("/")
    def read(
        filters: Annotated[Filters | None, Depends(get_filters)],
        date_range: Annotated[Range | None, Query()] = None,
        limit: int = 10,
    ):
        return {"range": date_range, "filters": filters, "limit": limit}

    client = TestClient(app)
    response = client.get("/", params={"limit": "5"})
    assert response.status_code == 200, response.text
    assert response.json() == {"range": None, "filters": None, "limit": 5}
    response = client.get("/", params={"start": "0", "end": "10"})
    assert response.status_code == 200, response.text
    assert response.json() == {
        "range": {"start": 0, "end": 10},
        "filters": None,
        "limit": 10,
    }
    response = client.get("/", params={"tags": ["a", "b"]})
    assert response.status_code == 200, response.text
    assert response.json() == {
        "range": None,
        "filters": {"tags": ["a", "b"]},
        "limit": 10,
    }
    response = client.get("/", params={"start": "0", "end": "10", "tags": "a"})
    assert response.status_code == 200, response.text
    assert response.json() == {
        "range": {"start": 0, "end": 10},
        "filters": {"tags": ["a"]},
        "limit": 10,
    }
    response = client.get("/", params={"start": "0", "tags": "a"})
    assert response.status_code == 422
    assert response.json()["detail"][0]["loc"] == ["query", "end"]
    parameters = app.openapi()["paths"]["/"]["get"]["parameters"]
    assert {param["name"]: param["required"] for param in parameters} == {
        "start": False,
        "end": False,
        "tags": False,
        "limit": False,
    }


@pytest.mark.parametrize("extra", ["ignore", "allow", "forbid"])
@pytest.mark.parametrize(
    "fields", [{"limit": "5"}, {"limit": "5", "unknown": ["a", "b"]}]
)
def test_unknown_parameters(extra, fields):
    app = FastAPI()

    class Filters(BaseModel):
        model_config = ConfigDict(extra=extra)
        term: str = "default"

    @app.get("/")
    def read(filters: Annotated[Filters | None, Query()] = None, limit: int = 10):
        return filters

    client = TestClient(app)
    assert client.get("/").json() is None
    response = client.get("/", params=fields)
    if extra == "forbid":
        assert response.status_code == 422
        assert [error["loc"] for error in response.json()["detail"]] == [
            ["query", name] for name in fields
        ]
        assert all(
            error["type"] == "extra_forbidden" for error in response.json()["detail"]
        )
    else:
        assert response.status_code == 200, response.text
        assert response.json() == (
            {"term": "default", **fields} if extra == "allow" else None
        )


def test_allowed_extras_require_model_fields():
    app = FastAPI()

    class Filters(BaseModel):
        model_config = ConfigDict(extra="allow")
        term: str

    @app.get("/")
    def read(filters: Annotated[Filters | None, Query()] = None):
        return filters

    client = TestClient(app)
    response = client.get("/", params={"unknown": "value"})
    assert response.status_code == 422
    assert response.json()["detail"] == [
        {
            "type": "missing",
            "loc": ["query", "term"],
            "msg": "Field required",
            "input": {"unknown": "value"},
        }
    ]
    response = client.get("/", params={"term": "search", "unknown": "value"})
    assert response.status_code == 200, response.text
    assert response.json() == {"term": "search", "unknown": "value"}


def test_nullable_model_without_default_is_required():
    app = FastAPI()

    class Filters(BaseModel):
        term: str = "default"

    @app.get("/")
    def read(filters: Annotated[Filters | None, Query()]):
        return filters

    @app.get("/plain")
    def read_plain(filters: Annotated[Filters, Query()]):
        return filters

    client = TestClient(app)
    response = client.get("/")
    assert response.status_code == 422
    assert response.json()["detail"] == [
        {"type": "missing", "loc": ["query"], "msg": "Field required", "input": None}
    ]
    response = client.get("/", params={"term": ""})
    assert response.status_code == 200, response.text
    assert response.json() == {"term": ""}
    response = client.get("/plain")
    assert response.status_code == 200, response.text
    assert response.json() == {"term": "default"}


def test_defaults_factories_and_validators():
    app = FastAPI()
    calls = []

    class Filters(BaseModel):
        term: str
        tags: list[str] = Field(default_factory=list)

        @model_validator(mode="after")
        def validate_term(self):
            calls.append(self.term)
            return self

    default = Filters(term="parameter default")

    def factory():
        calls.append("factory")
        return Filters(term="factory default")

    @app.get("/")
    def read(filters: Annotated[Filters | None, Query()] = default):
        assert filters is not None
        filters.tags.append("new")
        return filters

    @app.get("/factory")
    def read_factory(
        filters: Annotated[Filters | None, Query(default_factory=factory)],
    ):
        return filters

    @app.get("/validated-default")
    def read_validated_default(
        filters: Annotated[Filters | None, Query(validate_default=True)] = default,
    ):
        return filters

    client = TestClient(app)
    calls.clear()
    for _ in range(2):
        response = client.get("/")
        assert response.status_code == 200, response.text
        assert response.json() == {"term": "parameter default", "tags": ["new"]}
    assert default.tags == []
    assert calls == []
    for _ in range(2):
        response = client.get("/factory")
        assert response.status_code == 200, response.text
        assert response.json() == {"term": "factory default", "tags": []}
    assert calls == ["factory", "factory default", "factory", "factory default"]
    calls.clear()
    response = client.get("/factory", params={"term": "submitted"})
    assert response.status_code == 200, response.text
    assert calls == ["submitted"]
    calls.clear()
    response = client.get("/validated-default")
    assert response.status_code == 200, response.text
    assert calls == ["parameter default"]
    for operation in app.openapi()["paths"].values():
        assert not any(param["required"] for param in operation["get"]["parameters"])


@pytest.mark.parametrize("key", ["q", "search", "term"])
def test_aliases_and_shared_fields(key):
    app = FastAPI()

    class Filters(BaseModel):
        model_config = ConfigDict(extra="forbid", populate_by_name=True)
        term: str = Field(validation_alias=AliasChoices("q", "search"))

    class Other(BaseModel):
        term: str
        limit: int

    @app.get("/")
    def read(
        filters: Annotated[Filters | None, Query()] = None,
        other: Annotated[Other | None, Query()] = None,
    ):
        return [filters, other]

    client = TestClient(app)
    response = client.get("/", params={key: "value"})
    if key == "term":
        assert response.status_code == 422
        assert response.json()["detail"][0]["loc"] == ["query", "limit"]
    else:
        assert response.status_code == 200, response.text
        assert response.json() == [{"term": "value"}, None]
    response = client.get("/", params={key: "value", "term": "value", "limit": "5"})
    assert response.status_code == 422
    assert all(
        error["type"] == "extra_forbidden" for error in response.json()["detail"]
    )
    assert response.json()["detail"][-1]["loc"] == ["query", "limit"]


def test_dependency_override_names():
    app = FastAPI()

    class Filters(BaseModel):
        model_config = ConfigDict(extra="forbid")
        term: str

    def pagination(limit: int = 10):
        return limit

    def replacement(page: int = 1):
        return page

    @app.get("/")
    def read(
        page: Annotated[int, Depends(pagination)],
        filters: Annotated[Filters | None, Query()] = None,
    ):
        return filters

    client = TestClient(app)
    assert client.get("/").json() is None
    response = client.get("/", params={"limit": "5"})
    assert response.status_code == 422
    assert response.json()["detail"][-1]["loc"] == ["query", "limit"]
    app.dependency_overrides[pagination] = replacement
    response = client.get("/", params={"page": "2"})
    assert response.status_code == 422
    assert response.json()["detail"][-1]["loc"] == ["query", "page"]
    assert response.json()["detail"][-1]["type"] == "extra_forbidden"


def test_openapi_required_fields_are_not_mutated():
    app = FastAPI()

    class Filters(BaseModel):
        term: str = Field(alias="q", description="Search term")
        limit: int = Field(10, ge=1)

    @app.get("/optional", response_model=Filters | None)
    def read_optional(filters: Annotated[Filters | None, Query()] = None):
        return filters

    @app.get("/required")
    def read_required(filters: Annotated[Filters | None, Query()]):
        return filters

    @app.get("/plain")
    def read_plain(filters: Annotated[Filters, Query()]):
        return filters

    schema = app.openapi()
    assert schema["paths"]["/optional"]["get"]["parameters"] == [
        {
            "name": "q",
            "in": "query",
            "required": False,
            "schema": {"type": "string", "description": "Search term", "title": "Q"},
            "description": "Search term",
        },
        {
            "name": "limit",
            "in": "query",
            "required": False,
            "schema": {
                "type": "integer",
                "minimum": 1,
                "default": 10,
                "title": "Limit",
            },
        },
    ]
    client = TestClient(app)
    response = client.get("/optional")
    assert response.status_code == 200, response.text
    assert response.json() is None
    for path in ("/required", "/plain"):
        assert schema["paths"][path]["get"]["parameters"][0]["required"] is True
        response = client.get(path)
        assert response.status_code == 422
        response = client.get(path, params={"q": "value"})
        assert response.status_code == 200, response.text
        assert response.json() == {"q": "value", "limit": 10}
    assert schema["components"]["schemas"]["Filters"]["required"] == ["q"]
    assert Filters.model_fields["term"].is_required()


def test_shared_required_parameter_and_hidden_model():
    app = FastAPI()

    class Filters(BaseModel):
        term: str
        limit: int

    @app.get("/")
    def read(term: str, filters: Annotated[Filters | None, Query()] = None):
        return filters

    @app.get("/hidden")
    def read_hidden(
        filters: Annotated[Filters | None, Query(include_in_schema=False)] = None,
    ):
        return filters

    schema = app.openapi()
    assert {
        p["name"]: p["required"] for p in schema["paths"]["/"]["get"]["parameters"]
    } == {
        "term": True,
        "limit": False,
    }
    assert "parameters" not in schema["paths"]["/hidden"]["get"]
    client = TestClient(app)
    response = client.get("/", params={"term": "value"})
    assert response.status_code == 422
    assert response.json()["detail"][0]["loc"] == ["query", "limit"]
    response = client.get("/", params={"term": "value", "limit": "5"})
    assert response.status_code == 200, response.text
    assert response.json() == {"term": "value", "limit": 5}
    response = client.get("/hidden")
    assert response.status_code == 200, response.text
    assert response.json() is None


def test_typing_optional():
    app = FastAPI()

    class Filters(BaseModel):
        term: str

    @app.get("/")
    def read(filters: Optional[Filters] = Query(default=None)):  # noqa: UP045
        return filters

    client = TestClient(app)
    response = client.get("/")
    assert response.status_code == 200, response.text
    assert response.json() is None
    response = client.get("/", params={"term": ""})
    assert response.status_code == 200, response.text
    assert response.json() == {"term": ""}


def test_optional_query_model_in_websocket():
    app = FastAPI()

    class Filters(BaseModel):
        term: str

    @app.websocket("/ws")
    async def read(
        websocket: WebSocket,
        filters: Annotated[Filters | None, Query()] = None,
    ):
        await websocket.accept()
        await websocket.send_json(filters.model_dump() if filters is not None else None)
        await websocket.close()

    client = TestClient(app)
    with client.websocket_connect("/ws") as websocket:
        assert websocket.receive_json() is None
    with client.websocket_connect("/ws?term=value") as websocket:
        assert websocket.receive_json() == {"term": "value"}