hooks: implementation of the hooks API

csernazs · csernazs · commit 50141e0f6782 · 2024-07-10T12:09:00.000+02:00
diff --git a/doc/api.rst b/doc/api.rst
@@ -100,3 +100,19 @@ by the user.
 
     .. autoclass:: pytest_httpserver.httpserver.RequestHandlerList
         :members:
+
+
+pytest_httpserver.hooks
+-----------------------
+
+.. automodule:: pytest_httpserver.hooks
+
+
+    .. autoclass:: pytest_httpserver.hooks.Chain
+        :members:
+
+    .. autoclass:: pytest_httpserver.hooks.Delay
+        :members:
+
+    .. autoclass:: pytest_httpserver.hooks.Garbage
+        :members:
diff --git a/doc/howto.rst b/doc/howto.rst
@@ -612,3 +612,49 @@ fixture so you can keep the original single-threaded behavior.
     that all threads are properly cleaned up and you want to wait for them,
     consider using the second option (:ref:`Creating a different httpserver fixture`)
     described above.
+
+
+Adding side effects
+-------------------
+
+Sometimes there's a need to add side effects to the handling of the requests.
+Such side effect could be adding some amount of delay to the serving or adding
+some garbage to response data.
+
+While these can be achieved by using
+:py:meth:`pytest_httpserver.RequestHandler.respond_with_handler` where you can
+implement your own function to serve the request, *pytest-httpserver* provides a
+hooks API where you can add side effects to request handlers such as
+:py:meth:`pytest_httpserver.RequestHandler.respond_with_json` and others.
+This allows to use the existing API of registering handlers.
+
+Example:
+
+.. literalinclude :: ../tests/examples/test_howto_hooks.py
+    :language: python
+
+:py:mod:`pytest_httpserver.hooks` module provides some pre-defined hooks to
+use.
+
+You can implement your own hook as well. The requirement is to have a callable
+object (a function) ``Callable[[Request, Response], Response]``. In details:
+
+* Parameter :py:class:`werkzeug.wrappers.Request` which represents the request
+  sent by the client.
+
+* Parameter :py:class:`werkzeug.wrappers.Response` which represents the response
+  made by the handler.
+
+* Returns a :py:class:`werkzeug.wrappers.Response` object which represents the
+  response will be returned to the client.
+
+
+Example:
+
+.. literalinclude :: ../tests/examples/test_howto_custom_hooks.py
+    :language: python
+
+``with_hook`` can be called multiple times, in this case *pytest-httpserver*
+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.
diff --git a/pytest_httpserver/hooks.py b/pytest_httpserver/hooks.py
@@ -0,0 +1,103 @@
+"""
+Hooks for pytest-httpserver
+"""
+
+import os
+import time
+from typing import Callable
+
+from werkzeug import Request
+from werkzeug import Response
+
+
+class Chain:
+    """
+    Combine multiple hooks into one callable object
+
+    Hooks specified will be called one by one.
+
+    Each hook will receive the response object made by the previous hook,
+    similar to reduce.
+    """
+
+    def __init__(self, *args: Callable[[Request, Response], Response]):
+        """
+        :param *args: callable objects specified in the same order they should
+            be called.
+        """
+        self._hooks = args
+
+    def __call__(self, request: Request, response: Response) -> Response:
+        """
+        Calls the callable object one by one. The second and further callable
+        objects receive the response returned by the previous one, while the
+        first one receives the original response object.
+        """
+        for hook in self._hooks:
+            response = hook(request, response)
+        return response
+
+
+class Delay:
+    """
+    Delays returning the response
+    """
+
+    def __init__(self, seconds: float):
+        """
+        :param seconds: seconds to sleep before returning the response
+        """
+        self._seconds = seconds
+
+    def _sleep(self):
+        """
+        Sleeps for the seconds specified in the constructor
+        """
+        time.sleep(self._seconds)
+
+    def __call__(self, _request: Request, response: Response) -> Response:
+        """
+        Delays returning the response object for the time specified in the
+        constructor. Returns the original response unmodified.
+        """
+        self._sleep()
+        return response
+
+
+class Garbage:
+    def __init__(self, prefix_size: int = 0, suffix_size: int = 0):
+        """
+        Adds random bytes to the beginning or to the end of the response data.
+
+        :param prefix_size: amount of random bytes to be added to the beginning
+            of the response data
+
+        :param suffix_size: amount of random bytes to be added to the end
+            of the response data
+
+        """
+        assert prefix_size >= 0, "prefix_size should be positive integer"
+        assert suffix_size >= 0, "suffix_size should be positive integer"
+        self._prefix_size = prefix_size
+        self._suffix_size = suffix_size
+
+    def _get_garbage_bytes(self, size: int) -> bytes:
+        """
+        Returns the specified amount of random bytes.
+
+        :param size: amount of bytes to return
+        """
+        return os.urandom(size)
+
+    def __call__(self, _request: Request, response: Response) -> Response:
+        """
+        Adds random bytes to the beginning or to the end of the response data.
+
+        New random bytes will be generated for every call.
+
+        Returns the modified response object.
+        """
+        prefix = self._get_garbage_bytes(self._prefix_size)
+        suffix = self._get_garbage_bytes(self._suffix_size)
+        response.set_data(prefix + response.get_data() + suffix)
+        return response
diff --git a/pytest_httpserver/httpserver.py b/pytest_httpserver/httpserver.py
@@ -529,6 +529,11 @@ class RequestHandler(RequestHandlerBase):
     def __init__(self, matcher: RequestMatcher):
         self.matcher = matcher
         self.request_handler: Callable[[Request], Response] | None = None
+        self._hooks: list[Callable[[Request, Response], Response]] = []
+
+    def with_hook(self, hook: Callable[[Request, Response], Response]):
+        self._hooks.append(hook)
+        return self
 
     def respond(self, request: Request) -> Response:
         """
@@ -546,7 +551,11 @@ def respond(self, request: Request) -> Response:
                 "Matching request handler found but no response defined: {} {}".format(request.method, request.path)
             )
         else:
-            return self.request_handler(request)
+            response = self.request_handler(request)
+
+            for hook in self._hooks:
+                response = hook(request, response)
+            return response
 
     def respond_with_handler(self, func: Callable[[Request], Response]):
         """
diff --git a/releasenotes/notes/hooks-306915ded3b2771f.yaml b/releasenotes/notes/hooks-306915ded3b2771f.yaml
@@ -0,0 +1,4 @@
+---
+features:
+  - |
+    Hooks API
diff --git a/tests/examples/test_howto_custom_hooks.py b/tests/examples/test_howto_custom_hooks.py
@@ -0,0 +1,17 @@
+import requests
+from werkzeug.wrappers import Request
+from werkzeug.wrappers import Response
+
+from pytest_httpserver import HTTPServer
+
+
+def my_hook(_request: Request, response: Response) -> Response:
+    # add a new header value to the response
+    response.headers["X-Example"] = "Example"
+    return response
+
+
+def test_custom_hook(httpserver: HTTPServer):
+    httpserver.expect_request("/foo").with_hook(my_hook).respond_with_data(b"OK")
+
+    assert requests.get(httpserver.url_for("/foo")).headers["X-Example"] == "Example"
diff --git a/tests/examples/test_howto_hooks.py b/tests/examples/test_howto_hooks.py
@@ -0,0 +1,11 @@
+import requests
+
+from pytest_httpserver import HTTPServer
+from pytest_httpserver.hooks import Delay
+
+
+def test_delay(httpserver: HTTPServer):
+    # this adds 0.5 seconds delay to the server response
+    httpserver.expect_request("/foo").with_hook(Delay(0.5)).respond_with_json({"example": "foo"})
+
+    assert requests.get(httpserver.url_for("/foo")).json() == {"example": "foo"}
diff --git a/tests/test_hooks.py b/tests/test_hooks.py
@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+import requests
+
+from pytest_httpserver.hooks import Chain
+from pytest_httpserver.hooks import Delay
+from pytest_httpserver.hooks import Garbage
+
+if TYPE_CHECKING:
+    from werkzeug.wrappers import Request
+    from werkzeug.wrappers import Response
+
+    from pytest_httpserver import HTTPServer
+
+
+class MyDelay(Delay):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.evidence: int | None = None
+
+    def _sleep(self):
+        assert self.evidence is None, "_sleep should be called only once"
+        self.evidence = self._seconds
+
+
+def my_hook(_request: Request, response: Response) -> Response:
+    response.set_data(response.get_data() + b"-SUFFIX")
+    return response
+
+
+def test_hook(httpserver: HTTPServer):
+
+    httpserver.expect_request("/foo").with_hook(my_hook).respond_with_data("OK")
+
+    assert requests.get(httpserver.url_for("/foo")).text == "OK-SUFFIX"
+
+
+def test_delay_hook(httpserver: HTTPServer):
+    delay = MyDelay(10)
+    httpserver.expect_request("/foo").with_hook(delay).respond_with_data("OK")
+    assert requests.get(httpserver.url_for("/foo")).text == "OK"
+    assert delay.evidence == 10
+
+
+def test_garbage_hook(httpserver: HTTPServer):
+    httpserver.expect_request("/prefix").with_hook(Garbage(prefix_size=128)).respond_with_data("OK")
+    httpserver.expect_request("/suffix").with_hook(Garbage(suffix_size=128)).respond_with_data("OK")
+    httpserver.expect_request("/both").with_hook(Garbage(prefix_size=128, suffix_size=128)).respond_with_data("OK")
+    httpserver.expect_request("/large_prefix").with_hook(Garbage(prefix_size=10 * 1024 * 1024)).respond_with_data("OK")
+
+    resp_content = requests.get(httpserver.url_for("/prefix")).content
+    assert len(resp_content) == 130
+    assert resp_content[128:] == b"OK"
+
+    resp_content = requests.get(httpserver.url_for("/large_prefix")).content
+    assert len(resp_content) == 10 * 1024 * 1024 + 2
+    assert resp_content[10 * 1024 * 1024 :] == b"OK"
+
+    resp_content = requests.get(httpserver.url_for("/suffix")).content
+    assert len(resp_content) == 130
+    assert resp_content[:2] == b"OK"
+
+    resp_content = requests.get(httpserver.url_for("/both")).content
+    assert len(resp_content) == 258
+    assert resp_content[128:130] == b"OK"
+
+    with pytest.raises(AssertionError, match="prefix_size should be positive integer"):
+        Garbage(-10)
+
+    with pytest.raises(AssertionError, match="suffix_size should be positive integer"):
+        Garbage(10, -10)
+
+
+def test_chain(httpserver: HTTPServer):
+    delay = MyDelay(10)
+    httpserver.expect_request("/foo").with_hook(Chain(delay, Garbage(128))).respond_with_data("OK")
+    assert len(requests.get(httpserver.url_for("/foo")).content) == 130
+    assert delay.evidence == 10
+
+
+def test_multiple_hooks(httpserver: HTTPServer):
+    delay = MyDelay(10)
+    httpserver.expect_request("/foo").with_hook(delay).with_hook(Garbage(128)).respond_with_data("OK")
+    assert len(requests.get(httpserver.url_for("/foo")).content) == 130
+    assert delay.evidence == 10
diff --git a/tests/test_release.py b/tests/test_release.py
@@ -155,6 +155,7 @@ def test_wheel_no_extra_contents(build: Build, version: str):
     assert package_contents == {
         "__init__.py",
         "blocking_httpserver.py",
+        "hooks.py",
         "httpserver.py",
         "py.typed",
         "pytest_plugin.py",
@@ -196,6 +197,7 @@ def test_sdist_contents(build: Build, version: str):
         "pytest_httpserver": {
             "__init__.py",
             "blocking_httpserver.py",
+            "hooks.py",
             "httpserver.py",
             "py.typed",
             "pytest_plugin.py",
@@ -207,6 +209,7 @@ def test_sdist_contents(build: Build, version: str):
             "test_blocking_httpserver.py",
             "test_handler_errors.py",
             "test_headers.py",
+            "test_hooks.py",
             "test_ip_protocols.py",
             "test_json_matcher.py",
             "test_log_querying.py",

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +---
 +features:
 +  - |
 +    Hooks API