falcon's testing module is a functional testing framework for falcon apps. it contains various test classes and utility functions to support functional testing. the testing framework supports both unittest and pytest.

we shall use following the script (myapp.py) to demonstrate testing functionality. it contains a helloresource class with an on_get() responder that renders a json response of hello world. the create() function returns falcon's application object added with a route registered with '/' url.

from waitress import serve
import falcon
import json
class helloresource:
   def on_get(self, req, resp):
      """handles get requests"""
      resp.text=json.dumps({"message":"hello world"})

   # this is the default status
   resp.status = falcon.http_200

   # default is json, so override
   resp.content_type = falcon.media_json 
def create():
   app = falcon.app()
   hello = helloresource()
   app.add_route('/', hello)
   return app
app=create()
if __name__ == '__main__':
   serve(app, host='0.0.0.0', port=8000)

using unittest

the testing.testcase extends unittest to facilitate functional testing of wsgi/asgi applications written with falcon. we need to inherit from this base class and write the tests.

the test functions in the testcase subclass are of the name simulate_*() where '*' stands for http methods like get, post etc. it means, we have to fetch the result of simulate_get() function and compare it with the expected result by assertion functions.

the simulate_*() functions receive two arguments.

simulate_*(app, route)

following is the code for test-myapp.py. it executes simulate_get() function and asserts its result with the anticipated result and indicates whether the test has failed or passed.

from falcon import testing
import myapp
class mytestcase(testing.testcase):
   def setup(self):
      super(mytestcase, self).setup()
      self.app = myapp.create()
class testmyapp(mytestcase):
   def test_get_message(self):
      doc = {'message': 'hello world!'}
      result = self.simulate_get('/')
      self.assertequal(result.json, doc)
if '__name__'=='__main__':
   unittest.main()

run the above test with the help of the following command −

python -m unittest test-myapp.py
f
==============================================================
fail: test_get_message (test-myapp.testmyapp)
--------------------------------------------------------------
traceback (most recent call last):
   file "e:\falconenv\test-myapp.py", line 17, in test_get_message
   self.assertequal(result.json, doc)
assertionerror: {'message': 'hello world'} != {'message':
'hello world!'}
- {'message': 'hello world'}
? ^
+ {'message': 'hello world!'}
? ^ +
--------------------------------------------------------------
ran 1 test in 0.019s
failed (failures=1)

using pytest

to perform testing using pytest framework, you need to install it using pip utility.

pip3 install pytest

to run a test function, we need an object of testing.testclient class. it simulates the requests for wsgi and asgi applications. this object is first obtained by giving falcon application object as the argument.

we run the simulate_*() functions and assert its result with the anticipated output to decide whether the test has failed or passed. in both the examples, the test fails because of difference in case of 'w' in hello world message. the responder returns it with uppercase 'w' whereas the test function has it in lowercase.

from falcon import testing
import pytest
import myapp
@pytest.fixture()
def client():
   return testing.testclient(myapp.create())
def test_get_message(client):
   doc = {'message': 'hello world!'}
   result = client.simulate_get('/')
   assert result.json == doc

run the above test using the following command −

pytest test-myapp.py v
=========== test session starts ==========================
platform win32 -- python 3.8.6, pytest-7.1.2, pluggy-1.0.0 --
e:\falconenv\scripts\python.exe
cachedir: .pytest_cache
rootdir: e:\falconenv
plugins: anyio-3.5.0
collected 1 item
test-myapp.py::test_get_message failed
[100%]
==================== failures =======================
_____________________________________________________
test_get_message
_____________________________________________________
client = <falcon.testing.client.testclient object at 0x0000000003eaa6a0>
def test_get_message(client):
   doc = {'message': 'hello world!'}
   result = client.simulate_get('/')
> assert result.json == doc
e assertionerror: assert {'message': 'hello world'} ==
{'message': 'hello world!'}
e differing items:
e {'message': 'hello world'} != {'message': 'hello world!'}
e full diff:
e - {'message': 'hello world!'}
e ? ^ -
e + {'message': 'hello world'}
e ? ^
test-myapp.py:42: assertionerror
============ short test summary info ==================
failed test-myapp.py::test_get_message - assertionerror:
assert {'message': 'hello world'} == {'message': 'hello
world!'}
============ 1 failed in 4.11s ========================

Save or share this article