Testing Flask Applications

    We will use the pytest framework to set up and run our tests.

    The goes over how to write tests for 100% coverage of the sample Flaskr blog application. See the tutorial on tests for a detailed explanation of specific tests for an application.

    Tests are typically located in the folder. Tests are functions that start with test_, in Python modules that start with test_. Tests can also be further grouped in classes that start with Test.

    It can be difficult to know what to test. Generally, try to test the code that you write, not the code of libraries that you use, since they are already tested. Try to extract complex behaviors as separate functions to test individually.

    Fixtures

    Pytest fixtures allow writing pieces of code that are reusable across tests. A simple fixture returns a value, but a fixture can also do setup, yield a value, then do teardown. Fixtures for the application, test client, and CLI runner are shown below, they can be placed in tests/conftest.py.

    If you’re using an application factory, define an app fixture to create and configure an app instance. You can add code before and after the yield to set up and tear down other resources, such as creating and clearing a database.

    If you’re not using a factory, you already have an app object you can import and configure directly. You can still use an app fixture to set up and tear down resources.

    1. import pytest
    2. from my_project import create_app
    4. @pytest.fixture()
    5. def app():
    6.     app = create_app()
    7.     app.config.update({
    8.         "TESTING": True,
    9.     })
    11.     # other setup can go here
    13.     yield app
    15.     # clean up / reset resources here
    18. @pytest.fixture()
    19. def client(app):
    20.     return app.test_client()
    22. @pytest.fixture()
    23. def runner(app):
    24.     return app.test_cli_runner()

    The test client makes requests to the application without running a live server. Flask’s client extends , see those docs for additional information.

    To make a request, call the method the request should use with the path to the route to test. A TestResponse is returned to examine the response data. It has all the usual properties of a response object. You’ll usually look at response.data, which is the bytes returned by the view. If you want to use text, Werkzeug 2.1 provides , or use response.get_data(as_text=True).

    1. def test_request_example(client):
    2.     response = client.get("/posts")
    3.     assert b"<h2>Hello, World!</h2>" in response.data

    Pass a dict query_string={"key": "value", ...} to set arguments in the query string (after the ? in the URL). Pass a dict headers={} to set request headers.

    To send a request body in a POST or PUT request, pass a value to data. If raw bytes are passed, that exact body is used. Usually, you’ll pass a dict to set form data.

    To send form data, pass a dict to data. The Content-Type header will be set to multipart/form-data or application/x-www-form-urlencoded automatically.

    If a value is a file object opened for reading bytes ("rb" mode), it will be treated as an uploaded file. To change the detected filename and content type, pass a (file, filename, content_type) tuple. File objects will be closed after making the request, so they do not need to use the usual with open() as f: pattern.

    It can be useful to store files in a tests/resources folder, then use pathlib.Path to get files relative to the current test file.

    1. from pathlib import Path
    3. # get the resources folder in the tests folder
    4. resources = Path(__file__).parent / "resources"
    6. def test_edit_user(client):
    7.     response = client.post("/user/2/edit", data={
    8.         "name": "Flask",
    9.         "theme": "dark",
    10.         "picture": (resources / "picture.png").open("rb"),
    11.     })
    12.     assert response.status_code == 200

    JSON Data

    To send JSON data, pass an object to json. The Content-Type header will be set to application/json automatically.

    Similarly, if the response contains JSON data, the response.json attribute will contain the deserialized object.

    Following Redirects

    is a tuple of the responses that led up to the final response. Each response has a request attribute which records the request that produced that response.

    1. def test_logout_redirect(client):
    2.     response = client.get("/logout")
    3.     # Check that there was one redirect response.
    4.     assert len(response.history) == 1
    5.     # Check that the second request was to the index page.
    6.     assert response.request.path == "/index"

    To access Flask’s context variables, mainly , use the client in a with statement. The app and request context will remain active after making a request, until the block ends.

    1. from flask import session
    3. def test_access_session(client):
    4.     with client:
    5.         # session is still accessible
    6.         assert session["user_id"] == 1
    8.     # session is no longer accessible

    If you want to access or set a value in the session before making a request, use the client’s session_transaction() method in a with statement. It returns a session object, and will save the session once the block ends.

    1. from flask import session
    3. def test_modify_session(client):
    4.     with client.session_transaction() as session:
    5.         # set a user id without going through the login route
    6.         session["user_id"] = 1
    8.     # session is saved now
    10.     response = client.get("/users/me")
    11.     assert response.json["username"] == "flask"

    Running Commands with the CLI Runner

    Flask provides test_cli_runner() to create a , which runs CLI commands in isolation and captures the output in a Result object. Flask’s runner extends , see those docs for additional information.

    Use the runner’s invoke() method to call commands in the same way they would be called with the flask command from the command line.

    You may have functions that are called from views or commands, that expect an active or request context because they access request, session, or current_app. Rather than testing them by making a request or invoking the command, you can create and activate a context directly.

    Use with app.app_context() to push an application context. For example, database extensions usually require an active app context to make queries.

    1. def test_db_post_model(app):
    2.     with app.app_context():
    3.         post = db.session.query(Post).get(1)

    Use with app.test_request_context() to push a request context. It takes the same arguments as the test client’s request methods.

    1. def test_validate_user_edit(app):
    2.     with app.test_request_context(
    3.         "/user/2/edit", method="POST", data={"name": ""}
    4.     ):
    5.         # call a function that accesses `request`
    6.         messages = validate_edit_user()
    8.     assert messages["name"][0] == "Name cannot be empty."
    1. def test_auth_token(app):
    2.     with app.test_request_context("/user/2/edit", headers={"X-Auth-Token": "1"}):