JSON request/response mixin

AUTHORS

@@ -9,6 +9,7 @@ Development Lead
 Patches and Suggestions
 ```````````````````````
 
+- Adam Byrtek
 - Adam Zapletal
 - Ali Afshar
 - Chris Edgemon

CHANGES

@@ -11,6 +11,11 @@ Version 0.12
   See pull request ``#1849``.
 - Make ``flask.safe_join`` able to join multiple paths like ``os.path.join``
   (pull request ``#1730``).
+- Added `json` keyword argument to :meth:`flask.testing.FlaskClient.open`
+  (and related ``get``, ``post``, etc.), which makes it more convenient to
+  send JSON requests from the test client.
+- Added ``is_json`` and ``get_json`` to :class:``flask.wrappers.Response``
+  in order to make it easier to build assertions when testing JSON responses.
 
 Version 0.11.2
 --------------

docs/api.rst

@@ -29,7 +29,7 @@ Incoming Request Data
 ---------------------
 
 .. autoclass:: Request
-   :members:
+   :members: is_json, get_json
 
    .. attribute:: form
 
@@ -141,7 +141,7 @@ Response Objects
 ----------------
 
 .. autoclass:: flask.Response
-   :members: set_cookie, data, mimetype
+   :members: set_cookie, data, mimetype, is_json, get_json
 
    .. attribute:: headers
 

docs/testing.rst

@@ -353,3 +353,35 @@ independently of the session backend used::
 Note that in this case you have to use the ``sess`` object instead of the
 :data:`flask.session` proxy.  The object however itself will provide the
 same interface.
+
+
+Testing JSON APIs
+-----------------
+
+.. versionadded:: 1.0
+
+Flask has great support for JSON, and is a popular choice for building REST
+APIs. Testing both JSON requests and responses using the test client is very
+convenient::
+
+    from flask import jsonify
+
+    @app.route('/api/auth')
+    def auth():
+        json_data = request.get_json()
+        email = json_data['email']
+        password = json_data['password']
+
+        return jsonify(token=generate_token(email, password))
+
+    with app.test_client() as c:
+        email = '[email protected]'
+        password = 'secret'
+        resp = c.post('/api/auth', json={'login': email, 'password': password})
+
+        json_data = resp.get_json()
+        assert verify_token(email, json_data['token'])
+
+Note that if the ``json`` argument is provided then the test client will put
+JSON-serialized data in the request body, and also set the
+``Content-Type: application/json`` HTTP header.

flask/testing.py

@@ -13,6 +13,7 @@
 from contextlib import contextmanager
 from werkzeug.test import Client, EnvironBuilder
 from flask import _request_ctx_stack
+from flask.json import dumps as json_dumps
 
 try:
     from werkzeug.urls import url_parse
@@ -33,6 +34,16 @@ def make_test_environ_builder(app, path='/', base_url=None, *args, **kwargs):
             path = url.path
             if url.query:
                 path += '?' + url.query
+
+    if 'json' in kwargs:
+        if 'data' in kwargs:
+            raise ValueError('Client cannot provide both `json` and `data`')
+        kwargs['data'] = json_dumps(kwargs.pop('json'))
+
+        # Only set Content-Type when not explicitly provided
+        if 'content_type' not in kwargs:
+            kwargs['content_type'] = 'application/json'
+
     return EnvironBuilder(path, base_url, *args, **kwargs)
 
 

flask/wrappers.py

@@ -13,19 +13,110 @@
 from werkzeug.exceptions import BadRequest
 
 from . import json
-from .globals import _request_ctx_stack
+from .globals import _app_ctx_stack
 
-_missing = object()
 
+class JSONMixin(object):
+    """Common mixin for both request and response objects to provide JSON
+    parsing capabilities.
 
-def _get_data(req, cache):
-    getter = getattr(req, 'get_data', None)
-    if getter is not None:
-        return getter(cache=cache)
-    return req.data
+    .. versionadded:: 0.12
+    """
+
+    @property
+    def is_json(self):
+        """Indicates if this request/response is in JSON format or not.  By
+        default it is considered to include JSON data if the mimetype is
+        :mimetype:`application/json` or :mimetype:`application/*+json`.
 
+        .. versionadded:: 1.0
+        """
+        mt = self.mimetype
+        if mt == 'application/json':
+            return True
+        if mt.startswith('application/') and mt.endswith('+json'):
+            return True
+        return False
+
+    @property
+    def json(self):
+        """If this request/response is in JSON format then this property will
+        contain the parsed JSON data.  Otherwise it will be ``None``.
+
+        The :meth:`get_json` method should be used instead.
+        """
+        from warnings import warn
+        warn(DeprecationWarning(
+            'json is deprecated.  Use get_json() instead.'), stacklevel=2)
+        return self.get_json()
+
+    def _get_data_for_json(self, cache):
+        getter = getattr(self, 'get_data', None)
+        if getter is not None:
+            return getter(cache=cache)
+        return self.data
+
+    def get_json(self, force=False, silent=False, cache=True):
+        """Parses the JSON request/response data and returns it.  By default
+        this function will return ``None`` if the mimetype is not
+        :mimetype:`application/json` but this can be overridden by the
+        ``force`` parameter. If parsing fails the
+        :meth:`on_json_loading_failed` method on the request object will be
+        invoked.
+
+        :param force: if set to ``True`` the mimetype is ignored.
+        :param silent: if set to ``True`` this method will fail silently
+                       and return ``None``.
+        :param cache: if set to ``True`` the parsed JSON data is remembered
+                      on the object.
+        """
+        try:
+            return getattr(self, '_cached_json')
+        except AttributeError:
+            pass
+
+        if not (force or self.is_json):
+            return None
+
+        # We accept MIME charset header against the specification as certain
+        # clients have been using this in the past.  For responses, we assume
+        # that if the response charset was set explicitly then the data had
+        # been encoded correctly as well.
+        charset = self.mimetype_params.get('charset')
+        try:
+            data = self._get_data_for_json(cache)
+            if charset is not None:
+                rv = json.loads(data, encoding=charset)
+            else:
+                rv = json.loads(data)
+        except ValueError as e:
+            if silent:
+                rv = None
+            else:
+                rv = self.on_json_loading_failed(e)
+        if cache:
+            self._cached_json = rv
+        return rv
+
+    def on_json_loading_failed(self, e):
+        """Called if decoding of the JSON data failed.  The return value of
+        this method is used by :meth:`get_json` when an error occurred.  The
+        default implementation just raises a :class:`BadRequest` exception.
+
+        .. versionchanged:: 0.10
+           Removed buggy previous behavior of generating a random JSON
+           response.  If you want that behavior back you can trivially
+           add it by subclassing.
+
+        .. versionadded:: 0.8
+        """
+        ctx = _app_ctx_stack.top
+        if ctx is not None and ctx.app.debug:
+            raise BadRequest('Failed to decode JSON object: {0}'.format(e))
+        raise BadRequest()
 
-class Request(RequestBase):
+
+class Request(RequestBase, JSONMixin):
     """The request object used by default in Flask.  Remembers the
     matched endpoint and view arguments.
 
@@ -62,7 +153,7 @@ class Request(RequestBase):
     @property
     def max_content_length(self):
         """Read-only view of the ``MAX_CONTENT_LENGTH`` config key."""
-        ctx = _request_ctx_stack.top
+        ctx = _app_ctx_stack.top
         if ctx is not None:
             return ctx.app.config['MAX_CONTENT_LENGTH']
 
@@ -95,104 +186,19 @@ def blueprint(self):
         if self.url_rule and '.' in self.url_rule.endpoint:
             return self.url_rule.endpoint.rsplit('.', 1)[0]
 
-    @property
-    def json(self):
-        """If the mimetype is :mimetype:`application/json` this will contain the
-        parsed JSON data.  Otherwise this will be ``None``.
-
-        The :meth:`get_json` method should be used instead.
-        """
-        from warnings import warn
-        warn(DeprecationWarning('json is deprecated.  '
-                                'Use get_json() instead.'), stacklevel=2)
-        return self.get_json()
-
-    @property
-    def is_json(self):
-        """Indicates if this request is JSON or not.  By default a request
-        is considered to include JSON data if the mimetype is
-        :mimetype:`application/json` or :mimetype:`application/*+json`.
-
-        .. versionadded:: 0.11
-        """
-        mt = self.mimetype
-        if mt == 'application/json':
-            return True
-        if mt.startswith('application/') and mt.endswith('+json'):
-            return True
-        return False
-
-    def get_json(self, force=False, silent=False, cache=True):
-        """Parses the incoming JSON request data and returns it.  By default
-        this function will return ``None`` if the mimetype is not
-        :mimetype:`application/json` but this can be overridden by the
-        ``force`` parameter. If parsing fails the
-        :meth:`on_json_loading_failed` method on the request object will be
-        invoked.
-
-        :param force: if set to ``True`` the mimetype is ignored.
-        :param silent: if set to ``True`` this method will fail silently
-                       and return ``None``.
-        :param cache: if set to ``True`` the parsed JSON data is remembered
-                      on the request.
-        """
-        rv = getattr(self, '_cached_json', _missing)
-        if rv is not _missing:
-            return rv
-
-        if not (force or self.is_json):
-            return None
-
-        # We accept a request charset against the specification as
-        # certain clients have been using this in the past.  This
-        # fits our general approach of being nice in what we accept
-        # and strict in what we send out.
-        request_charset = self.mimetype_params.get('charset')
-        try:
-            data = _get_data(self, cache)
-            if request_charset is not None:
-                rv = json.loads(data, encoding=request_charset)
-            else:
-                rv = json.loads(data)
-        except ValueError as e:
-            if silent:
-                rv = None
-            else:
-                rv = self.on_json_loading_failed(e)
-        if cache:
-            self._cached_json = rv
-        return rv
-
-    def on_json_loading_failed(self, e):
-        """Called if decoding of the JSON data failed.  The return value of
-        this method is used by :meth:`get_json` when an error occurred.  The
-        default implementation just raises a :class:`BadRequest` exception.
-
-        .. versionchanged:: 0.10
-           Removed buggy previous behavior of generating a random JSON
-           response.  If you want that behavior back you can trivially
-           add it by subclassing.
-
-        .. versionadded:: 0.8
-        """
-        ctx = _request_ctx_stack.top
-        if ctx is not None and ctx.app.config.get('DEBUG', False):
-            raise BadRequest('Failed to decode JSON object: {0}'.format(e))
-        raise BadRequest()
-
     def _load_form_data(self):
         RequestBase._load_form_data(self)
 
         # In debug mode we're replacing the files multidict with an ad-hoc
         # subclass that raises a different error for key errors.
-        ctx = _request_ctx_stack.top
+        ctx = _app_ctx_stack.top
         if ctx is not None and ctx.app.debug and \
            self.mimetype != 'multipart/form-data' and not self.files:
             from .debughelpers import attach_enctype_error_multidict
             attach_enctype_error_multidict(self)
 
 
-class Response(ResponseBase):
+class Response(ResponseBase, JSONMixin):
     """The response object that is used by default in Flask.  Works like the
     response object from Werkzeug but is set to have an HTML mimetype by
     default.  Quite often you don't have to create this object yourself because

tests/test_testing.py

@@ -13,6 +13,7 @@
 import flask
 
 from flask._compat import text_type
+from flask.json import jsonify
 
 
 def test_environ_defaults_from_config():
@@ -203,6 +204,27 @@ def action():
         assert 'gin' in flask.request.form
         assert 'vodka' in flask.request.args
 
+def test_json_request_and_response():
+    app = flask.Flask(__name__)
+    app.testing = True
+
+    @app.route('/echo', methods=['POST'])
+    def echo():
+        return jsonify(flask.request.json)
+
+    with app.test_client() as c:
+        json_data = {'drink': {'gin': 1, 'tonic': True}, 'price': 10}
+        rv = c.post('/echo', json=json_data)
+
+        # Request should be in JSON
+        assert flask.request.is_json
+        assert flask.request.get_json() == json_data
+
+        # Response should be in JSON
+        assert rv.status_code == 200
+        assert rv.is_json
+        assert rv.get_json() == json_data
+
 def test_subdomain():
     app = flask.Flask(__name__)
     app.config['SERVER_NAME'] = 'example.com'