Add bake() method for pre-configured request expectations

Author: HayaoSuzuki

doc/api.rst

@@ -31,6 +31,12 @@ RequestMatcher
         :members:
 
 
+BakedHTTPServer
+~~~~~~~~~~~~~~~~
+
+    .. autoclass:: BakedHTTPServer
+        :members:
+
 BlockingHTTPServer
 ~~~~~~~~~~~~~~~~~~
 

doc/howto.rst

@@ -704,3 +704,29 @@ Example:
 will register the hooks, and hooks will be called sequentially, one by one. Each
 hook will receive the response what the previous hook returned, and the last
 hook called will return the final response which will be sent back to the client.
+
+
+Reducing repetition with bake
+-----------------------------
+
+When multiple expectations share common parameters (such as headers or method),
+the ``bake()`` method creates a proxy with pre-configured defaults. Keyword
+arguments passed to ``bake()`` become defaults that are merged with arguments
+provided at call time using last-wins semantics: if the same keyword appears in
+both, the call-time value is used.
+
+.. literalinclude :: ../tests/examples/test_howto_bake.py
+   :language: python
+
+The ``bake()`` method can be chained to layer additional defaults:
+
+.. code-block:: python
+
+    json_post = httpserver.bake(method="POST").bake(
+        headers={"Content-Type": "application/json"}
+    )
+
+All ``expect_request``, ``expect_oneshot_request``, and
+``expect_ordered_request`` methods are available on the baked object. Other
+attributes such as ``url_for()`` and ``check_assertions()`` are delegated to
+the underlying server transparently.

pytest_httpserver/__init__.py

@@ -6,6 +6,7 @@
 __all__ = [
     "METHOD_ALL",
     "URI_DEFAULT",
+    "BakedHTTPServer",
     "BlockingHTTPServer",
     "BlockingRequestHandler",
     "Error",
@@ -23,6 +24,7 @@
 from .blocking_httpserver import BlockingRequestHandler
 from .httpserver import METHOD_ALL
 from .httpserver import URI_DEFAULT
+from .httpserver import BakedHTTPServer
 from .httpserver import Error
 from .httpserver import HeaderValueMatcher
 from .httpserver import HTTPServer

pytest_httpserver/httpserver.py

@@ -1495,3 +1495,97 @@ def assert_request_made(self, matcher: RequestMatcher, *, count: int = 1) -> Non
             assert_msg = "\n".join(assert_msg_lines) + "\n"
 
             assert matching_count == count, assert_msg
+
+    def bake(self, **kwargs: Any) -> BakedHTTPServer:
+        """
+        Create a proxy with pre-configured defaults for ``expect_request()``.
+
+        Keyword arguments passed here become defaults for ``expect_request()``
+        and related methods. When the same keyword is provided both at bake
+        time and at call time, the call-time value wins (last-wins merging).
+
+        :param kwargs: default keyword arguments for ``expect_request()`` and
+            related methods (e.g. ``method``, ``headers``, ``json``, etc.).
+        :return: a :py:class:`BakedHTTPServer` proxy object.
+
+        Example:
+
+        .. code-block:: python
+
+            json_server = httpserver.bake(headers={"content-type": "application/json"})
+            json_server.expect_request("/foo").respond_with_json({"result": "ok"})
+        """
+        return BakedHTTPServer(self, **kwargs)
+
+
+class BakedHTTPServer:
+    """
+    A proxy for :py:class:`HTTPServer` with pre-configured defaults for
+    ``expect_request()`` and related methods.
+
+    Created via :py:meth:`HTTPServer.bake`. Keyword arguments stored at bake
+    time are merged with arguments provided at call time using last-wins
+    semantics: if the same keyword appears in both, the call-time value is
+    used.
+
+    Any attribute not explicitly defined here is delegated to the wrapped
+    :py:class:`HTTPServer`, so ``url_for()``, ``check_assertions()``, etc.
+    work transparently.
+    """
+
+    def __init__(self, server: HTTPServer, **kwargs: Any) -> None:
+        self._server = server
+        self._defaults = kwargs
+
+    def __enter__(self) -> Self:
+        self._server.__enter__()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self._server.__exit__(exc_type, exc_value, traceback)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._server, name)
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__} defaults={self._defaults!r} server={self._server!r}>"
+
+    def _merge_kwargs(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        return {**self._defaults, **kwargs}
+
+    def bake(self, **kwargs: Any) -> Self:
+        """
+        Create a new :py:class:`BakedHTTPServer` by further layering defaults.
+
+        The new proxy merges the current defaults with the new ``kwargs``.
+        """
+        return self.__class__(self._server, **self._merge_kwargs(kwargs))
+
+    def expect_request(
+        self,
+        uri: str | URIPattern | Pattern[str],
+        **kwargs: Any,
+    ) -> RequestHandler:
+        """Create and register a request handler, using baked defaults."""
+        return self._server.expect_request(uri, **self._merge_kwargs(kwargs))
+
+    def expect_oneshot_request(
+        self,
+        uri: str | URIPattern | Pattern[str],
+        **kwargs: Any,
+    ) -> RequestHandler:
+        """Create and register a oneshot request handler, using baked defaults."""
+        return self._server.expect_oneshot_request(uri, **self._merge_kwargs(kwargs))
+
+    def expect_ordered_request(
+        self,
+        uri: str | URIPattern | Pattern[str],
+        **kwargs: Any,
+    ) -> RequestHandler:
+        """Create and register an ordered request handler, using baked defaults."""
+        return self._server.expect_ordered_request(uri, **self._merge_kwargs(kwargs))

tests/examples/test_howto_bake.py

@@ -0,0 +1,25 @@
+import requests
+
+from pytest_httpserver import HTTPServer
+
+
+def test_bake_json_api(httpserver: HTTPServer) -> None:
+    # bake common defaults so you don't repeat them for every expect_request
+    json_api = httpserver.bake(method="POST", headers={"Content-Type": "application/json"})
+
+    json_api.expect_request("/users").respond_with_json({"id": 1, "name": "Alice"}, status=201)
+    json_api.expect_request("/items").respond_with_json({"id": 42, "name": "Widget"}, status=201)
+
+    resp = requests.post(
+        httpserver.url_for("/users"),
+        json={"name": "Alice"},
+    )
+    assert resp.status_code == 201
+    assert resp.json() == {"id": 1, "name": "Alice"}
+
+    resp = requests.post(
+        httpserver.url_for("/items"),
+        json={"name": "Widget"},
+    )
+    assert resp.status_code == 201
+    assert resp.json() == {"id": 42, "name": "Widget"}

tests/test_bake.py

@@ -0,0 +1,126 @@
+from collections.abc import Callable
+
+import pytest
+import requests
+
+from pytest_httpserver import BakedHTTPServer
+from pytest_httpserver import HTTPServer
+
+
+def test_bake_with_headers(httpserver: HTTPServer) -> None:
+    server = httpserver.bake(headers={"Content-Type": "application/json"})
+    server.expect_request("/foo").respond_with_json({"result": "ok"})
+
+    response = requests.get(
+        httpserver.url_for("/foo"),
+        headers={"Content-Type": "application/json"},
+    )
+    assert response.status_code == 200
+    assert response.json() == {"result": "ok"}
+
+
+@pytest.mark.parametrize(
+    ("bake_chain", "expect_kwargs", "request_method"),
+    [
+        pytest.param(
+            lambda s: s.bake(method="POST"),
+            {},
+            "POST",
+            id="bake-default",
+        ),
+        pytest.param(
+            lambda s: s.bake(method="GET"),
+            {"method": "POST"},
+            "POST",
+            id="call-time-override",
+        ),
+        pytest.param(
+            lambda s: s.bake(method="GET").bake(method="POST"),
+            {},
+            "POST",
+            id="chained-override",
+        ),
+    ],
+)
+def test_bake_method_resolution(
+    httpserver: HTTPServer,
+    bake_chain: Callable[[HTTPServer], BakedHTTPServer],
+    expect_kwargs: dict,
+    request_method: str,
+) -> None:
+    server = bake_chain(httpserver)
+    server.expect_request("/endpoint", **expect_kwargs).respond_with_data("ok")
+
+    response = requests.request(request_method, httpserver.url_for("/endpoint"))
+    assert response.status_code == 200
+    assert response.text == "ok"
+
+
+def test_bake_chained(httpserver: HTTPServer) -> None:
+    server = httpserver.bake(method="POST").bake(headers={"X-Custom": "value"})
+    server.expect_request("/chain").respond_with_data("chained")
+
+    response = requests.post(
+        httpserver.url_for("/chain"),
+        headers={"X-Custom": "value"},
+    )
+    assert response.status_code == 200
+    assert response.text == "chained"
+
+
+def test_bake_oneshot(httpserver: HTTPServer) -> None:
+    server = httpserver.bake(method="PUT")
+    server.expect_oneshot_request("/once").respond_with_data("once")
+
+    response = requests.put(httpserver.url_for("/once"))
+    assert response.status_code == 200
+    assert response.text == "once"
+
+    response = requests.put(httpserver.url_for("/once"))
+    assert response.status_code == 500
+
+
+def test_bake_ordered(httpserver: HTTPServer) -> None:
+    server = httpserver.bake(method="GET")
+    server.expect_ordered_request("/first").respond_with_data("1")
+    server.expect_ordered_request("/second").respond_with_data("2")
+
+    response = requests.get(httpserver.url_for("/first"))
+    assert response.status_code == 200
+    assert response.text == "1"
+
+    response = requests.get(httpserver.url_for("/second"))
+    assert response.status_code == 200
+    assert response.text == "2"
+
+
+def test_bake_delegates_url_for(httpserver: HTTPServer) -> None:
+    server = httpserver.bake(method="GET")
+    assert server.url_for("/path") == httpserver.url_for("/path")
+
+
+def test_bake_context_manager() -> None:
+    server = HTTPServer()
+    baked = server.bake(method="GET")
+    with baked:
+        assert server.is_running()
+        baked.expect_request("/ctx").respond_with_data("ok")
+        response = requests.get(baked.url_for("/ctx"))
+        assert response.status_code == 200
+        assert response.text == "ok"
+    assert not server.is_running()
+
+
+@pytest.mark.parametrize(
+    "bake_chain",
+    [
+        pytest.param(lambda s: s.bake(method="GET"), id="single"),
+        pytest.param(lambda s: s.bake(method="GET").bake(headers={"X-Foo": "bar"}), id="chained"),
+    ],
+)
+def test_bake_returns_baked_type(
+    httpserver: HTTPServer,
+    bake_chain: Callable[[HTTPServer], BakedHTTPServer],
+) -> None:
+    server = bake_chain(httpserver)
+    assert isinstance(server, BakedHTTPServer)