httpserver: json matcher

csernazs · csernazs · commit 25e9214a0796 · 2020-10-17T09:59:41.000+02:00
Add the new parameter 'json' to the expect* functions: expect_request expect_oneshot_request expect_ordered_request This will match the body of the request, in a way that the request body will be first loaded as json, then it will be compared to the value specified for the parameter. Fixes #41.
diff --git a/README.md b/README.md
@@ -16,6 +16,7 @@ the pre-defined expected http requests and their responses.
 
 ### Example
 
+#### Handling a simple GET request
 ```python
 def test_my_client(httpserver): # httpserver is a pytest fixture which starts the server
     # set up the server to serve /foobar with the json
@@ -24,6 +25,16 @@ def test_my_client(httpserver): # httpserver is a pytest fixture which starts th
     assert requests.get(httpserver.url_for("/foobar")).json() == {'foo': 'bar'}
 ```
 
+#### Handing a POST request with an expected json body
+```python
+def test_json_request(httpserver): # httpserver is a pytest fixture which starts the server
+    # set up the server to serve /foobar with the json
+    httpserver.expect_request("/foobar", method="POST", json={"id": 12, "name": "foo"}).respond_with_json({"foo": "bar"})
+    # check that the request is served
+    assert requests.post(httpserver.url_for("/foobar"), json={"id": 12, "name": "foo"}).json() == {'foo': 'bar'}
+```
+
+
 You can also use the library without pytest. There's a with statement to ensure that the server is stopped.
 
 
diff --git a/doc/howto.rst b/doc/howto.rst
@@ -153,6 +153,51 @@ order of the parameters in the ``Authorization`` header does not matter.
         assert response.text == 'OK'
 
 
+JSON matching
+-------------
+
+Matching the request data can be done in two different ways. One way is to
+provide a python string (or bytes object) whose value will be compared to the
+request body.
+
+When the request contains a json, matching to will be error prone as an object
+can be represented as json in different ways, for example when different length
+of indentation is used.
+
+To match the body as json, you need to add the python data structure (which
+could be dict, list or anything which can be the result of `json.loads()` call).
+The request's body will be loaded as json and the result will be compared to the
+provided object. If the request's body cannot be loaded as json, the matcher
+will fail and *pytest-httpserver* will proceed with the next registered matcher.
+
+Example:
+
+.. code:: python
+
+    def test_json_matcher(httpserver: HTTPServer):
+        httpserver.expect_request("/foo", json={"foo": "bar"}).respond_with_data("Hello world!")
+        resp = requests.get(httpserver.url_for("/foo"), json={"foo": "bar"})
+        assert resp.status_code == 200
+        assert resp.text == "Hello world!"
+
+
+.. note::
+    JSON requests usually come with ``Content-Type: application/json`` header.
+    *pytest-httpserver* provides the *headers* parameter to match the headers of
+    the request, however matching json body does not imply matching the
+    *Content-Type* header. If matching the header is intended, specify the expected
+    *Content-Type* header and its value to the headers parameter.
+
+.. note::
+    *json* and *data* parameters are mutually exclusive so both of then cannot
+    be specified as in such case the behavior is ambiguous.
+
+.. note::
+    The request body is decoded by using the *data_encoding* parameter, which is
+    default to *utf-8*. If the request comes in a different encoding, and the
+    decoding fails, the request won't match with the expected json.
+
+
 Advanced header matching
 ------------------------
 
diff --git a/pytest_httpserver/httpserver.py b/pytest_httpserver/httpserver.py
@@ -8,20 +8,30 @@
 from enum import Enum
 from contextlib import suppress, contextmanager
 from copy import copy
-from typing import Callable, Mapping, Optional, Union, Pattern
+from typing import Any, Callable, Mapping, Optional, Union, Pattern
 from ssl import SSLContext
 import abc
 
 from werkzeug.http import parse_authorization_header
 from werkzeug.serving import make_server
-from werkzeug.wrappers import Request, Response
+from werkzeug.wrappers import Request
+from werkzeug.wrappers import Response
+
 import werkzeug.urls
 from werkzeug.datastructures import MultiDict
 
 URI_DEFAULT = ""
 METHOD_ALL = "__ALL"
 
 
+class Undefined:
+    def __repr__(self):
+        return "<UNDEFINED>"
+
+
+UNDEFINED = Undefined()
+
+
 class Error(Exception):
     """
     Base class for all exception defined in this package.
@@ -273,12 +283,17 @@ def __init__(
             data_encoding: str = "utf-8",
             headers: Optional[Mapping[str, str]] = None,
             query_string: Union[None, QueryMatcher, str, bytes, Mapping] = None,
-            header_value_matcher: Optional[HeaderValueMatcher] = None):
+            header_value_matcher: Optional[HeaderValueMatcher] = None,
+            json: Any = UNDEFINED):
+
+        if json is not UNDEFINED and data is not None:
+            raise ValueError("data and json parameters are mutually exclusive")
 
         self.uri = uri
         self.method = method
         self.query_string = query_string
         self.query_matcher = _create_query_matcher(self.query_string)
+        self.json = json
 
         if headers is None:
             self.headers = {}
@@ -289,6 +304,7 @@ def __init__(
             data = data.encode(data_encoding)
 
         self.data = data
+        self.data_encoding = data_encoding
 
         self.header_value_matcher = HeaderValueMatcher() if header_value_matcher is None else header_value_matcher
 
@@ -299,7 +315,8 @@ def __repr__(self):
 
         class_name = self.__class__.__name__
         retval = "<{} ".format(class_name)
-        retval += "uri={uri!r} method={method!r} query_string={query_string!r} headers={headers!r} data={data!r}>".format_map(self.__dict__)
+        retval += "uri={uri!r} method={method!r} query_string={query_string!r} headers={headers!r} data={data!r} json={json!r}>".format_map(
+            self.__dict__)
         return retval
 
     def match_data(self, request: Request) -> bool:
@@ -335,6 +352,30 @@ def match_uri(self, request: Request) -> bool:
 
             return self.uri == URI_DEFAULT or path == self.uri
 
+    def match_json(self, request: Request) -> bool:
+        """
+        Matches the request data as json.
+
+        Load the request data as json and compare it to self.json which is a
+        json-serializable data structure (eg. a dict or list).
+
+        :param request: the HTTP request
+        :return: `True` when the data is matched or no matching is required. `False` otherwise.
+        """
+        if self.json is UNDEFINED:
+            return True
+
+        try:
+            # do the decoding here as python 3.5 requires string and does not
+            # accept bytes
+            json_received = json.loads(request.data.decode(self.data_encoding))
+        except json.JSONDecodeError:
+            return False
+        except UnicodeDecodeError:
+            return False
+
+        return json_received == self.json
+
     def difference(self, request: Request) -> list:
         """
         Calculates the difference between the matcher and the request.
@@ -371,6 +412,8 @@ def difference(self, request: Request) -> list:
         if not self.match_data(request):
             retval.append(("data", request.data, self.data))
 
+        if not self.match_json(request):
+            retval.append(("json", request.data, self.json))
         return retval
 
     def match(self, request: Request) -> bool:
@@ -614,7 +657,8 @@ def expect_request(
             headers: Optional[Mapping[str, str]] = None,
             query_string: Union[None, QueryMatcher, str, bytes, Mapping] = None,
             header_value_matcher: Optional[HeaderValueMatcher] = None,
-            handler_type: HandlerType = HandlerType.PERMANENT) -> RequestHandler:
+            handler_type: HandlerType = HandlerType.PERMANENT,
+            json: Any = UNDEFINED) -> RequestHandler:
         """
         Create and register a request handler.
 
@@ -647,8 +691,13 @@ def expect_request(
             object from werkzeug.
         :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches values of headers.
         :param handler_type: type of handler
+        :param json: a python object (eg. a dict) whose value will be compared to the request body after it
+            is loaded as json. If load fails, this matcher will be failed also. *Content-Type* is not checked.
+            If that's desired, add it to the headers parameter.
 
         :return: Created and register :py:class:`RequestHandler`.
+
+        Parameters `json` and `data` are mutually exclusive.
         """
 
         matcher = self.create_matcher(
@@ -659,6 +708,7 @@ def expect_request(
             headers=headers,
             query_string=query_string,
             header_value_matcher=header_value_matcher,
+            json=json,
         )
         request_handler = RequestHandler(matcher)
         if handler_type == HandlerType.PERMANENT:
@@ -677,7 +727,8 @@ def expect_oneshot_request(
             data_encoding: str = "utf-8",
             headers: Optional[Mapping[str, str]] = None,
             query_string: Union[None, QueryMatcher, str, bytes, Mapping] = None,
-            header_value_matcher: Optional[HeaderValueMatcher] = None) -> RequestHandler:
+            header_value_matcher: Optional[HeaderValueMatcher] = None,
+            json: Any = UNDEFINED) -> RequestHandler:
         """
         Create and register a oneshot request handler.
 
@@ -698,8 +749,13 @@ def expect_oneshot_request(
             value will be used. If multiple values needed to be handled, use ``MultiDict``
             object from werkzeug.
         :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches values of headers.
+        :param json: a python object (eg. a dict) whose value will be compared to the request body after it
+            is loaded as json. If load fails, this matcher will be failed also. *Content-Type* is not checked.
+            If that's desired, add it to the headers parameter.
 
         :return: Created and register :py:class:`RequestHandler`.
+
+        Parameters `json` and `data` are mutually exclusive.
         """
 
         return self.expect_request(
@@ -711,6 +767,7 @@ def expect_oneshot_request(
             query_string=query_string,
             header_value_matcher=header_value_matcher,
             handler_type=HandlerType.ONESHOT,
+            json=json,
         )
 
     def expect_ordered_request(
@@ -721,7 +778,8 @@ def expect_ordered_request(
             data_encoding: str = "utf-8",
             headers: Optional[Mapping[str, str]] = None,
             query_string: Union[None, QueryMatcher, str, bytes, Mapping] = None,
-            header_value_matcher: Optional[HeaderValueMatcher] = None) -> RequestHandler:
+            header_value_matcher: Optional[HeaderValueMatcher] = None,
+            json: Any = UNDEFINED) -> RequestHandler:
         """
         Create and register a ordered request handler.
 
@@ -742,8 +800,13 @@ def expect_ordered_request(
             value will be used. If multiple values needed to be handled, use ``MultiDict``
             object from werkzeug.
         :param header_value_matcher: :py:class:`HeaderValueMatcher` that matches values of headers.
+        :param json: a python object (eg. a dict) whose value will be compared to the request body after it
+            is loaded as json. If load fails, this matcher will be failed also. *Content-Type* is not checked.
+            If that's desired, add it to the headers parameter.
 
         :return: Created and register :py:class:`RequestHandler`.
+
+        Parameters `json` and `data` are mutually exclusive.
         """
 
         return self.expect_request(
@@ -755,6 +818,7 @@ def expect_ordered_request(
             query_string=query_string,
             header_value_matcher=header_value_matcher,
             handler_type=HandlerType.ORDERED,
+            json=json,
         )
 
     def thread_target(self):
diff --git a/releasenotes/notes/json-matcher-1d030e3b4f9b66bd.yaml b/releasenotes/notes/json-matcher-1d030e3b4f9b66bd.yaml
@@ -0,0 +1,6 @@
+---
+features:
+  - |
+    It is now possible to specify a JSON-serializable python value (such as
+    dict, list, etc) and match the request to it as JSON. The request's body
+    is loaded as JSON and it will be compared to the expected value.
diff --git a/tests/test_json_matcher.py b/tests/test_json_matcher.py
@@ -0,0 +1,40 @@
+
+import json
+from pytest_httpserver import HTTPServer
+
+import requests
+import pytest
+
+
+def test_json_matcher(httpserver: HTTPServer):
+    httpserver.expect_request("/foo", json={"foo": "bar"}).respond_with_data("Hello world!")
+    assert requests.get(httpserver.url_for("/foo")).status_code == 500
+    resp = requests.get(httpserver.url_for("/foo"), json={"foo": "bar"})
+    assert resp.status_code == 200
+    assert resp.text == "Hello world!"
+    assert requests.get(httpserver.url_for("/foo"), json={"foo": "bar", "foo2": "bar2"}).status_code == 500
+
+
+def test_json_matcher_with_none(httpserver: HTTPServer):
+    httpserver.expect_request("/foo", json=None).respond_with_data("Hello world!")
+    resp = requests.get(httpserver.url_for("/foo"), data=json.dumps(None), headers={"content-type": "application/json"})
+    assert resp.status_code == 200
+    assert resp.text == "Hello world!"
+
+
+def test_json_matcher_without_content_type(httpserver: HTTPServer):
+    httpserver.expect_request("/foo", json={"foo": "bar"}).respond_with_data("Hello world!")
+    assert requests.get(httpserver.url_for("/foo"), json={"foo": "bar"}).status_code == 200
+    assert requests.get(httpserver.url_for("/foo"), data=json.dumps({"foo": "bar"})).status_code == 200
+
+
+def test_json_matcher_with_invalid_json(httpserver: HTTPServer):
+    httpserver.expect_request("/foo", json={"foo": "bar"}).respond_with_data("Hello world!")
+    assert requests.get(httpserver.url_for("/foo"), data="invalid-json").status_code == 500
+    assert requests.get(httpserver.url_for("/foo"), data='{"invalid": "json"').status_code == 500
+    assert requests.get(httpserver.url_for("/foo"), data=b"non-text\x1f\x8b").status_code == 500
+
+
+def test_data_and_json_mutually_exclusive(httpserver: HTTPServer):
+    with pytest.raises(ValueError):
+        httpserver.expect_request("/foo", json={}, data="foo")
