test(testing): add POST request tests for the 'things_advanced' example (#2581)

* update to examples and FAQ

* update to examples and FAQ with corrections

Author: 0xMattB

README.rst

@@ -444,12 +444,12 @@ Note that this example assumes that the
     import uuid
     from wsgiref import simple_server
 
-    import falcon
     import requests
 
+    import falcon
+
 
     class StorageEngine:
-
         def get_things(self, marker, limit):
             return [{'id': str(uuid.uuid4()), 'color': 'green'}]
 
@@ -459,15 +459,13 @@ Note that this example assumes that the
 
 
     class StorageError(Exception):
-
         @staticmethod
-        def handle(ex, req, resp, params):
+        def handle(req, resp, ex, params):
             # TODO: Log the error, clean up, etc. before raising
             raise falcon.HTTPInternalServerError()
 
 
     class SinkAdapter:
-
         engines = {
             'ddg': 'https://duckduckgo.com',
             'y': 'https://search.yahoo.com/search',
@@ -478,54 +476,59 @@ Note that this example assumes that the
             params = {'q': req.get_param('q', True)}
             result = requests.get(url, params=params)
 
-            resp.status = str(result.status_code) + ' ' + result.reason
+            resp.status = falcon.code_to_http_status(result.status_code)
             resp.content_type = result.headers['content-type']
             resp.text = result.text
 
 
     class AuthMiddleware:
-
         def process_request(self, req, resp):
             token = req.get_header('Authorization')
             account_id = req.get_header('Account-ID')
 
             challenges = ['Token type="Fernet"']
 
             if token is None:
-                description = ('Please provide an auth token '
-                               'as part of the request.')
+                description = 'Please provide an auth token as part of the request.'
 
-                raise falcon.HTTPUnauthorized(title='Auth token required',
-                                              description=description,
-                                              challenges=challenges,
-                                              href='http://docs.example.com/auth')
+                raise falcon.HTTPUnauthorized(
+                    title='Auth token required',
+                    description=description,
+                    challenges=challenges,
+                    href='http://docs.example.com/auth',
+                )
 
             if not self._token_is_valid(token, account_id):
-                description = ('The provided auth token is not valid. '
-                               'Please request a new token and try again.')
+                description = (
+                    'The provided auth token is not valid. '
+                    'Please request a new token and try again.'
+                )
 
-                raise falcon.HTTPUnauthorized(title='Authentication required',
-                                              description=description,
-                                              challenges=challenges,
-                                              href='http://docs.example.com/auth')
+                raise falcon.HTTPUnauthorized(
+                    title='Authentication required',
+                    description=description,
+                    challenges=challenges,
+                    href='http://docs.example.com/auth',
+                )
 
         def _token_is_valid(self, token, account_id):
             return True  # Suuuuuure it's valid...
 
 
     class RequireJSON:
-
         def process_request(self, req, resp):
             if not req.client_accepts_json:
                 raise falcon.HTTPNotAcceptable(
                     description='This API only supports responses encoded as JSON.',
-                    href='http://docs.examples.com/api/json')
+                    href='http://docs.examples.com/api/json',
+                )
 
             if req.method in ('POST', 'PUT'):
                 if 'application/json' not in req.content_type:
                     raise falcon.HTTPUnsupportedMediaType(
                         title='This API only supports requests encoded as JSON.',
-                        href='http://docs.examples.com/api/json')
+                        href='http://docs.examples.com/api/json',
+                    )
 
 
     class JSONTranslator:
@@ -542,21 +545,24 @@ Note that this example assumes that the
                 # Nothing to do
                 return
 
-            body = req.stream.read()
+            body = req.bounded_stream.read()
             if not body:
-                raise falcon.HTTPBadRequest(title='Empty request body',
-                                            description='A valid JSON document is required.')
+                raise falcon.HTTPBadRequest(
+                    title='Empty request body',
+                    description='A valid JSON document is required.',
+                )
 
             try:
                 req.context.doc = json.loads(body.decode('utf-8'))
 
             except (ValueError, UnicodeDecodeError):
-                description = ('Could not decode the request body. The '
-                               'JSON was incorrect or not encoded as '
-                               'UTF-8.')
+                description = (
+                    'Could not decode the request body. The '
+                    'JSON was incorrect or not encoded as '
+                    'UTF-8.'
+                )
 
-                raise falcon.HTTPBadRequest(title='Malformed JSON',
-                                            description=description)
+                raise falcon.HTTPBadRequest(title='Malformed JSON', description=description)
 
         def process_response(self, req, resp, resource, req_succeeded):
             if not hasattr(resp.context, 'result'):
@@ -566,21 +572,22 @@ Note that this example assumes that the
 
 
     def max_body(limit):
-
         def hook(req, resp, resource, params):
             length = req.content_length
             if length is not None and length > limit:
-                msg = ('The size of the request is too large. The body must not '
-                       'exceed ' + str(limit) + ' bytes in length.')
+                msg = (
+                    'The size of the request is too large. The body must not '
+                    'exceed ' + str(limit) + ' bytes in length.'
+                )
 
                 raise falcon.HTTPContentTooLarge(
-                    title='Request body is too large', description=msg)
+                    title='Request body is too large', description=msg
+                )
 
         return hook
 
 
     class ThingsResource:
-
         def __init__(self, db):
             self.db = db
             self.logger = logging.getLogger('thingsapp.' + __name__)
@@ -594,14 +601,15 @@ Note that this example assumes that the
             except Exception as ex:
                 self.logger.error(ex)
 
-                description = ('Aliens have attacked our base! We will '
-                               'be back as soon as we fight them off. '
-                               'We appreciate your patience.')
+                description = (
+                    'Aliens have attacked our base! We will '
+                    'be back as soon as we fight them off. '
+                    'We appreciate your patience.'
+                )
 
                 raise falcon.HTTPServiceUnavailable(
-                    title='Service Outage',
-                    description=description,
-                    retry_after=30)
+                    title='Service Outage', description=description, retry_after=30
+                )
 
             # NOTE: Normally you would use resp.media for this sort of thing;
             # this example serves only to demonstrate how the context can be
@@ -619,19 +627,23 @@ Note that this example assumes that the
             except AttributeError:
                 raise falcon.HTTPBadRequest(
                     title='Missing thing',
-                    description='A thing must be submitted in the request body.')
+                    description='A thing must be submitted in the request body.',
+                )
 
             proper_thing = self.db.add_thing(doc)
 
             resp.status = falcon.HTTP_201
-            resp.location = '/%s/things/%s' % (user_id, proper_thing['id'])
+            resp.location = '/{}/things/{}'.format(user_id, proper_thing['id'])
+
 
     # Configure your WSGI server to load "things.app" (app is a WSGI callable)
-    app = falcon.App(middleware=[
-        AuthMiddleware(),
-        RequireJSON(),
-        JSONTranslator(),
-    ])
+    app = falcon.App(
+        middleware=[
+            AuthMiddleware(),
+            RequireJSON(),
+            JSONTranslator(),
+        ]
+    )
 
     db = StorageEngine()
     things = ThingsResource(db)

docs/user/faq.rst

@@ -1372,6 +1372,45 @@ To include multiple values, simply use ``"; "`` to separate each name-value
 pair. For example, if you were to pass ``{'Cookie': 'xxx=yyy; hello=world'}``,
 you would get ``{'cookies': {'xxx': 'yyy', 'hello': 'world'}}``.
 
+How can I set header fields when simulating requests?
+-----------------------------------------------------
+
+Default header fields can be overwritten to simulate unexpected
+behavior. For instance, to test the condition where a ``POST``
+request has an empty body but the value of ``Content-Length``
+is non-zero, we can overwrite that value in the header.
+
+.. code:: python
+
+    import falcon
+    import falcon.testing
+    import pytest
+
+    class PostTest:
+
+        def on_post(self, req, resp):
+            if req.content_length in (None, 0):
+                resp.status = falcon.HTTP_200
+            else:
+                if req.stream.read(req.content_length or 0):
+                    resp.status = falcon.HTTP_201
+                else:
+                    resp.status = falcon.HTTP_400
+
+    @pytest.fixture
+    def client():
+        app = falcon.App()
+        app.add_route('/resource', PostTest())
+
+        return falcon.testing.TestClient(app)
+
+
+    def test_post_empty_body_with_length(client):
+        headers = [('Content-Length', '1'),]
+        body = ''
+        result = client.simulate_post(path='/resource', body=body, headers=headers)
+        assert(result.status == falcon.HTTP_400)
+
 Why do I see no error tracebacks in my ASGI application?
 --------------------------------------------------------
 

examples/things_advanced.py

@@ -106,7 +106,7 @@ def process_request(self, req, resp):
             # Nothing to do
             return
 
-        body = req.stream.read()
+        body = req.bounded_stream.read()
         if not body:
             raise falcon.HTTPBadRequest(
                 title='Empty request body',

tests/test_examples.py

@@ -58,3 +58,23 @@ def test_things_advanced(asgi, util, httpx, requests):
     assert resp2.status_code == 200
     assert len(resp2.json) == 1
     assert resp2.json[0]['color'] == 'green'
+
+    resp3 = testing.simulate_post(
+        advanced.app,
+        '/1337/things',
+        headers={'Authorization': 'custom-token', 'Content-Type': 'application/json'},
+        body='{"key": "value"}',
+    )
+    assert resp3.status_code == 201
+
+    resp4 = testing.simulate_post(
+        advanced.app,
+        '/1337/things',
+        headers={
+            'Authorization': 'custom-token',
+            'Content-Type': 'application/json',
+            'Content-Length': '1',
+        },
+        body='',
+    )
+    assert resp4.status_code == 400